net.sf.saxon.lib

## Class SerializerFactory

- java.lang.Object
- - net.sf.saxon.lib.SerializerFactory

- All Implemented Interfaces:
    Serializable
  Direct Known Subclasses:
    SerializerFactoryPE

      public class SerializerFactory
      extends Object
      implements Serializable

  Helper class to construct a serialization pipeline for a given result destination and a given set of output properties. The pipeline is represented by a Receiver object to which result tree events are sent. Since Saxon 8.8 is is possible to write a subclass of SerializerFactory and register it with the Configuration, allowing customisation of the Serializer pipeline. The class includes methods for instantiating each of the components used on the Serialization pipeline. This allows a customized SerializerFactory to replace any or all of these components by subclasses that refine the behaviour.
  See Also:
    Serialized Form

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `SerializerFactory(Configuration config)` Create a SerializerFactory

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Receiver` | `addHtml5Component(Receiver next, Properties outputProperties)`
    `Receiver` | `addTextOutputFilter(Receiver next, Properties properties)` Add a filter to the text output method pipeline.
    `protected Receiver` | `createHTMLSerializer(Emitter emitter, Properties props, PipelineConfiguration pipe, CharacterMapExpander characterMapExpander, ProxyReceiver normalizer)` Create a serialization pipeline to implement the HTML output method.
    `protected Receiver` | `createSaxonSerializationMethod(String method, Properties props, PipelineConfiguration pipe, CharacterMapExpander characterMapExpander, ProxyReceiver normalizer)`
    `protected Receiver` | `createTextSerializer(Emitter emitter, Properties props, CharacterMapExpander characterMapExpander, ProxyReceiver normalizer)` Create a serialization pipeline to implement the text output method.
    `protected Receiver` | `createUserDefinedOutputMethod(String method, Properties props, PipelineConfiguration pipe)` Create a serialization pipeline to implement a user-defined output method.
    `protected Receiver` | `createXHTMLSerializer(Emitter emitter, Properties props, PipelineConfiguration pipe, CharacterMapExpander characterMapExpander, ProxyReceiver normalizer)` Create a serialization pipeline to implement the XHTML output method.
    `protected Receiver` | `createXMLSerializer(XMLEmitter emitter, Properties props, PipelineConfiguration pipe, CharacterMapExpander characterMapExpander, ProxyReceiver normalizer)` Create a serialization pipeline to implement the XML output method.
    `Receiver` | `getReceiver(Result result, PipelineConfiguration pipe, Properties props)` Get a Receiver that wraps a given Result object.
    `Receiver` | `getReceiver(Result result, PipelineConfiguration pipe, Properties props, CharacterMapIndex charMapIndex)` Get a Receiver that wraps a given Result object.
    `StreamWriterToReceiver` | `getXMLStreamWriter(StreamResult result, Properties properties)` Create a serializer with given output properties, and return an XMLStreamWriter that can be used to feed events to the serializer.
    `protected ProxyReceiver` | `newAttributeSorter(Receiver next, Properties outputProperties)` Create a new AttributeSorter, responsible for sorting of attributes into a specified order.
    `protected ProxyReceiver` | `newCDATAFilter(Receiver next, Properties outputProperties)` Create a new CDATA Filter, responsible for insertion of CDATA sections where required.
    `CharacterMapExpander` | `newCharacterMapExpander(Receiver next)` Create a new CharacterMapExpander.
    `protected ContentHandlerProxy` | `newContentHandlerProxy()` Create a ContentHandlerProxy.
    `protected Emitter` | `newHTMLEmitter(Properties properties)` Create a new HTML Emitter.
    `protected ProxyReceiver` | `newHTMLIndenter(Receiver next, Properties outputProperties)` Create a new HTML Indenter.
    `protected MetaTagAdjuster` | `newHTMLMetaTagAdjuster(Receiver next, Properties outputProperties)` Create a new XHTML MetaTagAdjuster, responsible for insertion, removal, or replacement of meta elements.
    `protected ProxyReceiver` | `newHTMLURIEscaper(Receiver next, Properties outputProperties)` Create a new HTML URI Escaper, responsible for percent-encoding of URIs in HTML output documents.
    `SequenceWrapper` | `newSequenceWrapper(Receiver destination)` Get a SequenceWrapper, a class that serializes an XDM sequence with full annotation of item types, node kinds, etc.
    `protected Emitter` | `newTEXTEmitter()` Create a new Text Emitter.
    `protected UncommittedSerializer` | `newUncommittedSerializer(Result result, Receiver next, Properties properties)` Create an UncommittedSerializer.
    `protected ProxyReceiver` | `newUnicodeNormalizer(Receiver next, Properties outputProperties)` Create a Unicode Normalizer.
    `protected Emitter` | `newXHTMLEmitter(Properties properties)` Create a new XHTML Emitter.
    `protected ProxyReceiver` | `newXHTMLIndenter(Receiver next, Properties outputProperties)` Create a new XHTML Indenter.
    `protected MetaTagAdjuster` | `newXHTMLMetaTagAdjuster(Receiver next, Properties outputProperties)` Create a new XHTML MetaTagAdjuster, responsible for insertion, removal, or replacement of meta elements.
    `protected ProxyReceiver` | `newXHTMLURIEscaper(Receiver next, Properties outputProperties)` Create a new XHTML URI Escaper, responsible for percent-encoding of URIs in HTML output documents.
    `protected ProxyReceiver` | `newXML10ContentChecker(Receiver next, Properties outputProperties)` Create a new XML 1.0 content checker, responsible for checking that the output conforms to XML 1.0 rules (this is used only if the Configuration supports XML 1.1 but the specific output file requires XML 1.0).
    `protected Emitter` | `newXMLEmitter(Properties properties)` Create a new XML Emitter.
    `protected ProxyReceiver` | `newXMLIndenter(XMLEmitter next, Properties outputProperties)` Create a new XML Indenter.
    `Result` | `prepareNextStylesheet(Controller controller, String href, String baseURI, Result result)` Prepare another stylesheet to handle the output of this one.

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

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

- - ### Constructor Detail

    - #### SerializerFactory

          public SerializerFactory(Configuration config)

      Create a SerializerFactory
      Parameters:
        `config` - the Saxon Configuration

  - ### Method Detail

    - #### getXMLStreamWriter

          public StreamWriterToReceiver getXMLStreamWriter(StreamResult result,
                                                  Properties properties)
                                                    throws XPathException

      Create a serializer with given output properties, and return an XMLStreamWriter that can be used to feed events to the serializer.
      Parameters:
        `result` - the destination of the serialized output (wraps a Writer, an OutputStream, or a File)
        `properties` - the serialization properties to be used
      Returns:
        a serializer in the form of an XMLStreamWriter
      Throws:
        `XPathException` - if any error occurs

    - #### getReceiver

          public Receiver getReceiver(Result result,
                             PipelineConfiguration pipe,
                             Properties props)
                               throws XPathException

      Get a Receiver that wraps a given Result object. Saxon calls this method to construct a serialization pipeline. The method can be overridden in a subclass; alternatively, the subclass can override the various methods used to instantiate components of the serialization pipeline.

      Note that this method ignores the `SaxonOutputKeys.WRAP` output property. If wrapped output is required, the user must create a `SequenceWrapper` directly.

      Parameters:
        `result` - The final destination of the serialized output. Usually a StreamResult, but other kinds of Result are possible.
        `pipe` - The PipelineConfiguration.
        `props` - The serialization properties. If this includes the property `SaxonOutputKeys.USE_CHARACTER_MAPS` then the PipelineConfiguration must contain a non-null Controller, and the Executable associated with this Controller must have a CharacterMapIndex which is used to resolve the names of the character maps appearing in this property.
      Returns:
        the newly constructed Receiver that performs the required serialization
      Throws:
        `XPathException` - if any failure occurs

    - #### getReceiver

          public Receiver getReceiver(Result result,
                             PipelineConfiguration pipe,
                             Properties props,
                             CharacterMapIndex charMapIndex)
                               throws XPathException

      Get a Receiver that wraps a given Result object. Saxon calls this method to construct a serialization pipeline. The method can be overridden in a subclass; alternatively, the subclass can override the various methods used to instantiate components of the serialization pipeline.

      Note that this method ignores the `SaxonOutputKeys.WRAP` output property. If wrapped output is required, the user must create a `SequenceWrapper` directly.

      Parameters:
        `result` - The final destination of the serialized output. Usually a StreamResult, but other kinds of Result are possible.
        `pipe` - The PipelineConfiguration.
        `props` - The serialization properties
        `charMapIndex` - The index of character maps. Required if any of the serialization properties is `SaxonOutputKeys.USE_CHARACTER_MAPS`, in which case the named character maps listed in that property must be present in the index of character maps.
      Returns:
        the newly constructed Receiver that performs the required serialization
      Throws:
        `XPathException`

    - #### createHTMLSerializer

          protected Receiver createHTMLSerializer(Emitter emitter,
                                      Properties props,
                                      PipelineConfiguration pipe,
                                      CharacterMapExpander characterMapExpander,
                                      ProxyReceiver normalizer)
                                           throws XPathException

      Create a serialization pipeline to implement the HTML output method. This method is protected so that it can be customized in a user-written SerializerFactory
      Parameters:
        `emitter` - the emitter at the end of the pipeline (created using the method `newHTMLEmitter(java.util.Properties)`
        `props` - the serialization properties
        `pipe` - the pipeline configuration information
        `characterMapExpander` - the filter to be used for expanding character maps defined in the stylesheet
        `normalizer` - the filter used for Unicode normalization
      Returns:
        a Receiver acting as the entry point to the serialization pipeline
      Throws:
        `XPathException` - if a failure occurs

    - #### createTextSerializer

          protected Receiver createTextSerializer(Emitter emitter,
                                      Properties props,
                                      CharacterMapExpander characterMapExpander,
                                      ProxyReceiver normalizer)
                                           throws XPathException

      Create a serialization pipeline to implement the text output method. This method is protected so that it can be customized in a user-written SerializerFactory
      Parameters:
        `emitter` - the emitter at the end of the pipeline (created using the method `newTEXTEmitter()`
        `props` - the serialization properties
        `characterMapExpander` - the filter to be used for expanding character maps defined in the stylesheet
        `normalizer` - the filter used for Unicode normalization
      Returns:
        a Receiver acting as the entry point to the serialization pipeline
      Throws:
        `XPathException` - if a failure occurs

    - #### createXHTMLSerializer

          protected Receiver createXHTMLSerializer(Emitter emitter,
                                       Properties props,
                                       PipelineConfiguration pipe,
                                       CharacterMapExpander characterMapExpander,
                                       ProxyReceiver normalizer)
                                            throws XPathException

      Create a serialization pipeline to implement the XHTML output method. This method is protected so that it can be customized in a user-written SerializerFactory
      Parameters:
        `emitter` - the emitter at the end of the pipeline (created using the method `newXHTMLEmitter(java.util.Properties)`
        `props` - the serialization properties
        `pipe` - the pipeline configuration information
        `characterMapExpander` - the filter to be used for expanding character maps defined in the stylesheet
        `normalizer` - the filter used for Unicode normalization
      Returns:
        a Receiver acting as the entry point to the serialization pipeline
      Throws:
        `XPathException` - if a failure occurs

    - #### addHtml5Component

          public Receiver addHtml5Component(Receiver next,
                                   Properties outputProperties)

    - #### createXMLSerializer

          protected Receiver createXMLSerializer(XMLEmitter emitter,
                                     Properties props,
                                     PipelineConfiguration pipe,
                                     CharacterMapExpander characterMapExpander,
                                     ProxyReceiver normalizer)
                                          throws XPathException

      Create a serialization pipeline to implement the XML output method. This method is protected so that it can be customized in a user-written SerializerFactory
      Parameters:
        `emitter` - the emitter at the end of the pipeline (created using the method `newXHTMLEmitter(java.util.Properties)`
        `props` - the serialization properties
        `pipe` - the pipeline configuration information
        `characterMapExpander` - the filter to be used for expanding character maps defined in the stylesheet
        `normalizer` - the filter used for Unicode normalization
      Returns:
        a Receiver acting as the entry point to the serialization pipeline
      Throws:
        `XPathException` - if a failure occurs

    - #### createSaxonSerializationMethod

          protected Receiver createSaxonSerializationMethod(String method,
                                                Properties props,
                                                PipelineConfiguration pipe,
                                                CharacterMapExpander characterMapExpander,
                                                ProxyReceiver normalizer)
                                                     throws XPathException

      Throws:
        `XPathException`

    - #### createUserDefinedOutputMethod

          protected Receiver createUserDefinedOutputMethod(String method,
                                               Properties props,
                                               PipelineConfiguration pipe)
                                                    throws XPathException

      Create a serialization pipeline to implement a user-defined output method. This method is protected so that it can be customized in a user-written SerializerFactory
      Parameters:
        `method` - the name of the user-defined output method, as a QName in Clark format (that is "{uri}local").
        `props` - the serialization properties
        `pipe` - the pipeline configuration information
      Returns:
        a Receiver acting as the entry point to the serialization pipeline
      Throws:
        `XPathException` - if a failure occurs

    - #### newContentHandlerProxy

          protected ContentHandlerProxy newContentHandlerProxy()

      Create a ContentHandlerProxy. This method exists so that it can be overridden in a subclass.
      Returns:
        the newly created ContentHandlerProxy.

    - #### newUncommittedSerializer

          protected UncommittedSerializer newUncommittedSerializer(Result result,
                                                       Receiver next,
                                                       Properties properties)

      Create an UncommittedSerializer. This method exists so that it can be overridden in a subclass.
      Parameters:
        `result` - the result destination
        `next` - the next receiver in the pipeline
        `properties` - the serialization properties
      Returns:
        the newly created UncommittedSerializer.

    - #### newXMLEmitter

          protected Emitter newXMLEmitter(Properties properties)

      Create a new XML Emitter. This method exists so that it can be overridden in a subclass.
      Parameters:
        `properties` - the output properties
      Returns:
        the newly created XML emitter.

    - #### newHTMLEmitter

          protected Emitter newHTMLEmitter(Properties properties)

      Create a new HTML Emitter. This method exists so that it can be overridden in a subclass.
      Parameters:
        `properties` - the output properties
      Returns:
        the newly created HTML emitter.

    - #### newXHTMLEmitter

          protected Emitter newXHTMLEmitter(Properties properties)

      Create a new XHTML Emitter. This method exists so that it can be overridden in a subclass.
      Parameters:
        `properties` - the output properties
      Returns:
        the newly created XHTML emitter.

    - #### addTextOutputFilter

          public Receiver addTextOutputFilter(Receiver next,
                                     Properties properties)
                                       throws XPathException

      Add a filter to the text output method pipeline. This does nothing unless overridden in a superclass
      Parameters:
        `next` - the next receiver (typically the TextEmitter)
        `properties` - the output properties
      Returns:
        the receiver to be used in place of the "next" receiver
      Throws:
        `XPathException`

    - #### newTEXTEmitter

          protected Emitter newTEXTEmitter()

      Create a new Text Emitter. This method exists so that it can be overridden in a subclass.
      Returns:
        the newly created text emitter.

    - #### newXMLIndenter

          protected ProxyReceiver newXMLIndenter(XMLEmitter next,
                                     Properties outputProperties)

      Create a new XML Indenter. This method exists so that it can be overridden in a subclass.
      Parameters:
        `next` - the next receiver in the pipeline
        `outputProperties` - the serialization parameters
      Returns:
        the newly created XML indenter.

    - #### newHTMLIndenter

          protected ProxyReceiver newHTMLIndenter(Receiver next,
                                      Properties outputProperties)

      Create a new HTML Indenter. This method exists so that it can be overridden in a subclass.
      Parameters:
        `next` - the next receiver in the pipeline
        `outputProperties` - the serialization parameters
      Returns:
        the newly created HTML indenter.

    - #### newXHTMLIndenter

          protected ProxyReceiver newXHTMLIndenter(Receiver next,
                                       Properties outputProperties)

      Create a new XHTML Indenter. This method exists so that it can be overridden in a subclass.
      Parameters:
        `next` - the next receiver in the pipeline
        `outputProperties` - the serialization parameters
      Returns:
        the newly created XHTML indenter.

    - #### newXHTMLMetaTagAdjuster

          protected MetaTagAdjuster newXHTMLMetaTagAdjuster(Receiver next,
                                                Properties outputProperties)

      Create a new XHTML MetaTagAdjuster, responsible for insertion, removal, or replacement of meta elements. This method exists so that it can be overridden in a subclass.
      Parameters:
        `next` - the next receiver in the pipeline
        `outputProperties` - the serialization parameters
      Returns:
        the newly created XHTML MetaTagAdjuster.

    - #### newHTMLMetaTagAdjuster

          protected MetaTagAdjuster newHTMLMetaTagAdjuster(Receiver next,
                                               Properties outputProperties)

      Create a new XHTML MetaTagAdjuster, responsible for insertion, removal, or replacement of meta elements. This method exists so that it can be overridden in a subclass.
      Parameters:
        `next` - the next receiver in the pipeline
        `outputProperties` - the serialization parameters
      Returns:
        the newly created HTML MetaTagAdjuster.

    - #### newHTMLURIEscaper

          protected ProxyReceiver newHTMLURIEscaper(Receiver next,
                                        Properties outputProperties)

      Create a new HTML URI Escaper, responsible for percent-encoding of URIs in HTML output documents. This method exists so that it can be overridden in a subclass.
      Parameters:
        `next` - the next receiver in the pipeline
        `outputProperties` - the serialization parameters
      Returns:
        the newly created HTML URI escaper.

    - #### newXHTMLURIEscaper

          protected ProxyReceiver newXHTMLURIEscaper(Receiver next,
                                         Properties outputProperties)

      Create a new XHTML URI Escaper, responsible for percent-encoding of URIs in HTML output documents. This method exists so that it can be overridden in a subclass.
      Parameters:
        `next` - the next receiver in the pipeline
        `outputProperties` - the serialization parameters
      Returns:
        the newly created HTML URI escaper.

    - #### newCDATAFilter

          protected ProxyReceiver newCDATAFilter(Receiver next,
                                     Properties outputProperties)
                                          throws XPathException

      Create a new CDATA Filter, responsible for insertion of CDATA sections where required. This method exists so that it can be overridden in a subclass.
      Parameters:
        `next` - the next receiver in the pipeline
        `outputProperties` - the serialization parameters
      Returns:
        the newly created CDATA filter.
      Throws:
        `XPathException` - if an error occurs

    - #### newAttributeSorter

          protected ProxyReceiver newAttributeSorter(Receiver next,
                                         Properties outputProperties)
                                              throws XPathException

      Create a new AttributeSorter, responsible for sorting of attributes into a specified order. This method exists so that it can be overridden in a subclass.
      Parameters:
        `next` - the next receiver in the pipeline
        `outputProperties` - the serialization parameters
      Returns:
        the newly created CDATA filter.
      Throws:
        `XPathException` - if an error occurs

    - #### newXML10ContentChecker

          protected ProxyReceiver newXML10ContentChecker(Receiver next,
                                             Properties outputProperties)

      Create a new XML 1.0 content checker, responsible for checking that the output conforms to XML 1.0 rules (this is used only if the Configuration supports XML 1.1 but the specific output file requires XML 1.0). This method exists so that it can be overridden in a subclass.
      Parameters:
        `next` - the next receiver in the pipeline
        `outputProperties` - the serialization parameters
      Returns:
        the newly created XML 1.0 content checker.

    - #### newUnicodeNormalizer

          protected ProxyReceiver newUnicodeNormalizer(Receiver next,
                                           Properties outputProperties)
                                                throws XPathException

      Create a Unicode Normalizer. This method exists so that it can be overridden in a subclass.
      Parameters:
        `next` - the next receiver in the pipeline
        `outputProperties` - the serialization parameters
      Returns:
        the newly created Unicode normalizer.
      Throws:
        `XPathException` - if an error occurs

    - #### newCharacterMapExpander

          public CharacterMapExpander newCharacterMapExpander(Receiver next)

      Create a new CharacterMapExpander. This method exists so that it can be overridden in a subclass.
      Parameters:
        `next` - the next receiver in the pipeline
      Returns:
        the newly created CharacterMapExpander.

    - #### prepareNextStylesheet

          public Result prepareNextStylesheet(Controller controller,
                                     String href,
                                     String baseURI,
                                     Result result)
                                       throws TransformerException

      Prepare another stylesheet to handle the output of this one.

      This method is intended for internal use, to support the `saxon:next-in-chain` extension.

      Parameters:
        `controller` - the current transformation
        `href` - URI of the next stylesheet to be applied
        `baseURI` - base URI for resolving href if it's a relative URI
        `result` - the output destination of the current stylesheet
      Returns:
        a replacement destination for the current stylesheet
      Throws:
        `XPathException` - if any dynamic error occurs
        `TransformerException`

    - #### newSequenceWrapper

          public SequenceWrapper newSequenceWrapper(Receiver destination)

      Get a SequenceWrapper, a class that serializes an XDM sequence with full annotation of item types, node kinds, etc. There are variants for Saxon-HE and Saxon-PE

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