Package net.sf.saxon.serialize

## Class Emitter

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

- All Implemented Interfaces:
    `javax.xml.transform.Result`, `Receiver`, `ReceiverWithOutputProperties`
  Direct Known Subclasses:
    `BinaryEmitter`, `XMLEmitter`

      public abstract class Emitter
      extends SequenceReceiver
      implements ReceiverWithOutputProperties

  Emitter: This abstract class defines methods that must be implemented by components that format SAXON output. There is one emitter for XML, one for HTML, and so on. Additional methods are concerned with setting options and providing a Writer.

  The interface is deliberately designed to be as close as possible to the standard SAX2 ContentHandler interface, however, it allows additional information to be made available.

  An Emitter is a Receiver, specifically it is a Receiver that can direct output to a Writer or OutputStream, using serialization properties defined in a Properties object.

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected boolean` | `allCharactersEncodable` |
    `protected CharacterSet` | `characterSet` |
    `protected java.util.Properties` | `outputProperties` |
    `protected java.io.OutputStream` | `outputStream` |
    `protected javax.xml.transform.stream.StreamResult` | `streamResult` |
    `protected java.io.Writer` | `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
    --- | ---
    `Emitter()` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `append​(Item item, Location locationId, int copyNamespaces)` | Append an arbitrary item (node or atomic value) to the output
    `void` | `close()` | Notify the end of the event stream
    `java.util.Properties` | `getOutputProperties()` | Get the output properties
    `java.io.OutputStream` | `getOutputStream()` | Get the output stream
    `java.io.Writer` | `getWriter()` | Get the output writer
    `protected java.io.OutputStream` | `makeOutputStream()` |
    `protected void` | `makeWriter()` | Make a Writer for this Emitter to use, given a StreamResult.
    `void` | `setOutputProperties​(java.util.Properties details)` | Set output properties
    `void` | `setOutputStream​(java.io.OutputStream stream)` | Set the output destination as a byte stream.
    `void` | `setStreamResult​(javax.xml.transform.stream.StreamResult result)` | Set the StreamResult acting as the output destination of the Emitter
    `void` | `setUnparsedEntity​(java.lang.String name, java.lang.String uri, java.lang.String publicId)` | Set unparsed entity URI.
    `void` | `setWriter​(java.io.Writer writer)` | Set the output destination as a character stream
    `boolean` | `usesTypeAnnotations()` | Ask whether this Receiver (or the downstream pipeline) makes any use of the type annotations supplied on element and attribute events
    `boolean` | `usesWriter()` | Determine whether the Emitter wants a Writer for character output or an OutputStream for binary output.

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

      `append, decompose, flatten, getConfiguration, getErrorCodeForDecomposingFunctionItems, getNamePool, getPipelineConfiguration, getSystemId, handlesAppend, open, 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, characters, comment, endDocument, endElement, getPipelineConfiguration, handlesAppend, open, processingInstruction, setPipelineConfiguration, setSystemId, startDocument, startElement`

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

      `getSystemId`

- - ### Field Detail

    - #### streamResult

          protected javax.xml.transform.stream.StreamResult streamResult

    - #### writer

          protected java.io.Writer writer

    - #### outputStream

          protected java.io.OutputStream outputStream

    - #### outputProperties

          protected java.util.Properties outputProperties

    - #### characterSet

          protected CharacterSet characterSet

    - #### allCharactersEncodable

          protected boolean allCharactersEncodable

  - ### Constructor Detail

    - #### Emitter

          public Emitter()

  - ### Method Detail

    - #### setOutputProperties

          public void setOutputProperties​(java.util.Properties details)
                                   throws XPathException

      Set output properties
      Parameters:
        `details` - the output serialization properties
      Throws:
        `XPathException` - if an error occurs finding the encoding property

    - #### getOutputProperties

          public java.util.Properties getOutputProperties()

      Get the output properties
      Specified by:
        `getOutputProperties` in interface `ReceiverWithOutputProperties`
      Returns:
        the output serialization properties. The returned value will be null if setOutputProperties() has not been called

    - #### setStreamResult

          public void setStreamResult​(javax.xml.transform.stream.StreamResult result)
                               throws XPathException

      Set the StreamResult acting as the output destination of the Emitter
      Parameters:
        `result` - the output destination
      Throws:
        `XPathException` - if an error occurs

    - #### makeWriter

          protected void makeWriter()
                             throws XPathException

      Make a Writer for this Emitter to use, given a StreamResult.
      Throws:
        `XPathException` - if an error occurs

    - #### makeOutputStream

          protected java.io.OutputStream makeOutputStream()
                                                   throws XPathException

      Throws:
        `XPathException`

    - #### usesWriter

          public boolean usesWriter()

      Determine whether the Emitter wants a Writer for character output or an OutputStream for binary output. The standard Emitters all use a Writer, so this returns true; but a subclass can override this if it wants to use an OutputStream
      Returns:
        true if a Writer is needed, as distinct from an OutputStream

    - #### setWriter

          public void setWriter​(java.io.Writer writer)
                         throws XPathException

      Set the output destination as a character stream
      Parameters:
        `writer` - the Writer to use as an output destination
      Throws:
        `XPathException` - if an error occurs

    - #### getWriter

          public java.io.Writer getWriter()

      Get the output writer
      Returns:
        the Writer being used as an output destination, if any

    - #### setOutputStream

          public void setOutputStream​(java.io.OutputStream stream)
                               throws XPathException

      Set the output destination as a byte stream.

      Note that if a specific encoding (other than the default, UTF-8) is required, then `setOutputProperties(java.util.Properties)` must be called before calling this method.

      Parameters:
        `stream` - the OutputStream being used as an output destination
      Throws:
        `XPathException` - if an error occurs

    - #### getOutputStream

          public java.io.OutputStream getOutputStream()

      Get the output stream
      Returns:
        the OutputStream being used as an output destination, if any

    - #### setUnparsedEntity

          public void setUnparsedEntity​(java.lang.String name,
                                        java.lang.String uri,
                                        java.lang.String publicId)
                                 throws XPathException

      Set unparsed entity URI. Needed to satisfy the Receiver interface, but not used, because unparsed entities can occur only in input documents, not in output documents.
      Specified by:
        `setUnparsedEntity` in interface `Receiver`
      Overrides:
        `setUnparsedEntity` in class `SequenceReceiver`
      Parameters:
        `name` - the entity name
        `uri` - the entity system ID
        `publicId` - the entity public ID
      Throws:
        `XPathException` - if an error occurs

    - #### close

          public void close()
                     throws XPathException

      Notify the end of the event stream
      Specified by:
        `close` in interface `Receiver`
      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`
      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 (or conversely, it may avoid stripping unwanted type annotations)

    - #### append

          public void append​(Item item,
                             Location locationId,
                             int copyNamespaces)
                      throws XPathException

      Append an arbitrary item (node or atomic value) to the output
      Specified by:
        `append` in interface `Receiver`
      Specified by:
        `append` in class `SequenceReceiver`
      Parameters:
        `item` - the item to be appended
        `locationId` - the location of the calling instruction, for diagnostics
        `copyNamespaces` - if the item is an element node, this indicates whether its namespaces need to be copied. Values are `ReceiverOption.ALL_NAMESPACES`; the default (0) means
      Throws:
        `XPathException` - if an error occurs