Package net.sf.saxon.s9api

Class Serializer

  • All Implemented Interfaces:
    Destination
    public class Serializer
extends AbstractDestination
    A Serializer takes a tree representation of XML and turns it into lexical XML markup.

    To construct a Serializer, use the factory method Processor.newSerializer(File).

    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 3.0 and XQuery 3.1 Serialization. Saxon supports all the serialization parameters defined in that specification, together with some additional parameters, whose property names are prefixed "SAXON_".

    A Serializer may also be created from an Xslt30Transformer using the method Xslt30Transformer.newSerializer() or one of its variants. In this case the serializer is initialized with properties taken from the default output declaration in the stylesheet.

    Serialization parameters set explicitly on the Serializer take precedence over any serialization parameters supplied when getReceiver(net.sf.saxon.event.PipelineConfiguration, net.sf.saxon.serialize.SerializationProperties) is called. The getReceiver(net.sf.saxon.event.PipelineConfiguration, net.sf.saxon.serialize.SerializationProperties) method is supplied with parameters derived from the query or stylesheet, which are merged with the parameters set on this Serializer.

    Any serialization parameters that are not given an explicit value using one of these mechanisms are defaulted using the rules for the XSLT 3.0 xsl:output declaration. In particular, this means that the default serialization method (when serializing an XDM document) depends on the name of the first element encountered in the document.

    Changed in 9.9 so the Serializer now only holds one set of output properties. Additional serialization properties can be supplied when getReceiver(PipelineConfiguration, SerializationProperties) is called, but these are not stored within the Serializer itself.

    • Constructor Detail

      • Serializer

        protected Serializer​(Processor processor)
        Create a Serializer belonging to a specific processor
        Parameters:
        processor - the processor associated with the Serializer. Must not be null.

    • 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.
        Parameters:
        processor - the associated Processor (must not be null)
        Since:
        9.3

      • getProcessor

        public Processor getProcessor()
        Get the Processor associated with this Serializer.
        Returns:
        the associated Processor. Never null.

      • setOutputProperties

        public void setOutputProperties​(java.util.Properties suppliedProperties)
        Set output properties, from a Properties object. The keys in the supplied Properties object are QNames in Clark format, that is "{uri}local"; any QNames within the values must also be in this format.
        Parameters:
        suppliedProperties - the output properties to be used. These overwrite any properties that have been individually specified using setOutputProperty(Property, String) setOutputProperty}

      • setOutputProperties

        public void setOutputProperties​(SerializationProperties suppliedProperties)
        Set output properties, from an SerializationProperties object. The keys in the contained Properties object are QNames in Clark format, that is "{uri}local"; any QNames within the values must also be in this format.

        The values supplied are typically those specified in the stylesheet or query. In the case of XSLT, they are typically the properties associated with unnamed xsl:output declarations.

        Parameters:
        suppliedProperties - the output properties to be used. These overwrite any properties that have been individually specified using setOutputProperty(Property, String) setOutputProperty}
        Since:
        9.9

      • 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 supplied 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.

      • getCharacterMapIndex

        public CharacterMapIndex getCharacterMapIndex()
        Get the character map index in use
        Returns:
        a set of named character maps.

      • 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.

        This method sets the destination base URI to the URI corresponding to the name of the supplied file.

        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.

        If the supplied XdmValue is an XdmNode, then it is serialized using the serializeNode(XdmNode) method. In other cases, it behaves in a way equivalent to XSLT serialization with build-tree="no"; this is the recommended way to output non-node values using the JSON or Adaptive serialization methods.

        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
        SaxonApiException - if a serialization error or I/O error occurs
        Since:
        9.3

      • serialize

        public void serialize​(javax.xml.transform.Source source)
               throws SaxonApiException
        Serialize an arbitrary JAXP Source 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.

        The default serialization properties used by this method correspond to the properties used by an XSLT 3.0 stylesheet with no xsl:output declaration. In particular, the default output method (always one of XML, XHTML, or HTML) depends on the name of the first element node encountered.

        Parameters:
        source - 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
        SaxonApiException - if a serialization error or I/O error occurs
        Since:
        10.0

      • serializeToString

        public java.lang.String serializeToString​(javax.xml.transform.Source source)
                                   throws SaxonApiException
        Serialize an arbitrary JAXP Source to a string 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.

        The default serialization properties used by this method correspond to the properties used by an XSLT 3.0 stylesheet with no xsl:output declaration. In particular, the default output method (always one of XML, XHTML, or HTML) depends on the name of the first element node encountered.

        Parameters:
        source - The value to be serialized
        Returns:
        the serialized result, as a string
        Throws:
        SaxonApiException - if a serialization error or I/O error occurs
        Since:
        10.0

      • serializeNodeToString

        public java.lang.String serializeNodeToString​(XdmNode node)
                                       throws SaxonApiException
        Serialize an XdmNode to a string using this serializer

        The default serialization properties used by this method correspond to the properties used by an XSLT 3.0 stylesheet with no xsl:output declaration. In particular, the default output method (always one of XML, XHTML, or HTML) depends on the name of the first element node encountered.

        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.

        The default serialization properties used by this method correspond to the properties used by an XSLT 3.0 stylesheet with no xsl:output declaration. In particular, the default output method (always one of XML, XHTML, or HTML) depends on the name of the first element node encountered.

        Returns:
        a newly constructed XMLStreamWriter that pipes events into this Serializer
        Throws:
        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.

        The default serialization properties used by this method correspond to the properties used by an XSLT 3.0 stylesheet with no xsl:output declaration. In particular, the default output method (always one of XML, XHTML, or HTML) depends on the name of the first element node encountered.

        Returns:
        a newly constructed ContentHandler that pipes events into this Serializer
        Throws:
        SaxonApiException - if any other failure occurs
        Since:
        9.7

      • getReceiver

        public Receiver getReceiver​(PipelineConfiguration pipe,
                            SerializationProperties params)
                     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 configuration. This is an internal implementation object held within the Processor
        params - Serialization parameters originating from the query or stylesheet (for example, xsl:output declarations or xsl:result-document attributes). These parameters are combined with those held by this Serializer itself, with properties set on the Serializer taking precedence. If a particular property has not been set either on the Serializer object itself or in the supplied params, the defaults follow the XSLT 3.0 rules.
        Returns:
        a receiver to which XML events will be sent
        Throws:
        SaxonApiException - if the Receiver cannot be created

      • getCombinedOutputProperties

        public java.util.Properties getCombinedOutputProperties​(java.util.Properties defaultOutputProperties)
        Create a Properties object holding the defined serialization properties. This will be in the same format as JAXP interfaces such as Transformer.getOutputProperties()
        Parameters:
        defaultOutputProperties - the default properties
        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 defaultOutputProperties.

      • getLocallyDefinedProperties

        protected java.util.Properties getLocallyDefinedProperties()
        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.

      • getSerializationProperties

        public SerializationProperties getSerializationProperties()
        Create a SerializationProperties object holding the serialization properties explicitly declared within this Serializer object (including any character map index), and not including any defaults taken from the stylesheet or query.
        Returns:
        a newly-constructed SerializationProperties 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
        Returns:
        the JAXP StreamResult object

      • 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.
        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()