net.sf.saxon.s9api

## Class Serializer

- java.lang.Object
- - net.sf.saxon.s9api.Serializer

- All Implemented Interfaces:
    Destination

      public class Serializer
      extends 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
    Constructor and Description
    `Serializer()` Create a Serializer
    `Serializer(File file)` Create a Serializer initialized to write to a given File.
    `Serializer(OutputStream stream)` Create a Serializer initialized to write to a given OutputStream.
    `Serializer(Writer writer)` Create a Serializer initialized to write to a given Writer.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` Close any resources associated with this destination.
    `Object` | `getOutputDestination()` Get the current output destination.
    `protected Properties` | `getOutputProperties()` Create a Properties object holding the defined serialization properties.
    `String` | `getOutputProperty(Serializer.Property property)` Get the value of a serialization property
    `Receiver` | `getReceiver(Configuration config)` Return a receiver to which Saxon will send events.
    `protected Receiver` | `getReceiver(Executable executable)` Return a receiver to which Saxon will send events.
    `protected 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.
    `void` | `serializeNode(XdmNode node)` Serialize an XdmNode to the selected output destination using this serializer
    `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` | `setOutputFile(File file)` Set the destination of the serialized output, as a File.
    `void` | `setOutputProperty(Serializer.Property property, String value)` Set the value of a serialization property.
    `void` | `setOutputStream(OutputStream stream)` Set the destination of the serialized output, as an OutputStream.
    `void` | `setOutputWriter(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

          public Serializer()

      Create a Serializer

    - #### Serializer

          public Serializer(OutputStream stream)

      Create a Serializer initialized to write to a given OutputStream.

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

      Parameters:
        `stream` - The OutputStream to which the Serializer will write

    - #### Serializer

          public Serializer(Writer writer)

      Create a Serializer initialized to write to a given Writer.

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

      Parameters:
        `writer` - The Writer to which the Serializer will write

    - #### Serializer

          public Serializer(File file)

      Create a Serializer initialized to write to a given File.
      Parameters:
        `file` - The File to which the Serializer will write

  - ### 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
      Since:
        9.3

    - #### setOutputProperty

          public void setOutputProperty(Serializer.Property property,
                               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.

      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:
        `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 String getOutputProperty(Serializer.Property property)

      Get the value of a serialization property
      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(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(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(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:
        `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:
        `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 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:
        `IllegalStateException` - if no Processor has been set for this Serializer
        `SaxonApiException` - if any other failure occurs
      Since:
        9.3

    - #### getOutputDestination

          public 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

          protected 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

    - #### getOutputProperties

          protected Properties getOutputProperties()

      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

    - #### getResult

          protected 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

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