DOMElementWriter (Apache Ant API)
Description: declaration: package: org.apache.tools.ant.util, class: DOMElementWriter

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

  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 Details

  - ### knownEntities

    protected java.lang.String[] knownEntities
    Don't try to be too smart but at least recognize the predefined entities.

- ## Constructor Details

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

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