com.icl.saxon.trax.serialize
Interface Serializer


public interface Serializer

Interface to a serializer implementation. A serializer is used for serializing a document through one of three interfaces. The serializer object serves as an anchor point for setting the output stream and output format, for obtaining any of these interfaces, and for resetting the serializer.

A serializer is created from SerializerFactory.

Prior to using the serializer, the output format and output stream or writer should be set. The serializer is then used in one of three ways:

The serializer may be reused with the same output format and output stream, or different output format and output stream, by calling the reset() method after completing serialization. The document handler or DOMSerializer must be re-acquired after a successful return from reset().

A serializer is not thread safe. Only one thread should call the asXXX methods and use the returned document handler, or DOM serializer.

Example:

 ser = SerializerFactory.getSerializer( Method.XML );
 emptyDoc( ser, System.out );
 emptyDoc( ser, System.err );
 . . . 

 void emptyDoc( Serializer ser, OutputStream os )
 {
   ser.setOutputStream( os );
   ser.asDocumentHandler().startDocument();
   ser.asDocumentHandler().startElement( "empty", new AttributeListImpl() );
   ser.asDocumentHandler().endElement( "empty" );
   ser.asDocumentHandler().endDocument();
   ser.reset();
 }
 


Method Summary
 org.xml.sax.ContentHandler asContentHandler()
          Return a ContentHandler interface into this serializer.
 org.xml.sax.DocumentHandler asDocumentHandler()
          Return a DocumentHandler interface into this serializer.
 DOMSerializer asDOMSerializer()
          Return a DOMSerializer interface into this serializer.
 OutputFormat getOutputFormat()
          Returns the output format for this serializer.
 boolean reset()
          Resets the serializer.
 void setOutputFormat(OutputFormat 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

public void setOutputStream(java.io.OutputStream output)
                     throws java.io.UnsupportedEncodingException
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 OutputFormat is used, or if no encoding was specified, the default for the selected output method.

Parameters:
output - The output stream
UnsupportedEncodingException - The encoding specified in the output format is not supported

setWriter

public 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 OutputFormat must be identical to the output format used with the writer.

Parameters:
writer - The output writer stream

setOutputFormat

public void setOutputFormat(OutputFormat 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.
Parameters:
format - The output format to use

getOutputFormat

public OutputFormat getOutputFormat()
Returns the output format for this serializer.
Returns:
The output format in use

asDocumentHandler

public org.xml.sax.DocumentHandler asDocumentHandler()
Return a DocumentHandler interface into this serializer. If the serializer does not support the DocumentHandler interface, it should return null.

asContentHandler

public org.xml.sax.ContentHandler asContentHandler()
Return a ContentHandler interface into this serializer. If the serializer does not support the ContentHandler interface, it should return null.

asDOMSerializer

public DOMSerializer asDOMSerializer()
Return a DOMSerializer interface into this serializer. If the serializer does not support the DOMSerializer interface, it should return null.

reset

public boolean reset()
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 use the existing output format and output stream.
Returns:
True if serializer has been reset and can be reused