net.sf.saxon.serialize

## Class XMLEmitter

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

- All Implemented Interfaces:
    Result, Receiver
  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 and Description
    --- | ---
    `protected CharacterReferenceGenerator` | `characterReferenceGenerator`
    `protected boolean` | `declarationIsWritten`
    `protected NodeName` | `elementCode`
    `protected Stack<String>` | `elementStack`
    `protected int` | `indentForNextAttribute`
    `protected boolean` | `openStartTag`
    `protected boolean` | `started`
    `protected boolean` | `startedElement`
    `protected boolean` | `undeclareNamespaces`

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

      `allCharactersEncodable, characterSet, namePool, outputProperties, outputStream, pipelineConfig, streamResult, systemId, writer`

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

      `PI_DISABLE_OUTPUT_ESCAPING, PI_ENABLE_OUTPUT_ESCAPING`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `XMLEmitter()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `attribute(NodeName nameCode, SimpleType typeCode, CharSequence value, int locationId, int properties)` Notify an attribute.
    `void` | `characters(CharSequence chars, int locationId, int properties)` Character data.
    `void` | `close()` End of the document.
    `void` | `closeStartTag()` Mark the end of the start tag
    `void` | `comment(CharSequence chars, int locationId, int properties)` Handle a comment.
    `protected String` | `emptyElementTagCloser(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 String` | `getAttributeIndentString()`
    `void` | `namespace(NamespaceBinding namespaceBinding, int properties)` Notify a namespace.
    `void` | `open()` Start of the event stream.
    `protected void` | `openDocument()` Do the real work of starting the document.
    `void` | `processingInstruction(String target, CharSequence data, int 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(Boolean escape)` Say that all non-ASCII characters should be escaped, regardless of the character encoding
    `void` | `setIndentForNextAttribute(int indent)`
    `void` | `startContent()` Notify the start of the content, that is, the completion of all attributes and namespaces.
    `void` | `startDocument(int properties)` Start of a document node.
    `void` | `startElement(NodeName elemName, SchemaType typeCode, int locationId, int properties)` Start of an element.
    `protected int` | `testCharacters(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, String attname, CharSequence value, int properties)` Write attribute name=value pair.
    `void` | `writeCharSequence(CharSequence s)` Write a CharSequence (without any escaping of special characters): various implementations
    `void` | `writeDeclaration()` Output the XML declaration
    `protected void` | `writeDocType(NodeName name, String displayName, String systemId, String publicId)` Output the document type declaration
    `protected boolean` | `writeDocTypeWithNullSystemId()`
    `protected void` | `writeEscape(CharSequence chars, boolean inAttribute)` Write contents of array to current writer, after escaping special characters.

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

      `getConfiguration, getOutputProperties, getOutputStream, getPipelineConfiguration, getSystemId, getWriter, makeOutputStream, makeWriter, setOutputProperties, setOutputStream, setPipelineConfiguration, setStreamResult, setSystemId, setUnparsedEntity, setWriter, usesWriter`

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

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

- - ### Field Detail

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

    - #### elementStack

          protected Stack<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(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.
      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` - bit-significant integer indicating properties of the document node. The definitions of the bits are in class `ReceiverOptions`
      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` - f 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,
                          String displayName,
                          String systemId,
                          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 DOCTYP 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 typeCode,
                          int locationId,
                          int properties)
                            throws XPathException

      Start of an element. Output the start tag, escaping special characters.
      Parameters:
        `elemName` - the name of the element.
        `typeCode` - the type annotation of the element.
        `locationId` - an integer which can be interpreted using a `LocationProvider` to return information such as line number and system ID. If no location information is available, the value zero is supplied.
        `properties` - bit-significant properties of the element node. If there are no revelant properties, zero is supplied. The definitions of the bits are in class `ReceiverOptions`
      Throws:
        `XPathException` - if an error occurs

    - #### writeDocTypeWithNullSystemId

          protected boolean writeDocTypeWithNullSystemId()

    - #### namespace

          public void namespace(NamespaceBinding namespaceBinding,
                       int properties)
                         throws XPathException

      Description copied from interface: `Receiver`
      Notify a namespace. Namespaces are notified after the startElement event, and before any children for the element. The namespaces that are reported are only required to include those that are different from the parent element. The events represent namespace declarations and undeclarations rather than in-scope namespace nodes: an undeclaration is represented by a namespace code of zero. If the sequence of namespace events contains two A namespace must not conflict with any namespaces already used for element or attribute names.
      Parameters:
        `namespaceBinding` - contains the namespace prefix and namespace URI
        `properties` - The most important property is REJECT_DUPLICATES. If this property is set, the namespace declaration will be rejected if it conflicts with a previous declaration of the same prefix. If the property is not set, the namespace declaration will be ignored if it conflicts with a previous declaration. This reflects the fact that when copying a tree, namespaces for child elements are emitted before the namespaces of their parent element. Unfortunately this conflicts with the XSLT rule for complex content construction, where the recovery action in the event of conflicts is to take the namespace that comes last. XSLT therefore doesn't recover from this error:
      Throws:
        `XPathException` - if an error occurs

    - #### setIndentForNextAttribute

          public void setIndentForNextAttribute(int indent)

    - #### attribute

          public void attribute(NodeName nameCode,
                       SimpleType typeCode,
                       CharSequence value,
                       int locationId,
                       int properties)
                         throws XPathException

      Description copied from interface: `Receiver`
      Notify an attribute. Attributes are notified after the startElement event, and before any children. Namespaces and attributes may be intermingled.
      Parameters:
        `nameCode` - The name of the attribute
        `typeCode` - The type of the attribute, as held in the name pool. The additional bit NodeInfo.IS_DTD_TYPE may be set to indicate a DTD-derived type.
        `value` - the string value of the attribute
        `locationId` - an integer which can be interpreted using a `LocationProvider` to return information such as line number and system ID. If no location information is available, the value zero is supplied.
        `properties` - Bit significant value. The following bits are defined:
      DISABLE_ESCAPING
        Disable escaping for this attribute
      NO_SPECIAL_CHARACTERS
        Attribute value contains no special characters
      Throws:
        `XPathException` - if an error occurs

    - #### getAttributeIndentString

          protected String getAttributeIndentString()

    - #### startContent

          public void startContent()
                            throws XPathException

      Description copied from interface: `Receiver`
      Notify the start of the content, that is, the completion of all attributes and namespaces. Note that the initial receiver of output from XSLT instructions will not receive this event, it has to detect it itself. Note that this event is reported for every element even if it has no attributes, no namespaces, and no content.
      Throws:
        `XPathException` - if an error occurs

    - #### closeStartTag

          public void closeStartTag()
                             throws XPathException

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

    - #### emptyElementTagCloser

          protected String emptyElementTagCloser(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,
                            String attname,
                            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(CharSequence chars)
                                throws XPathException

      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
      Throws:
        `XPathException`

    - #### endElement

          public void endElement()
                          throws XPathException

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

    - #### characters

          public void characters(CharSequence chars,
                        int locationId,
                        int properties)
                          throws XPathException

      Character data.
      Parameters:
        `chars` - The characters
        `locationId` - an integer which can be interpreted using a `LocationProvider` to return information such as line number and system ID. If no location information is available, the value zero is supplied.
        `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(CharSequence s)
                                 throws IOException

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

    - #### processingInstruction

          public void processingInstruction(String target,
                                   CharSequence data,
                                   int 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` - an integer which can be interpreted using a `LocationProvider` to return information such as line number and system ID. If no location information is available, the value zero is supplied.
        `properties` - Additional information about the PI.
      Throws:
        `XPathException` - if an error occurs

    - #### writeEscape

          protected void writeEscape(CharSequence chars,
                         boolean inAttribute)
                              throws 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:
        `IOException`
        `XPathException`

    - #### comment

          public void comment(CharSequence chars,
                     int locationId,
                     int properties)
                       throws XPathException

      Handle a comment.
      Parameters:
        `chars` - The content of the comment
        `locationId` - an integer which can be interpreted using a `LocationProvider` to return information such as line number and system ID. If no location information is available, the value zero is supplied.
        `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

Copyright (c) 2004-2013 Saxonica Limited. All rights reserved.