net.sf.saxon.s9api

Class Serializer

java.lang.Object

net.sf.saxon.s9api.Serializer

All Implemented Interfaces:

Destination

public class Serializer
extends java.lang.Object
implements Destination

A Serializer takes a tree representation of XML and turns it into lexical XML markup.

Note that this is XML serialization in the sense of the W3C XSLT and XQuery specifications. This has nothing to do with the serialization of Java objects, or the Serializable interface.

The serialization may be influenced by a number of serialization parameters. A parameter has a name, which is an instance of Serializer.Property, and a value, which is expressed as a string. The effect of most of the properties is as described in the W3C specification XSLT 2.0 and XQuery 1.0 Serialization. Saxon supports all the serialization parameters defined in that specification, together with some additional parameters, whose property names are prefixed "SAXON_".

Serialization parameters defined via this interface take precedence over any serialization parameters defined within the source of the query or stylesheet.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Serializer.Property Enumerator over the defined serialization properties

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Serializer(Processor processor) Create a Serializer belonging to a specific processor

Method Summary

Modifier and Type	Method and Description
void	close() Close any resources associated with this destination.
java.util.Properties	getCombinedOutputProperties() Create a Properties object holding the defined serialization properties.
org.xml.sax.ContentHandler	getContentHandler() Get a ContentHandler that can be used to direct the output of a SAX parser (or other source of SAX events) to this serializer.
protected java.util.Properties	getLocalOutputProperties() Create a Properties object holding the serialization properties explicitly declared within this Serializer object, and not including any defaults taken from the stylesheet or query.
java.lang.Object	getOutputDestination() Get the current output destination.
java.lang.String	getOutputProperty(QName property) Get the value of a serialization property.
java.lang.String	getOutputProperty(Serializer.Property property) Get the value of a serialization property
Processor	getProcessor() Get the Processor associated with this Serializer.
static Serializer.Property	getProperty(QName name) Get the Property with a given QName
Receiver	getReceiver(Configuration config) Return a receiver to which Saxon will send events.
Receiver	getReceiver(Executable executable) Return a receiver to which Saxon will send events.
Receiver	getReceiver(PipelineConfiguration pipe) Return a receiver to which Saxon will send events.
protected javax.xml.transform.Result	getResult() Get the JAXP StreamResult object representing the output destination of this serializer
StreamWriterToReceiver	getXMLStreamWriter() Get an XMLStreamWriter that can be used for writing application-generated XML to be output via this serializer.
boolean	isMustCloseAfterUse()
void	serializeNode(XdmNode node) Serialize an XdmNode to the selected output destination using this serializer
java.lang.String	serializeNodeToString(XdmNode node) Serialize an XdmNode to a string using this serializer
void	serializeXdmValue(XdmValue value) Serialize an arbitrary XdmValue to the selected output destination using this serializer.
void	setCharacterMap(CharacterMapIndex characterMap) Set a character map to be used; more specifically, supply a set of named character maps
void	setCloseOnCompletion(boolean value) Say if the output stream should be closed on completion By default the close method closes the output stream only when the serializer created the output stream itself that is when the destination has been suppplied as a file rather than a stream.
void	setDefaultOutputProperties(java.util.Properties defaultProperties) Set default output properties, for use when no explicit properties are set using setProperty().
void	setOutputFile(java.io.File file) Set the destination of the serialized output, as a File.
void	setOutputProperty(QName property, java.lang.String value) Set the value of a serialization property.
void	setOutputProperty(Serializer.Property property, java.lang.String value) Set the value of a serialization property.
void	setOutputStream(java.io.OutputStream stream) Set the destination of the serialized output, as an OutputStream.
void	setOutputWriter(java.io.Writer writer) Set the destination of the serialized output, as a Writer.
void	setProcessor(Processor processor) Set the Processor associated with this Serializer.

Methods inherited from class java.lang.Object

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

Constructor Detail

Serializer

protected Serializer(Processor processor)

Create a Serializer belonging to a specific processor

Parameters:

processor - the processor associated with the Serializer

Method Detail

setProcessor

public void setProcessor(Processor processor)

Set the Processor associated with this Serializer. This will be called automatically if the serializer is created using one of the Processor.newSerializer() methods. The Serializer currently needs to know about the Processor only if the method getXMLStreamWriter() is called.

Parameters:

processor - the associated Processor (must not be null)

Since:

9.3

getProcessor

public Processor getProcessor()

Get the Processor associated with this Serializer. This may be null if a deprecated constructor was used to create the Serializer.

Returns:

the associated Processor

setDefaultOutputProperties

public void setDefaultOutputProperties(java.util.Properties defaultProperties)

Set default output properties, for use when no explicit properties are set using setProperty(). The values supplied are typically those specified in the stylesheet or query. In the case of XSLT, they are the properties associated with unnamed xsl:output declarations.

Parameters:

defaultProperties - the default output properties to be used

setCloseOnCompletion

public void setCloseOnCompletion(boolean value)

Say if the output stream should be closed on completion By default the close method closes the output stream only when the serializer created the output stream itself that is when the destination has been suppplied as a file rather than a stream.

Parameters:

value - - if true the output file will be closed when the close method is called if false the close method has no effect.

setCharacterMap

public void setCharacterMap(CharacterMapIndex characterMap)

Set a character map to be used; more specifically, supply a set of named character maps

Parameters:

characterMap - a set of named character maps. A character map in this set will only be used if the name of the character map is added to the value of the Serializer.Property.USE_CHARACTER_MAPS serialization property. The character maps in this index are added to the existing set of character maps known to the serializer, unless they have the same names as existing character maps, in which case the new one overwrites the old.

setOutputProperty

public void setOutputProperty(Serializer.Property property,
                              java.lang.String value)

Set the value of a serialization property. Any existing value of the property is overridden. If the supplied value is null, any existing value of the property is removed.

Example:

serializer.setOutputProperty(Serializer.Property.METHOD, "xml");

Any serialization properties supplied via this interface take precedence over serialization properties defined in the source stylesheet or query, including properties set dynamically using xsl:result-document. However, they only affect the principal output of a transformation; the serialization of secondary result documents is controlled using an OutputURIResolver.

Parameters:

property - The name of the property to be set

value - The value of the property, as a string. The format is generally as defined in the xsl:output declaration in XSLT: this means that boolean properties, for example, are represented using the strings "yes" and "no". Properties whose values are QNames, such as cdata-section-elements are expressed using the Clark representation of a QName, that is "{uri}local". Multi-valued properties (again, cdata-section-elements is an example) are expressed as a space-separated list.

Throws:

java.lang.IllegalArgumentException - if the value of the property is invalid. The property is validated individually; invalid combinations of properties will be detected only when the properties are actually used to serialize an XML event stream.

getOutputProperty

public java.lang.String getOutputProperty(Serializer.Property property)

Get the value of a serialization property

Parameters:

property - the name of the required property. This method only considers properties explicitly set on this Serialized object, it does not return values obtained from the stylesheet or query.

Returns:

the value of the required property as a string, or null if the property has not been given any value.

setOutputProperty

public void setOutputProperty(QName property,
                              java.lang.String value)

Set the value of a serialization property. Any existing value of the property is overridden. If the supplied value is null, any existing value of the property is removed.

Example:

serializer.setOutputProperty(new QName("method"), "xml");

Any serialization properties supplied via this interface take precedence over serialization properties defined in the source stylesheet or query.

Unlike the method setOutputProperty(Property, String), this method allows properties to be set whose names are not in the standard set of property names defined in the W3C specifications, nor in a recognized Saxon extension. This enables properties to be set for use by a custom serialization method.

Parameters:

property - The name of the property to be set

value - The value of the property, as a string. The format is generally as defined in the xsl:output declaration in XSLT: this means that boolean properties, for example, are represented using the strings "yes" and "no". Properties whose values are QNames, such as cdata-section-elements are expressed using the Clark representation of a QName, that is "{uri}local". Multi-valued properties (again, cdata-section-elements is an example) are expressed as a space-separated list.

Throws:

java.lang.IllegalArgumentException - if the value of the property is invalid. The property is validated individually; invalid combinations of properties will be detected only when the properties are actually used to serialize an XML event stream. No validation occurs unless the property name is either in no namespace, or in the Saxon namespace

getOutputProperty

public java.lang.String getOutputProperty(QName property)

Get the value of a serialization property.

Unlike the method getOutputProperty(Property), this method allows properties to be read whose names are not in the standard set of property names defined in the W3C specifications, nor in a recognized Saxon extension. This enables properties to be set for use by a custom serialization method.

Parameters:

property - the name of the required property

Returns:

the value of the required property as a string, or null if the property has not been given any value.

setOutputWriter

public void setOutputWriter(java.io.Writer writer)

Set the destination of the serialized output, as a Writer.

Note that when this option is used, the serializer does not perform character encoding. This also means that it never replaces special characters with XML numeric character references. The final encoding is the responsibility of the supplied Writer.

Closing the writer after use is the responsibility of the caller.

Calling this method has the side-effect of setting the OutputStream and OutputFile to null.

Parameters:

writer - the Writer to which the serialized XML output will be written.

setOutputStream

public void setOutputStream(java.io.OutputStream stream)

Set the destination of the serialized output, as an OutputStream.

Closing the output stream after use is the responsibility of the caller.

Calling this method has the side-effect of setting the OutputWriter and OutputFile to null.

Parameters:

stream - the OutputStream to which the serialized XML output will be written.

setOutputFile

public void setOutputFile(java.io.File file)

Set the destination of the serialized output, as a File.

Calling this method has the side-effect of setting the current OutputWriter and OutputStream to null.

Parameters:

file - the File to which the serialized XML output will be written.

serializeNode

public void serializeNode(XdmNode node)
                   throws SaxonApiException

Serialize an XdmNode to the selected output destination using this serializer

Parameters:

node - The node to be serialized

Throws:

java.lang.IllegalStateException - if no outputStream, Writer, or File has been supplied as the destination for the serialized output

SaxonApiException - if a serialization error or I/O error occurs

Since:

9.3

serializeXdmValue

public void serializeXdmValue(XdmValue value)
                       throws SaxonApiException

Serialize an arbitrary XdmValue to the selected output destination using this serializer. The supplied sequence is first wrapped in a document node according to the rules given in section 2 (Sequence Normalization) of the XSLT/XQuery serialization specification; the resulting document nodes is then serialized using the serialization parameters defined in this serializer.

Parameters:

value - The value to be serialized

Throws:

java.lang.IllegalStateException - if no outputStream, Writer, or File has been supplied as the destination for the serialized output, or if no Processor is associated with the serializer

SaxonApiException - if a serialization error or I/O error occurs

Since:

9.3

serializeNodeToString

public java.lang.String serializeNodeToString(XdmNode node)
                                       throws SaxonApiException

Serialize an XdmNode to a string using this serializer

Parameters:

node - The node to be serialized

Returns:

the serialized representation of the node as lexical XML

Throws:

SaxonApiException - if a serialization error occurs

Since:

9.3

getXMLStreamWriter

public StreamWriterToReceiver getXMLStreamWriter()
                                          throws SaxonApiException

Get an XMLStreamWriter that can be used for writing application-generated XML to be output via this serializer.

Returns:

a newly constructed XMLStreamWriter that pipes events into this Serializer

Throws:

java.lang.IllegalStateException - if no Processor has been set for this Serializer

SaxonApiException - if any other failure occurs

Since:

9.3

getContentHandler

public org.xml.sax.ContentHandler getContentHandler()
                                             throws SaxonApiException

Get a ContentHandler that can be used to direct the output of a SAX parser (or other source of SAX events) to this serializer.

Returns:

a newly constructed ContentHandler that pipes events into this Serializer

Throws:

java.lang.IllegalStateException - if no Processor has been set for this Serializer

SaxonApiException - if any other failure occurs

Since:

9.7

getOutputDestination

public java.lang.Object getOutputDestination()

Get the current output destination.

Returns:

an OutputStream, Writer, or File, depending on the previous calls to setOutputStream(java.io.OutputStream), setOutputWriter(java.io.Writer), or setOutputFile(java.io.File); or null, if no output destination has been set up.

getReceiver

public Receiver getReceiver(Configuration config)
                     throws SaxonApiException

Return a receiver to which Saxon will send events. This method is provided primarily for internal use, though it could also be called by user applications wanting to make use of the Saxon serializer.

Specified by:

getReceiver in interface Destination

Parameters:

config - The Saxon configuration. This is an internal implementation object held within the Processor

Returns:

a receiver to which XML events will be sent

Throws:

SaxonApiException - if the Receiver cannot be created

getReceiver

public Receiver getReceiver(PipelineConfiguration pipe)
                     throws SaxonApiException

Return a receiver to which Saxon will send events. This method is provided primarily for internal use, though it could also be called by user applications wanting to make use of the Saxon serializer.

Parameters:

pipe - The Saxon pipeline configuration. This is an internal implementation object held within the Processor

Returns:

a receiver to which XML events will be sent

Throws:

SaxonApiException

getReceiver

public Receiver getReceiver(Executable executable)
                     throws SaxonApiException

Return a receiver to which Saxon will send events. This method is provided primarily for internal use, though it could also be called by user applications wanting to make use of the Saxon serializer.

Parameters:

executable - The Saxon Executable for the transformation or query. The serialization properties defined in this Serializer are supplemented by properties that have been defined in the query or stylesheet associated with the Executable. The properties defined in this Serializer take precedence over those in the stylesheet or query.

Returns:

a receiver to which XML events will be sent

Throws:

SaxonApiException - if any failure occurs

getCombinedOutputProperties

public java.util.Properties getCombinedOutputProperties()

Create a Properties object holding the defined serialization properties. This will be in the same format as JAXP interfaces such as Transformer.getOutputProperties()

Returns:

a newly-constructed Properties object holding the declared serialization properties. Specifically, it holds the properties defined explicitly on this Serializer object, backed by the properties defined in unnamed xsl:output declarations in the stylesheet, or output declarations in XQuery.

getLocalOutputProperties

protected java.util.Properties getLocalOutputProperties()

Create a Properties object holding the serialization properties explicitly declared within this Serializer object, and not including any defaults taken from the stylesheet or query.

Returns:

a newly-constructed Properties object holding the declared serialization properties. Specifically, it holds the properties defined explicitly on this Serializer object, and excludes any properties defined in named or unnamed xsl:output declarations in the stylesheet, or the equivalent in XQuery.

getResult

protected javax.xml.transform.Result getResult()

Get the JAXP StreamResult object representing the output destination of this serializer

close

public void close()
           throws SaxonApiException

Close any resources associated with this destination. Note that this does not close any user-supplied OutputStream or Writer; those must be closed explicitly by the calling application.

Specified by:

close in interface Destination

Throws:

SaxonApiException - if any failure occurs

getProperty

public static Serializer.Property getProperty(QName name)

Get the Property with a given QName

Parameters:

name - the QName of the required property, which must be either a standard property defined in the XSLT 3.0 / XQuery 3.0 serialization specification, or an extension property defined by Saxon in the Saxon namespace

Returns:

the corresponding Property object

Throws:

java.lang.IllegalArgumentException - if the name is not a recognized serialization property name.

Since:

9.6

isMustCloseAfterUse

public boolean isMustCloseAfterUse()