org.apache.tools.ant.util

## Class DOMElementWriter

- java.lang.Object
- - org.apache.tools.ant.util.DOMElementWriter

-     public class DOMElementWriter
      extends java.lang.Object

  Writes a DOM tree to a given Writer. warning: this utility currently does not declare XML Namespaces.

  Utility class used by `XmlLogger` and org.apache.tools.ant.taskdefs.optional.junit.XMLJUnitResultFormatter XMLJUnitResultFormatter}.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `DOMElementWriter.XmlNamespacePolicy` Whether namespaces should be ignored for elements and attributes.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected java.lang.String[]` | `knownEntities` Don't try to be too smart but at least recognize the predefined entities.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `DOMElementWriter()` Create an element writer.
    `DOMElementWriter(boolean xmlDeclaration)` Create an element writer XML namespaces will be ignored.
    `DOMElementWriter(boolean xmlDeclaration, DOMElementWriter.XmlNamespacePolicy namespacePolicy)` Create an element writer XML namespaces will be ignored.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `closeElement(org.w3c.dom.Element element, java.io.Writer out, int indent, java.lang.String indentWith, boolean hasChildren)` Writes a DOM tree to a stream.
    `java.lang.String` | `encode(java.lang.String value)` Escape <, > & ', " as their entities and drop characters that are illegal in XML documents.
    `java.lang.String` | `encodeAttributeValue(java.lang.String value)` Escape <, > & ', " as their entities, \n, \r and \t as numeric entities and drop characters that are illegal in XML documents.
    `java.lang.String` | `encodedata(java.lang.String value)` Drop characters that are illegal in XML documents.
    `boolean` | `isLegalCharacter(char c)` Is the given character allowed inside an XML document?
    `boolean` | `isReference(java.lang.String ent)` Is the given argument a character or entity reference?
    `void` | `openElement(org.w3c.dom.Element element, java.io.Writer out, int indent, java.lang.String indentWith)` Writes the opening tag - including all attributes - corresponding to a DOM element.
    `void` | `openElement(org.w3c.dom.Element element, java.io.Writer out, int indent, java.lang.String indentWith, boolean hasChildren)` Writes the opening tag - including all attributes - corresponding to a DOM element.
    `void` | `write(org.w3c.dom.Element root, java.io.OutputStream out)` Writes a DOM tree to a stream in UTF8 encoding.
    `void` | `write(org.w3c.dom.Element element, java.io.Writer out, int indent, java.lang.String indentWith)` Writes a DOM tree to a stream.
    `void` | `writeXMLDeclaration(java.io.Writer wri)` Writes the XML declaration if xmlDeclaration is true.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### knownEntities

          protected java.lang.String[] knownEntities

      Don't try to be too smart but at least recognize the predefined entities.

  - ### Constructor Detail

    - #### DOMElementWriter

          public DOMElementWriter()

      Create an element writer. The ?xml? declaration will be included, namespaces ignored.

    - #### DOMElementWriter

          public DOMElementWriter(boolean xmlDeclaration)

      Create an element writer XML namespaces will be ignored.
      Parameters:
        `xmlDeclaration` - flag to indicate whether the ?xml? declaration should be included.
      Since:
        Ant1.7

    - #### DOMElementWriter

          public DOMElementWriter(boolean xmlDeclaration,
                          DOMElementWriter.XmlNamespacePolicy namespacePolicy)

      Create an element writer XML namespaces will be ignored.
      Parameters:
        `xmlDeclaration` - flag to indicate whether the ?xml? declaration should be included.
        `namespacePolicy` - the policy to use.
      Since:
        Ant1.7

  - ### Method Detail

    - #### write

          public void write(org.w3c.dom.Element root,
                   java.io.OutputStream out)
                     throws java.io.IOException

      Writes a DOM tree to a stream in UTF8 encoding. Note that it prepends the <?xml version='1.0' encoding='UTF-8'?> if the xmlDeclaration field is true. The indent number is set to 0 and a 2-space indent.
      Parameters:
        `root` - the root element of the DOM tree.
        `out` - the outputstream to write to.
      Throws:
        `java.io.IOException` - if an error happens while writing to the stream.

    - #### writeXMLDeclaration

          public void writeXMLDeclaration(java.io.Writer wri)
                                   throws java.io.IOException

      Writes the XML declaration if xmlDeclaration is true.
      Parameters:
        `wri` - the writer to write to.
      Throws:
        `java.io.IOException` - if there is an error.
      Since:
        Ant 1.7.0

    - #### write

          public void write(org.w3c.dom.Element element,
                   java.io.Writer out,
                   int indent,
                   java.lang.String indentWith)
                     throws java.io.IOException

      Writes a DOM tree to a stream.
      Parameters:
        `element` - the Root DOM element of the tree
        `out` - where to send the output
        `indent` - number of
        `indentWith` - string that should be used to indent the corresponding tag.
      Throws:
        `java.io.IOException` - if an error happens while writing to the stream.

    - #### openElement

          public void openElement(org.w3c.dom.Element element,
                         java.io.Writer out,
                         int indent,
                         java.lang.String indentWith)
                           throws java.io.IOException

      Writes the opening tag - including all attributes - corresponding to a DOM element.
      Parameters:
        `element` - the DOM element to write
        `out` - where to send the output
        `indent` - number of
        `indentWith` - string that should be used to indent the corresponding tag.
      Throws:
        `java.io.IOException` - if an error happens while writing to the stream.

    - #### openElement

          public void openElement(org.w3c.dom.Element element,
                         java.io.Writer out,
                         int indent,
                         java.lang.String indentWith,
                         boolean hasChildren)
                           throws java.io.IOException

      Writes the opening tag - including all attributes - corresponding to a DOM element.
      Parameters:
        `element` - the DOM element to write
        `out` - where to send the output
        `indent` - number of
        `indentWith` - string that should be used to indent the corresponding tag.
        `hasChildren` - whether this element has children.
      Throws:
        `java.io.IOException` - if an error happens while writing to the stream.
      Since:
        Ant 1.7

    - #### closeElement

          public void closeElement(org.w3c.dom.Element element,
                          java.io.Writer out,
                          int indent,
                          java.lang.String indentWith,
                          boolean hasChildren)
                            throws java.io.IOException

      Writes a DOM tree to a stream.
      Parameters:
        `element` - the Root DOM element of the tree
        `out` - where to send the output
        `indent` - number of
        `indentWith` - string that should be used to indent the corresponding tag.
        `hasChildren` - if true indent.
      Throws:
        `java.io.IOException` - if an error happens while writing to the stream.

    - #### encode

          public java.lang.String encode(java.lang.String value)

      Escape <, > & ', " as their entities and drop characters that are illegal in XML documents.
      Parameters:
        `value` - the string to encode.
      Returns:
        the encoded string.

    - #### encodeAttributeValue

          public java.lang.String encodeAttributeValue(java.lang.String value)

      Escape <, > & ', " as their entities, \n, \r and \t as numeric entities and drop characters that are illegal in XML documents.
      Parameters:
        `value` - the string to encode.
      Returns:
        the encoded string.

    - #### encodedata

          public java.lang.String encodedata(java.lang.String value)

      Drop characters that are illegal in XML documents.

      Also ensure that we are not including an `]]>` marker by replacing that sequence with `&#x5d;&#x5d;&gt;`.

      See XML 1.0 2.2 http://www.w3.org/TR/1998/REC-xml-19980210#charsets and 2.7 http://www.w3.org/TR/1998/REC-xml-19980210#sec-cdata-sect.

      Parameters:
        `value` - the value to be encoded.
      Returns:
        the encoded value.

    - #### isReference

          public boolean isReference(java.lang.String ent)

      Is the given argument a character or entity reference?
      Parameters:
        `ent` - the value to be checked.
      Returns:
        true if it is an entity.

    - #### isLegalCharacter

          public boolean isLegalCharacter(char c)

      Is the given character allowed inside an XML document?

      See XML 1.0 2.2 http://www.w3.org/TR/1998/REC-xml-19980210#charsets.

      Parameters:
        `c` - the character to test.
      Returns:
        true if the character is allowed.
      Since:
        1.10, Ant 1.5