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 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 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​(Element element, Writer out, int indent, String indentWith, boolean hasChildren)`
  Writes a DOM tree to a stream.
  `String`
  `encode​(String value)`
  Escape <, >, &, ', " as their entities and drop characters that are illegal in XML documents.
  `String`
  `encodeAttributeValue​(String value)`
  Escape <, >, &, ', " as their entities, \n, \r and \t as numeric entities and drop characters that are illegal in XML documents.
  `void`
  `encodedata​(Writer out, String value)`
  Drop characters that are illegal in XML documents and write the rest to the given writer.
  `String`
  `encodedata​(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​(String ent)`
  Is the given argument a character or entity reference?
  `void`
  `openElement​(Element element, Writer out, int indent, String indentWith)`
  Writes the opening tag - including all attributes - corresponding to a DOM element.
  `void`
  `openElement​(Element element, Writer out, int indent, String indentWith, boolean hasChildren)`
  Writes the opening tag - including all attributes - corresponding to a DOM element.
  `void`
  `write​(Element root, OutputStream out)`
  Writes a DOM tree to a stream in UTF8 encoding.
  `void`
  `write​(Element element, Writer out, int indent, String indentWith)`
  Writes a DOM tree to a stream.
  `void`
  `writeXMLDeclaration​(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 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​(Element root, OutputStream out) throws 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:
      `IOException` - if an error happens while writing to the stream.

  - ### writeXMLDeclaration

    public void writeXMLDeclaration​(Writer wri) throws IOException
    Writes the XML declaration if xmlDeclaration is true.
    Parameters:
      `wri` - the writer to write to.
    Throws:
      `IOException` - if there is an error.
    Since:
      Ant 1.7.0

  - ### write

    public void write​(Element element, Writer out, int indent, String indentWith) throws 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:
      `IOException` - if an error happens while writing to the stream.

  - ### openElement

    public void openElement​(Element element, Writer out, int indent, String indentWith) throws 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:
      `IOException` - if an error happens while writing to the stream.

  - ### openElement

    public void openElement​(Element element, Writer out, int indent, String indentWith, boolean hasChildren) throws 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:
      `IOException` - if an error happens while writing to the stream.
    Since:
      Ant 1.7

  - ### closeElement

    public void closeElement​(Element element, Writer out, int indent, String indentWith, boolean hasChildren) throws 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:
      `IOException` - if an error happens while writing to the stream.

  - ### encode

    public String encode​(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 String encodeAttributeValue​(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 String encodedata​(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​(Writer out, String value) throws 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:
      `IOException` - if data cannot be written

  - ### isReference

    public boolean isReference​(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