Class SerializerFactory
- Direct Known Subclasses:
SerializerFactoryPE
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.
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionaddHtml5Component
(Receiver target, Properties outputProperties) This method constructs a step in the output pipeline to perform namespace-related tasks for HTML5 serialization.addTextOutputFilter
(Receiver next, Properties properties) Add a filter to the text output method pipeline.protected void
checkExtensions
(String key) protected static String
checkListOfEQNames
(String key, String value) protected static String
checkListOfEQNamesAllowingStar
(String key, String value) protected static void
checkNonNegativeInteger
(String key, String value) checkOutputProperty
(String key, String value) Check that a supplied output property is valid, and normalize the value (specifically in the case of boolean values where yes|true|1 are normalized to "yes", and no|false|0 are normalized to "no").protected static String
checkYesOrNo
(String key, String value) protected SequenceReceiver
createHTMLSerializer
(Emitter emitter, SerializationProperties params, PipelineConfiguration pipe) Create a serialization pipeline to implement the HTML output method.protected SequenceReceiver
createSaxonSerializationMethod
(String method, SerializationProperties params, PipelineConfiguration pipe, CharacterMapExpander characterMapExpander, ProxyReceiver normalizer, ExpandedStreamResult expandedResult, Result result) protected SequenceReceiver
createTextSerializer
(Emitter emitter, SerializationProperties params) Create a serialization pipeline to implement the text output method.protected SequenceReceiver
createUserDefinedOutputMethod
(String method, Properties props, PipelineConfiguration pipe) Create a serialization pipeline to implement a user-defined output method.protected SequenceReceiver
createXHTMLSerializer
(Emitter emitter, SerializationProperties params, PipelineConfiguration pipe) Create a serialization pipeline to implement the XHTML output method.protected SequenceReceiver
createXMLSerializer
(XMLEmitter emitter, SerializationProperties params) Create a serialization pipeline to implement the XML output method.protected SequenceReceiver
customizeAdaptiveSerializer
(AdaptiveEmitter emitter, Properties props, CharacterMapExpander characterMapExpander, ProxyReceiver normalizer) Create a serialization pipeline to implement the Adaptive output method.protected SequenceReceiver
customizeJSONSerializer
(JSONSerializer emitter, Properties props, CharacterMapExpander characterMapExpander, ProxyReceiver normalizer) Create a serialization pipeline to implement the JSON output method.protected Comparator
<AtomicValue> getPropertySorter
(String sortSpecification) getReceiver
(Result result) Get a Receiver that wraps a given Result object.getReceiver
(Result result, PipelineConfiguration pipe, Properties props) Deprecated.getReceiver
(Result result, SerializationProperties params) Get a Receiver that wraps a given Result object.getReceiver
(Result result, SerializationProperties params, PipelineConfiguration pipe) Get a Receiver that wraps a given Result object.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 Receiver
injectCharacterMapExpander
(SerializationProperties params, Receiver out, boolean useNullMarkers) protected Receiver
injectUnicodeNormalizer
(SerializationProperties params, Receiver out) makeSequenceNormalizer
(Receiver receiver, Properties properties) protected Receiver
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.Create a new CharacterMapExpander.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 Receiver
newNamespaceSorter
(Receiver next, Properties outputProperties) Create a new NamespaceSorter, responsible for sorting of namespaces into a specified order.newSequenceWrapper
(Receiver destination) Get a SequenceWrapper, a class that serializes an XDM sequence with full annotation of item types, node kinds, etc.protected Emitter
Create a new Text Emitter.protected UncommittedSerializer
newUncommittedSerializer
(Result result, Receiver next, SerializationProperties params) 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.prepareNextStylesheet
(PipelineConfiguration pipe, String href, String baseURI, Result result) Prepare another stylesheet to handle the output of this one.
-
Constructor Details
-
SerializerFactory
Create a SerializerFactory- Parameters:
config
- the Saxon Configuration
-
SerializerFactory
-
-
Method Details
-
getConfiguration
-
getReceiver
@Deprecated public Receiver getReceiver(Result result, PipelineConfiguration pipe, Properties props) throws XPathException Deprecated.since Saxon 9.9: use one of the othergetReceiver
methodsGet 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 aSequenceWrapper
directly.The effect of the method changes in Saxon 9.7 so that for serialization methods other than "json" and "adaptive", the returned Receiver performs the function of "sequence normalization" as defined in the Serialization specification. Previously the client code handled this by wrapping the result in a ComplexContentOutputter (usually as a side-effect of called XPathContext.changeOutputDestination()). Wrapping in a ComplexContentOutputter is no longer necessary, though it does no harm because the ComplexContentOutputter is idempotent.
Changed in 9.9 so that no character maps are used. Previously the character maps from the Executable associated with the Controller referenced from the PipelineConfiguration were used.
- 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 propertySaxonOutputKeys.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
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.This version of the method calls
getReceiver(Result, SerializationProperties, PipelineConfiguration)
supplying default output properties, and aPipelineConfiguration
newly constructed usingConfiguration.makePipelineConfiguration()
.- Parameters:
result
- The final destination of the serialized output. Usually a StreamResult, but other kinds of Result are possible.- Throws:
XPathException
- if a serializer cannot be created
-
getReceiver
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.This version of the method calls
getReceiver(Result, SerializationProperties, PipelineConfiguration)
supplying aPipelineConfiguration
newly constructed usingConfiguration.makePipelineConfiguration()
.- Parameters:
result
- The final destination of the serialized output. Usually a StreamResult, but other kinds of Result are possible.params
- The serialization properties, including character maps- Returns:
- the newly constructed Receiver that performs the required serialization
- Throws:
XPathException
- if a serializer cannot be created
-
getReceiver
public Receiver getReceiver(Result result, SerializationProperties params, PipelineConfiguration pipe) 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 aSequenceWrapper
directly.The effect of the method changes in Saxon 9.7 so that for serialization methods other than "json" and "adaptive", the returned Receiver performs the function of "sequence normalization" as defined in the Serialization specification. Previously the client code handled this by wrapping the result in a ComplexContentOutputter (usually as a side-effect of called XPathContext.changeOutputDestination()). Wrapping in a ComplexContentOutputter is no longer necessary, though it does no harm because the ComplexContentOutputter is idempotent.
- Parameters:
result
- The final destination of the serialized output. Usually a StreamResult, but other kinds of Result are possible.params
- The serialization properties, including character mapspipe
- The PipelineConfiguration.- Returns:
- the newly constructed Receiver that performs the required serialization
- Throws:
XPathException
- if a serializer cannot be created
-
makeSequenceNormalizer
-
createHTMLSerializer
protected SequenceReceiver createHTMLSerializer(Emitter emitter, SerializationProperties params, PipelineConfiguration pipe) 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 methodnewHTMLEmitter(java.util.Properties)
params
- the serialization propertiespipe
- the pipeline configuration information- Returns:
- a Receiver acting as the entry point to the serialization pipeline
- Throws:
XPathException
- if a failure occurs
-
createTextSerializer
protected SequenceReceiver createTextSerializer(Emitter emitter, SerializationProperties params) 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 methodnewTEXTEmitter()
params
- the serialization properties- Returns:
- a Receiver acting as the entry point to the serialization pipeline
- Throws:
XPathException
- if a failure occurs
-
customizeJSONSerializer
protected SequenceReceiver customizeJSONSerializer(JSONSerializer emitter, Properties props, CharacterMapExpander characterMapExpander, ProxyReceiver normalizer) throws XPathException Create a serialization pipeline to implement the JSON 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 methodnewTEXTEmitter()
props
- the serialization propertiescharacterMapExpander
- the filter to be used for expanding character maps defined in the stylesheetnormalizer
- the filter used for Unicode normalization- Returns:
- a Receiver acting as the entry point to the serialization pipeline
- Throws:
XPathException
-
customizeAdaptiveSerializer
protected SequenceReceiver customizeAdaptiveSerializer(AdaptiveEmitter emitter, Properties props, CharacterMapExpander characterMapExpander, ProxyReceiver normalizer) Create a serialization pipeline to implement the Adaptive 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 pipelineprops
- the serialization propertiescharacterMapExpander
- the filter to be used for expanding character maps defined in the stylesheetnormalizer
- the filter used for Unicode normalization- Returns:
- a Receiver acting as the entry point to the serialization pipeline
-
createXHTMLSerializer
protected SequenceReceiver createXHTMLSerializer(Emitter emitter, SerializationProperties params, PipelineConfiguration pipe) 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 methodnewXHTMLEmitter(java.util.Properties)
params
- the serialization propertiespipe
- the pipeline configuration information- Returns:
- a Receiver acting as the entry point to the serialization pipeline
- Throws:
XPathException
- if a failure occurs
-
addHtml5Component
This method constructs a step in the output pipeline to perform namespace-related tasks for HTML5 serialization. The default implementation adds a NamespaceReducer and an XHTMLPrefixRemover- Parameters:
target
- the Receiver that receives the output of this stepoutputProperties
- the serialization properties- Returns:
- a new Receiver to perform HTML5-related namespace manipulation
-
createXMLSerializer
protected SequenceReceiver createXMLSerializer(XMLEmitter emitter, SerializationProperties params) 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 methodnewXMLEmitter(java.util.Properties)
params
- the serialization properties- Returns:
- a Receiver acting as the entry point to the serialization pipeline
- Throws:
XPathException
- if a failure occurs
-
createSaxonSerializationMethod
protected SequenceReceiver createSaxonSerializationMethod(String method, SerializationProperties params, PipelineConfiguration pipe, CharacterMapExpander characterMapExpander, ProxyReceiver normalizer, ExpandedStreamResult expandedResult, Result result) throws XPathException - Throws:
XPathException
-
createUserDefinedOutputMethod
protected SequenceReceiver 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 EQName format (that is "Q{uri}local").props
- the serialization propertiespipe
- the pipeline configuration information- Returns:
- a Receiver acting as the entry point to the serialization pipeline
- Throws:
XPathException
- if a failure occurs
-
injectCharacterMapExpander
protected Receiver injectCharacterMapExpander(SerializationProperties params, Receiver out, boolean useNullMarkers) throws XPathException - Throws:
XPathException
-
injectUnicodeNormalizer
protected Receiver injectUnicodeNormalizer(SerializationProperties params, Receiver out) throws XPathException - Throws:
XPathException
-
newUncommittedSerializer
protected UncommittedSerializer newUncommittedSerializer(Result result, Receiver next, SerializationProperties params) Create an UncommittedSerializer. This method exists so that it can be overridden in a subclass.- Parameters:
result
- the result destinationnext
- the next receiver in the pipelineparams
- the serialization parameters- Returns:
- the newly created UncommittedSerializer.
-
newXMLEmitter
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
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
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
Add a filter to the text output method pipeline. This does nothing unless overridden in a subclass- 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
- if the operation fails
-
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
Create a new XML Indenter. This method exists so that it can be overridden in a subclass.- Parameters:
next
- the next receiver in the pipelineoutputProperties
- the serialization parameters- Returns:
- the newly created XML indenter.
-
newHTMLIndenter
Create a new HTML Indenter. This method exists so that it can be overridden in a subclass.- Parameters:
next
- the next receiver in the pipelineoutputProperties
- the serialization parameters- Returns:
- the newly created HTML indenter.
-
newXHTMLIndenter
Create a new XHTML Indenter. This method exists so that it can be overridden in a subclass.- Parameters:
next
- the next receiver in the pipelineoutputProperties
- the serialization parameters- Returns:
- the newly created XHTML indenter.
-
newXHTMLMetaTagAdjuster
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 pipelineoutputProperties
- the serialization parameters- Returns:
- the newly created XHTML MetaTagAdjuster.
-
newHTMLMetaTagAdjuster
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 pipelineoutputProperties
- the serialization parameters- Returns:
- the newly created HTML MetaTagAdjuster.
-
newHTMLURIEscaper
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 pipelineoutputProperties
- the serialization parameters- Returns:
- the newly created HTML URI escaper.
-
newXHTMLURIEscaper
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 pipelineoutputProperties
- 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 pipelineoutputProperties
- the serialization parameters- Returns:
- the newly created CDATA filter.
- Throws:
XPathException
- if an error occurs
-
newAttributeSorter
protected Receiver 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. The Saxon-HE version of this method returns the supplied receiver unchanged (attribute sorting is not supported in Saxon-HE). The AttributeSorter handles both sorting of attributes into a user-specified order (saxon:attribute-order) and sorting into C14N order (saxon:canonical).- Parameters:
next
- the next receiver in the pipelineoutputProperties
- the serialization parameters- Returns:
- the newly created filter.
- Throws:
XPathException
-
newNamespaceSorter
protected Receiver newNamespaceSorter(Receiver next, Properties outputProperties) throws XPathException Create a new NamespaceSorter, responsible for sorting of namespaces into a specified order.- Parameters:
next
- the next receiver in the pipelineoutputProperties
- the serialization parameters- Returns:
- the newly created filter.
- Throws:
XPathException
-
newXML10ContentChecker
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 pipelineoutputProperties
- 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 pipelineoutputProperties
- the serialization parameters- Returns:
- the newly created Unicode normalizer.
- Throws:
XPathException
- if an error occurs
-
newCharacterMapExpander
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 SequenceReceiver prepareNextStylesheet(PipelineConfiguration pipe, String href, String baseURI, Result result) throws XPathException 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:
pipe
- the current transformationhref
- URI of the next stylesheet to be appliedbaseURI
- base URI for resolving href if it's a relative URIresult
- the output destination of the current stylesheet- Returns:
- a replacement destination for the current stylesheet
- Throws:
XPathException
- if any dynamic error occurs
-
newSequenceWrapper
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- Parameters:
destination
- the place where the wrapped sequence will be sent- Returns:
- the new SequenceWrapper
-
checkOutputProperty
Check that a supplied output property is valid, and normalize the value (specifically in the case of boolean values where yes|true|1 are normalized to "yes", and no|false|0 are normalized to "no"). Clark names in the value ({uri}local
) are normalized to EQNames (Q{uri}local
)- Parameters:
key
- the name of the property, in Clark formatvalue
- the value of the property. This may be set to null, in which case no validation takes place. The value must be in JAXP format, that is, with lexical QNames expanded to either EQNames or Clark names.- Returns:
- normalized value of the property, or null if the supplied value is null
- Throws:
XPathException
- if the property name or value is invalid
-
checkYesOrNo
- Throws:
XPathException
-
checkNonNegativeInteger
- Throws:
XPathException
-
checkListOfEQNames
- Throws:
XPathException
-
checkListOfEQNamesAllowingStar
protected static String checkListOfEQNamesAllowingStar(String key, String value) throws XPathException - Throws:
XPathException
-
checkExtensions
- Throws:
XPathException
-
getPropertySorter
- Throws:
XPathException
-
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
methods