OpenJDK 1.23 · com.sun.org.apache.xml.internal.serializer.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;
com.sun.org.apache.xml.internal.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.

Method Summary

Modifier and Type	Method and Description
public ContentHandler	Returns: A `ContentHandler` interface into this serializer, or null if the serializer is not SAX 2 capable asContentHandler() Return a `ContentHandler` interface to provide SAX input to.
public Object	Returns: An Object to be cast to a DOM3Serializer interface into this serializer, or null if the serializer is not DOM capable asDOM3Serializer() Return an Object into this serializer to be cast to a DOM3Serializer.
public DOMSerializer	Returns: A `DOMSerializer` interface into this serializer, or null if the serializer is not DOM capable asDOMSerializer() Return a `DOMSerializer` interface into this serializer.
public Properties	Returns: The output format key/value pairs in use. getOutputFormat() Returns the output format properties for this serializer.
public OutputStream	Returns: reference to the result stream, or null if only a writer was set. getOutputStream() Get the output stream where the events will be serialized to.
public Writer	Returns: Reference to the result Writer, or null. getWriter() Get the character stream where the events will be serialized to.
public boolean	Returns: True if serializer has been reset and can be reused reset() This method resets the serializer.
public void	setOutputFormat(Properties The output format to use, as a set of key/value pairs. format) Specifies an output format for this serializer.
public void	setOutputStream(OutputStream The output stream output) Specifies an output stream to which the document should be serialized.
public void	setWriter(Writer The output writer stream writer) Specifies a writer to which the document should be serialized.

Method Detail

asContentHandler back to summary

asContentHandler	back to summary
public ContentHandler asContentHandler() throws 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:ContentHandler A `ContentHandler` interface into this serializer, or null if the serializer is not SAX 2 capable Exceptions IOException: An I/O exception occured

public ContentHandler asContentHandler() throws 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:ContentHandler

A ContentHandler interface into this serializer, or null if the serializer is not SAX 2 capable

Exceptions

IOException:: An I/O exception occured

asDOM3Serializer back to summary

asDOM3Serializer	back to summary
public Object asDOM3Serializer() throws 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:Object An Object to be cast to a DOM3Serializer interface into this serializer, or null if the serializer is not DOM capable Exceptions IOException: An I/O exception occured

public Object asDOM3Serializer() throws 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:Object

An Object to be cast to a DOM3Serializer interface into this serializer, or null if the serializer is not DOM capable

Exceptions

IOException:: An I/O exception occured

asDOMSerializer back to summary

asDOMSerializer	back to summary
public DOMSerializer asDOMSerializer() throws 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:DOMSerializer A `DOMSerializer` interface into this serializer, or null if the serializer is not DOM capable Exceptions IOException: An I/O exception occured

public DOMSerializer asDOMSerializer() throws 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:DOMSerializer

A DOMSerializer interface into this serializer, or null if the serializer is not DOM capable

Exceptions

IOException:: An I/O exception occured

getOutputFormat	back to summary
public Properties getOutputFormat() Returns the output format properties for this serializer. Returns:Properties The output format key/value pairs in use.

getOutputFormat

back to summary

public Properties getOutputFormat()

Returns the output format properties for this serializer.

Returns:Properties: The output format key/value pairs in use.

getOutputStream	back to summary
public OutputStream getOutputStream() Get the output stream where the events will be serialized to. Returns:OutputStream reference to the result stream, or null if only a writer was set.

getOutputStream

back to summary

public OutputStream getOutputStream()

Get the output stream where the events will be serialized to.

Returns:OutputStream: reference to the result stream, or null if only a writer was set.

getWriter	back to summary
public Writer getWriter() Get the character stream where the events will be serialized to. Returns:Writer Reference to the result Writer, or null.

getWriter

back to summary

public Writer getWriter()

Get the character stream where the events will be serialized to.

Returns:Writer: Reference to the result Writer, or null.

reset	back to summary
public 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:boolean True if serializer has been reset and can be reused

reset

back to summary

public 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:boolean: True if serializer has been reset and can be reused

setOutputFormat back to summary

setOutputFormat	back to summary
public void setOutputFormat(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 `href="http://www.w3.org/TR/1999/REC-xslt-19991116"> XSLT 1.0 recommendation</a>` 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:Properties The output format to use, as a set of key/value pairs.

public void setOutputFormat(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 href="http://www.w3.org/TR/1999/REC-xslt-19991116"> XSLT 1.0 recommendation</a>

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:Properties: The output format to use, as a set of key/value pairs.

setOutputStream back to summary

setOutputStream	back to summary
public void setOutputStream(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:OutputStream The output stream

public void setOutputStream(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:OutputStream: The output stream

setWriter back to summary

setWriter	back to summary
public void setWriter(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:Writer The output writer stream

public void setWriter(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:Writer: The output writer stream

public Interface Serializer

Method Summary

Method Detail