* 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 Method * @see OutputPropertiesFactory * @see SerializerFactory * @see DOMSerializer * @see ContentHandler * * @xsl.usage general */ public interface Serializer { /** * 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 {@link 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. * * @param output The output stream */ public void setOutputStream(OutputStream output); /** * Get the output stream where the events will be serialized to. * * @return reference to the result stream, or null if only a writer was * set. */ public OutputStream getOutputStream(); /** * 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 {@link Properties} must be * identical to the output format used with the writer. * *
* Only one of setWriter() or setOutputStream() should be called. * * @param writer The output writer stream */ public void setWriter(Writer writer); /** * Get the character stream where the events will be serialized to. * * @return Reference to the result Writer, or null. */ public Writer getWriter(); /** * 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 {@link XSLT 1.0 recommendation} *
* The non-standard property keys supported are defined in {@link 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. * * @param format The output format to use, as a set of key/value pairs. */ public void setOutputFormat(Properties format); /** * Returns the output format properties for this serializer. * * @return The output format key/value pairs in use. */ public Properties getOutputFormat(); /** * Return a {@link 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 {@link ContentHandler} * interface, it will return null. *
* In principle only one of asDOMSerializer() or asContentHander() * should be called. * * @return A {@link ContentHandler} interface into this serializer, * or null if the serializer is not SAX 2 capable * @throws IOException An I/O exception occured */ public ContentHandler asContentHandler() throws IOException; /** * Return a {@link 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 {@link DOMSerializer} * interface, it should return null. *
* In principle only one of asDOMSerializer() or asContentHander() * should be called. * * @return A {@link DOMSerializer} interface into this serializer, * or null if the serializer is not DOM capable * @throws IOException An I/O exception occured */ public DOMSerializer asDOMSerializer() throws IOException; /** * 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. * * @return True if serializer has been reset and can be reused */ public boolean reset(); /** * 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 {@link DOM3Serializer} * interface, it should return null. *
* In principle only one of asDOM3Serializer() or asContentHander() * should be called. * * @return An Object to be cast to a DOM3Serializer interface into this serializer, * or null if the serializer is not DOM capable * @throws IOException An I/O exception occured */ public Object asDOM3Serializer() throws IOException; }