org.apache.serialize
Interface Serializer

All Known Implementing Classes:
BaseMarkupSerializer

public interface Serializer

A serializer is used for serializing a document with a given output method. The Serializer object serves as an anchor point for setting the output stream and output format, for obtaining objects for serializing the document, and for resetting the serializer.

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 application may call one of these methods to obtain a way to serialize the document. It may not attempt to use two different handlers at the same time, nor should it use the same handler to serialize two documents.

The serializer may be recycled and used with a different or the same output format and output stream, by calling the reset() method after completing serialization.

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

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
 ContentHandler asContentHandler()
          Return a ContentHandler interface into this serializer.
 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.
 java.io.OutputStream getOutputStream()
           
 java.io.Writer getWriter()
           
 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)
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

getOutputStream

public java.io.OutputStream getOutputStream()

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

getWriter

public java.io.Writer getWriter()

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 DocumentHandler asDocumentHandler()
                                  throws java.io.IOException
Return a DocumentHandler interface into this serializer. If the serializer does not support the DocumentHandler interface, it should return null.
Returns:
A DocumentHandler interface into this serializer, or null if the serializer is not SAX 1 capable
Throws:
java.io.IOException - An I/O exception occured

asContentHandler

public ContentHandler asContentHandler()
                                throws java.io.IOException
Return a ContentHandler interface into this serializer. If the serializer does not support the ContentHandler interface, it should return null.
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

public DOMSerializer asDOMSerializer()
                              throws java.io.IOException
Return a DOMSerializer interface into this serializer. If the serializer does not support the DOMSerializer interface, it should return null.
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

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


Copyright © 2000 Apache XML Project. All Rights Reserved.