|
||||||||||
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES |
See:
Description
Interface Summary | |
DOMSerializer | Interface for a DOM serializer implementation. |
Serializer | A serializer is used for serializing a document with a given output method. |
SerializerHandler | Interface that supplements DocumentHandler and
ContentHandler with additional methods suitable
for serialization. |
Class Summary | |
Method | Names of the four default output methods. |
OutputFormat | The output format affects the manner in which a document is serialized. |
QName | A qualified name. |
SerializerFactory | Factory for creating default serializers. |
Defines an interface for SAX and DOM serializers, a serializer factory and its configuration, the output format properties, and related interfaces.
serialize.Serializer
defines the interface supported by
a serializer. A serializer implements a mechanism for producing output from
a series of SAX events or a DOM document, in a given format (aka the output
method). A serializer can be constructed directly, or obtained from some
factory, it may implement the base functionality or provide additional
functionality suitable for the given output method (e.g. indentation in
XML, page control in PDF, etc).
A serializer is not thread safe and may not be used concurrently, however, a serializer may be recyclable and used to serialize any number of documents with the same output method.
Before serializing a document, the serializer must be set with the output
stream or writer, and optionally with an serialize.OutputFormat
specifying the output properties. Serializer implementations may support
additional methods to control the way in which documents are serialized,
or extend serialize.OutputFormat
and offer additional
output properties.
serialize.Serializer
and serialize.OutputFormat
provides the minimum functionality that all serializers must support
and that an application may depend on, and are based on the XSLT 1.0
specification.
For the purpose of serializing, a handle to the serializer is obtained
that can be either a SAX 1 DocumentHandler, a SAX 2 ContentHandler
or a DOM Level 1/2 serialize.DOMSerializer
. The application
should obtain and use only one handle at any given time and may not reuse
the handle to serialize multiple documents. It is illegal for the application
to call two different handle returning methods without resetting the serializer,
or two use the same handle after resetting the serializer.
serialize.SerializerFactory
provides a means of obtaining
the default serializers available from a given implementation. At the minimum
an implementation should support XML, HTML and Text serializers. When additional
serializers are available, the application may obtain them through the serialize.SerializerFactory
or construct them directly.
Non-escaping and whitespace preserving output control is offered for
XML, HTML and similar output methods, but it is not mandatory that a
serializer support these output control methods. Non-escaping and whitespace
preserving can be set globally through serialize.OutputFormat
,
or directly when serializing SAX events through serialize.SerializerHandler
.
Serializers are not required to implement the serialize.SerializerHandler
interface.
Serialize a DOM document as XML:
void printXML( Document doc, OutputStream stream, String encoding ) { OutputFormat format; Serializer ser; // Obtain a suitable output format for the XML method and // set the encoding. format = SerializerFactory.getOutputFormat( Method.XML ); format.setEncoding( encoding ); // Obtain a suitable serializer for the XML method and // set the output stream. ser = SerializerFactory.getSerializer( format ); ser.setOutputStream( stream ); // Use DOMSerializer to serialize the document ser.asDOMSerializer().serialize( doc ); }
Serialize an empty HTML document using SAX events, reuse the serializer:
Serializer ser; // Obtain an HTML serializer once, use it multiple times. ser = SerializerFactory.getSerializer( Method.HTML ); printEmptyHTML( ser, System.out ); printEmptyHTML( ser, System.err ); . . . void printEmptyHTML( Serializer ser, OutputStream os ) { ser.setOutputStream( os ); ser.asDocumentHandler().startDocument(); ser.asDocumentHandler().startElement( "html", new AttributeListImpl() ); ser.asDocumentHandler().endElement( "html" ); ser.asDocumentHandler().endDocument(); ser.reset(); }
An implementation will include a serializer properties file called serializer.properties located in the serialize package. The properties file lists all the default serializers supported by that implementation. Serializers that are not listed in the properties file may be constructed directly by the application.
The properties file contains a property serialize.methods
listing all the output methods supported by the implementation (comma
separated list). For each method a property serialize.[method]
names the class of the serialize.Serializer
implementation.
The optional property serialize.format.[method] names the
class of a suitable serialize.OutputFormat
implementation.
|
||||||||||
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES |