DOMElementWriter (Apache Ant API)

Package 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 | Description
    --- | --- | ---
    `static class` | `DOMElementWriter.XmlNamespacePolicy` | Whether namespaces should be ignored for elements and attributes.

  - ### Field Summary

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

  - ### Constructor Summary

    Constructors
    Constructor | 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 Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | 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.
    `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.
    `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?
    `static boolean` | `isLegalXmlCharacter​(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 https://www.w3.org/TR/1998/REC-xml-19980210#charsets and 2.7 https://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 https://www.w3.org/TR/1998/REC-xml-19980210#charsets and 2.7 https://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 https://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

    - #### isLegalXmlCharacter

          public static boolean isLegalXmlCharacter​(char c)

      Is the given character allowed inside an XML document?

      See XML 1.0 2.2 https://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.10