net.sf.saxon.lib
Class SerializerFactory

java.lang.Object
  extended by 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
SerializerFactory(Configuration config)
          Create a SerializerFactory
 
Method Summary
 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.
 XMLStreamWriter 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 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.
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 XMLStreamWriter 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

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

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


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