Package net.sf.saxon.serialize

## Class XMLEmitter

- java.lang.Object
- - net.sf.saxon.event.SequenceReceiver
  - - net.sf.saxon.serialize.Emitter
    - - net.sf.saxon.serialize.XMLEmitter

- All Implemented Interfaces:
    `javax.xml.transform.Result`, `Receiver`, `ReceiverWithOutputProperties`
  Direct Known Subclasses:
    `HTMLEmitter`, `MessageEmitter`, `MessageWarner`, `TEXTEmitter`, `XHTML1Emitter`, `XHTML5Emitter`, `XQueryEmitter`

      public class XMLEmitter
      extends Emitter

  XMLEmitter is an Emitter that generates XML output to a specified destination.

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected boolean[]` | `attSpecials` |
    `protected boolean` | `canonical` |
    `protected CharacterReferenceGenerator` | `characterReferenceGenerator` |
    `protected boolean` | `declarationIsWritten` |
    `protected char` | `delimiter` |
    `protected NodeName` | `elementCode` |
    `protected java.util.Stack<java.lang.String>` | `elementStack` |
    `protected int` | `indentForNextAttribute` |
    `protected boolean` | `openStartTag` |
    `protected boolean` | `started` |
    `protected boolean` | `startedElement` |
    `protected boolean` | `undeclareNamespaces` |
    `protected boolean` | `unfailing` |

    - ### Fields inherited from class net.sf.saxon.serialize.Emitter

      `allCharactersEncodable, characterSet, outputProperties, outputStream, streamResult, writer`

    - ### Fields inherited from class net.sf.saxon.event.SequenceReceiver

      `pipelineConfiguration, previousAtomic, systemId`

    - ### Fields inherited from interface javax.xml.transform.Result

      `PI_DISABLE_OUTPUT_ESCAPING, PI_ENABLE_OUTPUT_ESCAPING`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `XMLEmitter()` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `characters​(java.lang.CharSequence chars, Location locationId, int properties)` | Character data.
    `void` | `close()` | End of the document.
    `void` | `closeStartTag()` | Mark the end of the start tag
    `void` | `comment​(java.lang.CharSequence chars, Location locationId, int properties)` | Handle a comment.
    `protected java.lang.String` | `convertToAscii​(java.lang.CharSequence chars)` | Where characters are not available in the selected encoding, substitute them
    `protected java.lang.String` | `emptyElementTagCloser​(java.lang.String displayName, NodeName nameCode)` | Close an empty element tag.
    `void` | `endDocument()` | Notify the end of a document node
    `void` | `endElement()` | End of an element.
    `protected java.lang.String` | `getAttributeIndentString()` |
    `boolean` | `isStarted()` | Ask whether anything has yet been written
    `void` | `namespace​(java.lang.String nsprefix, java.lang.String nsuri, boolean isFirst)` |
    `void` | `open()` | Start of the event stream.
    `protected void` | `openDocument()` | Do the real work of starting the document.
    `void` | `processingInstruction​(java.lang.String target, java.lang.CharSequence data, Location locationId, int properties)` | Handle a processing instruction.
    `void` | `setCharacterReferenceGenerator​(CharacterReferenceGenerator generator)` | Set the character reference generator to be used for generating hexadecimal or decimal character references
    `void` | `setEscapeNonAscii​(java.lang.Boolean escape)` | Say that all non-ASCII characters should be escaped, regardless of the character encoding
    `void` | `setIndentForNextAttribute​(int indent)` | Set the indentation to be used for attributes (this excludes the length of the element name itself)
    `void` | `startDocument​(int properties)` | Start of a document node.
    `void` | `startElement​(NodeName elemName, SchemaType type, AttributeMap attributes, NamespaceMap namespaces, Location location, int properties)` | Start of an element.
    `protected int` | `testCharacters​(java.lang.CharSequence chars)` | Test that all characters in a name (for example) are supported in the target encoding.
    `boolean` | `usesTypeAnnotations()` | Ask whether this Receiver (or the downstream pipeline) makes any use of the type annotations supplied on element and attribute events
    `protected void` | `writeAttribute​(NodeName elCode, java.lang.String attname, java.lang.CharSequence value, int properties)` | Write attribute name=value pair.
    `void` | `writeCharSequence​(java.lang.CharSequence s)` | Write a CharSequence (without any escaping of special characters): various implementations
    `void` | `writeDeclaration()` | Output the XML declaration
    `protected void` | `writeDocType​(NodeName name, java.lang.String displayName, java.lang.String systemId, java.lang.String publicId)` | Output the document type declaration
    `protected boolean` | `writeDocTypeWithNullSystemId()` |
    `protected void` | `writeEscape​(java.lang.CharSequence chars, boolean inAttribute)` | Write contents of array to current writer, after escaping special characters.

    - ### Methods inherited from class net.sf.saxon.serialize.Emitter

      `append, getOutputProperties, getOutputStream, getWriter, makeOutputStream, makeWriter, setOutputProperties, setOutputStream, setStreamResult, setUnparsedEntity, setWriter, usesWriter`

    - ### Methods inherited from class net.sf.saxon.event.SequenceReceiver

      `append, decompose, flatten, getConfiguration, getErrorCodeForDecomposingFunctionItems, getNamePool, getPipelineConfiguration, getSystemId, handlesAppend, setPipelineConfiguration, setSystemId`

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

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

    - ### Methods inherited from interface net.sf.saxon.event.Receiver

      `append, getPipelineConfiguration, handlesAppend, setPipelineConfiguration, setSystemId`

    - ### Methods inherited from interface javax.xml.transform.Result

      `getSystemId`

- - ### Field Detail

    - #### canonical

          protected boolean canonical

    - #### started

          protected boolean started

    - #### startedElement

          protected boolean startedElement

    - #### openStartTag

          protected boolean openStartTag

    - #### declarationIsWritten

          protected boolean declarationIsWritten

    - #### elementCode

          protected NodeName elementCode

    - #### indentForNextAttribute

          protected int indentForNextAttribute

    - #### undeclareNamespaces

          protected boolean undeclareNamespaces

    - #### unfailing

          protected boolean unfailing

    - #### delimiter

          protected char delimiter

    - #### attSpecials

          protected boolean[] attSpecials

    - #### elementStack

          protected java.util.Stack<java.lang.String> elementStack

    - #### characterReferenceGenerator

          protected CharacterReferenceGenerator characterReferenceGenerator

  - ### Constructor Detail

    - #### XMLEmitter

          public XMLEmitter()

  - ### Method Detail

    - #### setCharacterReferenceGenerator

          public void setCharacterReferenceGenerator​(CharacterReferenceGenerator generator)

      Set the character reference generator to be used for generating hexadecimal or decimal character references
      Parameters:
        `generator` - the character reference generator to be used

    - #### setEscapeNonAscii

          public void setEscapeNonAscii​(java.lang.Boolean escape)

      Say that all non-ASCII characters should be escaped, regardless of the character encoding
      Parameters:
        `escape` - true if all non ASCII characters should be escaped

    - #### open

          public void open()
                    throws XPathException

      Start of the event stream. Nothing is done at this stage: the opening of the output file is deferred until some content is written to it.
      Specified by:
        `open` in interface `Receiver`
      Overrides:
        `open` in class `SequenceReceiver`
      Throws:
        `XPathException` - if an error occurs

    - #### startDocument

          public void startDocument​(int properties)
                             throws XPathException

      Start of a document node. Nothing is done at this stage: the opening of the output file is deferred until some content is written to it.
      Parameters:
        `properties` -
      Throws:
        `XPathException` - if an error occurs

    - #### endDocument

          public void endDocument()
                           throws XPathException

      Notify the end of a document node
      Throws:
        `XPathException` - if an error occurs

    - #### openDocument

          protected void openDocument()
                               throws XPathException

      Do the real work of starting the document. This happens when the first content is written.
      Throws:
        `XPathException` - if an error occurs opening the output file

    - #### writeDeclaration

          public void writeDeclaration()
                                throws XPathException

      Output the XML declaration
      Throws:
        `XPathException`

    - #### writeDocType

          protected void writeDocType​(NodeName name,
                                      java.lang.String displayName,
                                      java.lang.String systemId,
                                      java.lang.String publicId)
                               throws XPathException

      Output the document type declaration
      Parameters:
        `name` - the qualified name of the element
        `displayName` - The element name as displayed
        `systemId` - The DOCTYPE system identifier
        `publicId` - The DOCTYPE public identifier
      Throws:
        `XPathException` - if an error occurs writing to the output

    - #### close

          public void close()
                     throws XPathException

      End of the document.
      Specified by:
        `close` in interface `Receiver`
      Overrides:
        `close` in class `Emitter`
      Throws:
        `XPathException` - if an error occurs

    - #### startElement

          public void startElement​(NodeName elemName,
                                   SchemaType type,
                                   AttributeMap attributes,
                                   NamespaceMap namespaces,
                                   Location location,
                                   int properties)
                            throws XPathException

      Start of an element. Output the start tag, escaping special characters.
      Parameters:
        `elemName` - the name of the element.
        `type` - the type annotation of the element.
        `attributes` - the attributes of this element
        `namespaces` - the in-scope namespaces of this element: generally this is all the in-scope namespaces, without relying on inheriting namespaces from parent elements
        `location` - an object providing information about the module, line, and column where the node originated
        `properties` - bit-significant properties of the element node. If there are no relevant properties, zero is supplied. The definitions of the bits are in class `ReceiverOption`
      Throws:
        `XPathException` - if an error occurs

    - #### writeDocTypeWithNullSystemId

          protected boolean writeDocTypeWithNullSystemId()

    - #### namespace

          public void namespace​(java.lang.String nsprefix,
                                java.lang.String nsuri,
                                boolean isFirst)
                         throws XPathException

      Throws:
        `XPathException`

    - #### setIndentForNextAttribute

          public void setIndentForNextAttribute​(int indent)

      Set the indentation to be used for attributes (this excludes the length of the element name itself)
      Parameters:
        `indent` - the number of spaces to be output before each attribute (on a new line)

    - #### getAttributeIndentString

          protected java.lang.String getAttributeIndentString()

    - #### closeStartTag

          public void closeStartTag()
                             throws XPathException

      Mark the end of the start tag
      Throws:
        `XPathException` - if an IO exception occurs

    - #### emptyElementTagCloser

          protected java.lang.String emptyElementTagCloser​(java.lang.String displayName,
                                                           NodeName nameCode)

      Close an empty element tag. (This is overridden in XHTMLEmitter).
      Parameters:
        `displayName` - the name of the empty element
        `nameCode` - the fingerprint of the name of the empty element
      Returns:
        the string used to close an empty element tag.

    - #### writeAttribute

          protected void writeAttribute​(NodeName elCode,
                                        java.lang.String attname,
                                        java.lang.CharSequence value,
                                        int properties)
                                 throws XPathException

      Write attribute name=value pair.
      Parameters:
        `elCode` - The element name is not used in this version of the method, but is used in the HTML subclass.
        `attname` - The attribute name, which has already been validated to ensure it can be written in this encoding
        `value` - The value of the attribute
        `properties` - Any special properties of the attribute
      Throws:
        `XPathException` - if an error occurs

    - #### testCharacters

          protected int testCharacters​(java.lang.CharSequence chars)

      Test that all characters in a name (for example) are supported in the target encoding.
      Parameters:
        `chars` - the characters to be tested
      Returns:
        zero if all the characters are available, or the value of the first offending character if not

    - #### convertToAscii

          protected java.lang.String convertToAscii​(java.lang.CharSequence chars)

      Where characters are not available in the selected encoding, substitute them

    - #### endElement

          public void endElement()
                          throws XPathException

      End of an element.
      Throws:
        `XPathException` - if an error occurs

    - #### characters

          public void characters​(java.lang.CharSequence chars,
                                 Location locationId,
                                 int properties)
                          throws XPathException

      Character data.
      Parameters:
        `chars` - The characters
        `locationId` - provides information such as line number and system ID.
        `properties` - Bit significant value. The following bits are defined:
        DISABLE_ESCAPING
          Disable escaping for this text node
        USE_CDATA
          Output as a CDATA section
      Throws:
        `XPathException` - if an error occurs

    - #### writeCharSequence

          public void writeCharSequence​(java.lang.CharSequence s)
                                 throws java.io.IOException

      Write a CharSequence (without any escaping of special characters): various implementations
      Parameters:
        `s` - the character sequence to be written
      Throws:
        `java.io.IOException` - in the event of a failure to write to the output file

    - #### processingInstruction

          public void processingInstruction​(java.lang.String target,
                                            java.lang.CharSequence data,
                                            Location locationId,
                                            int properties)
                                     throws XPathException

      Handle a processing instruction.
      Parameters:
        `target` - The PI name. This must be a legal name (it will not be checked).
        `data` - The data portion of the processing instruction
        `locationId` - provides information such as line number and system ID.
        `properties` - Additional information about the PI.
      Throws:
        `XPathException` - if an error occurs

    - #### writeEscape

          protected void writeEscape​(java.lang.CharSequence chars,
                                     boolean inAttribute)
                              throws java.io.IOException,
                                     XPathException

      Write contents of array to current writer, after escaping special characters. This method converts the XML special characters (such as < and &) into their predefined entities.
      Parameters:
        `chars` - The character sequence containing the string
        `inAttribute` - Set to true if the text is in an attribute value
      Throws:
        `java.io.IOException`
        `XPathException`

    - #### comment

          public void comment​(java.lang.CharSequence chars,
                              Location locationId,
                              int properties)
                       throws XPathException

      Handle a comment.
      Parameters:
        `chars` - The content of the comment
        `locationId` - provides information such as line number and system ID.
        `properties` - Additional information about the comment.
      Throws:
        `XPathException` - if an error occurs

    - #### usesTypeAnnotations

          public boolean usesTypeAnnotations()

      Ask whether this Receiver (or the downstream pipeline) makes any use of the type annotations supplied on element and attribute events
      Specified by:
        `usesTypeAnnotations` in interface `Receiver`
      Overrides:
        `usesTypeAnnotations` in class `Emitter`
      Returns:
        true if the Receiver makes any use of this information. If false, the caller may supply untyped nodes instead of supplying the type annotation

    - #### isStarted

          public boolean isStarted()

      Ask whether anything has yet been written
      Returns:
        true if content has been output