org.apache.xml.serializer

## Interface Serializer

- All Known Subinterfaces:
    SerializationHandler
  All Known Implementing Classes:
    AdaptiveResultTreeImpl, EmptySerializer, SerializerBase, SimpleResultTreeImpl, StringValueHandler, ToHTMLSAXHandler, ToHTMLStream, ToSAXHandler, ToStream, ToTextSAXHandler, ToTextStream, ToUnknownStream, ToXMLSAXHandler, ToXMLStream

      public interface Serializer

  The Serializer interface is implemented by a serializer to enable users to:
  - get and set streams or writers
  - configure the serializer with key/value properties
  - get an org.xml.sax.ContentHandler or a DOMSerializer to provide input to

  Here is an example using the asContentHandler() method:

       java.util.Properties props =
         OutputPropertiesFactory.getDefaultMethodProperties(Method.TEXT);
       Serializer ser = SerializerFactory.getSerializer(props);
       java.io.PrintStream ostream = System.out;
       ser.setOutputStream(ostream);

       // Provide the SAX input events
       ContentHandler handler = ser.asContentHandler();
       handler.startDocument();
       char[] chars = { 'a', 'b', 'c' };
       handler.characters(chars, 0, chars.length);
       handler.endDocument();

       ser.reset(); // get ready to use the serializer for another document
                    // of the same output method (TEXT).

  As an alternate to supplying a series of SAX events as input through the ContentHandler interface, the input to serialize may be given as a DOM.

  For example:

       org.w3c.dom.Document     inputDoc;
       org.apache.xml.serializer.Serializer   ser;
       java.io.Writer owriter;

       java.util.Properties props =
         OutputPropertiesFactory.getDefaultMethodProperties(Method.XML);
       Serializer ser = SerializerFactory.getSerializer(props);
       owriter = ...;  // create a writer to serialize the document to
       ser.setWriter( owriter );

       inputDoc = ...; // create the DOM document to be serialized
       DOMSerializer dser = ser.asDOMSerializer(); // a DOM will be serialized
       dser.serialize(inputDoc); // serialize the DOM, sending output to owriter

       ser.reset(); // get ready to use the serializer for another document
                    // of the same output method.

  This interface is a public API.
  See Also:
    `Method`, `OutputPropertiesFactory`, `SerializerFactory`, `DOMSerializer`, `ContentHandler`
  Usage:

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `org.xml.sax.ContentHandler` | `asContentHandler()` Return a `ContentHandler` interface to provide SAX input to.
    `java.lang.Object` | `asDOM3Serializer()` Return an Object into this serializer to be cast to a DOM3Serializer.
    `DOMSerializer` | `asDOMSerializer()` Return a `DOMSerializer` interface into this serializer.
    `java.util.Properties` | `getOutputFormat()` Returns the output format properties for this serializer.
    `java.io.OutputStream` | `getOutputStream()` Get the output stream where the events will be serialized to.
    `java.io.Writer` | `getWriter()` Get the character stream where the events will be serialized to.
    `boolean` | `reset()` This method resets the serializer.
    `void` | `setOutputFormat(java.util.Properties format)` Specifies an output format for this serializer.
    `void` | `setOutputStream(java.io.OutputStream output)` Specifies an output stream to which the document should be serialized.
    `void` | `setWriter(java.io.Writer writer)` Specifies a writer to which the document should be serialized.

- - ### Method Detail

    - #### setOutputStream

          void setOutputStream(java.io.OutputStream output)

      Specifies an output stream to which the document should be serialized. This method should not be called while the serializer is in the process of serializing a document.

      The encoding specified in the output `Properties` is used, or if no encoding was specified, the default for the selected output method.

      Only one of setWriter() or setOutputStream() should be called.

      Parameters:
        `output` - The output stream

    - #### getOutputStream

          java.io.OutputStream getOutputStream()

      Get the output stream where the events will be serialized to.
      Returns:
        reference to the result stream, or null if only a writer was set.

    - #### setWriter

          void setWriter(java.io.Writer writer)

      Specifies a writer to which the document should be serialized. This method should not be called while the serializer is in the process of serializing a document.

      The encoding specified for the output `Properties` must be identical to the output format used with the writer.

      Only one of setWriter() or setOutputStream() should be called.

      Parameters:
        `writer` - The output writer stream

    - #### getWriter

          java.io.Writer getWriter()

      Get the character stream where the events will be serialized to.
      Returns:
        Reference to the result Writer, or null.

    - #### setOutputFormat

          void setOutputFormat(java.util.Properties format)

      Specifies an output format for this serializer. It the serializer has already been associated with an output format, it will switch to the new format. This method should not be called while the serializer is in the process of serializing a document.

      The standard property keys supported are: "method", "version", "encoding", "omit-xml-declaration", "standalone", doctype-public", "doctype-system", "cdata-section-elements", "indent", "media-type". These property keys and their values are described in the XSLT recommendation, see XSLT 1.0 recommendation

      The non-standard property keys supported are defined in `OutputPropertiesFactory`.

      This method can be called multiple times before a document is serialized. Each time it is called more, or over-riding property values, can be specified. One property value that can not be changed is that of the "method" property key.

      The value of the "cdata-section-elements" property key is a whitespace separated list of elements. If the element is in a namespace then value is passed in this format: {uri}localName

      If the "cdata-section-elements" key is specified on multiple calls to this method the set of elements specified in the value is not replaced from one call to the next, but it is cumulative across the calls.

      Parameters:
        `format` - The output format to use, as a set of key/value pairs.

    - #### getOutputFormat

          java.util.Properties getOutputFormat()

      Returns the output format properties for this serializer.
      Returns:
        The output format key/value pairs in use.

    - #### asContentHandler

          org.xml.sax.ContentHandler asContentHandler()
                                               throws java.io.IOException

      Return a `ContentHandler` interface to provide SAX input to. Through the returned object the document to be serailized, as a series of SAX events, can be provided to the serialzier. If the serializer does not support the `ContentHandler` interface, it will return null.

      In principle only one of asDOMSerializer() or asContentHander() should be called.

      Returns:
        A `ContentHandler` interface into this serializer, or null if the serializer is not SAX 2 capable
      Throws:
        `java.io.IOException` - An I/O exception occured

    - #### asDOMSerializer

          DOMSerializer asDOMSerializer()
                                 throws java.io.IOException

      Return a `DOMSerializer` interface into this serializer. Through the returned object the document to be serialized, a DOM, can be provided to the serializer. If the serializer does not support the `DOMSerializer` interface, it should return null.

      In principle only one of asDOMSerializer() or asContentHander() should be called.

      Returns:
        A `DOMSerializer` interface into this serializer, or null if the serializer is not DOM capable
      Throws:
        `java.io.IOException` - An I/O exception occured

    - #### reset

          boolean reset()

      This method resets the serializer. If this method returns true, the serializer may be used for subsequent serialization of new documents. It is possible to change the output format and output stream prior to serializing, or to reuse the existing output format and output stream or writer.
      Returns:
        True if serializer has been reset and can be reused

    - #### asDOM3Serializer

          java.lang.Object asDOM3Serializer()
                                     throws java.io.IOException

      Return an Object into this serializer to be cast to a DOM3Serializer. Through the returned object the document to be serialized, a DOM (Level 3), can be provided to the serializer. If the serializer does not support casting to a `DOM3Serializer` interface, it should return null.

      In principle only one of asDOM3Serializer() or asContentHander() should be called.

      Returns:
        An Object to be cast to a DOM3Serializer interface into this serializer, or null if the serializer is not DOM capable
      Throws:
        `java.io.IOException` - An I/O exception occured

Copyright © 2023 Apache XML Project. All Rights Reserved.