DOMElementWriter (Apache Ant API)
Date: 2018-03-24

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

    All Methods Instance Methods Concrete 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.
    `void` | `encodedata(java.io.Writer out, java.lang.String value)` Drop characters that are illegal in XML documents and write the rest to the given writer.
    `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.

    - #### encodedata

          public void encodedata(java.io.Writer out,
                                 java.lang.String value)
                          throws java.io.IOException

      Drop characters that are illegal in XML documents and write the rest to the given writer.

      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.
        `out` - where to write the encoded data to.
      Throws:
        `java.io.IOException` - if data cannot be written

    - #### 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