001: /*
002: * Copyright 1999-2004 The Apache Software Foundation.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016: /*
017: * $Id: Serializer.java,v 1.5 2005/04/07 04:29:03 minchau Exp $
018: */
019: package org.apache.xml.serializer;
020:
021: import java.io.IOException;
022: import java.io.OutputStream;
023: import java.io.Writer;
024: import java.util.Properties;
025:
026: import org.xml.sax.ContentHandler;
027:
028: /**
029: * The Serializer interface is implemented by a serializer to enable users to:
030: * <ul>
031: * <li>get and set streams or writers
032: * <li>configure the serializer with key/value properties
033: * <li>get an org.xml.sax.ContentHandler or a DOMSerializer to provide input to
034: * </ul>
035: *
036: * <p>
037: * Here is an example using the asContentHandler() method:
038: * <pre>
039: * java.util.Properties props =
040: * OutputPropertiesFactory.getDefaultMethodProperties(Method.TEXT);
041: * Serializer ser = SerializerFactory.getSerializer(props);
042: * java.io.PrintStream ostream = System.out;
043: * ser.setOutputStream(ostream);
044: *
045: * // Provide the SAX input events
046: * ContentHandler handler = ser.asContentHandler();
047: * handler.startDocument();
048: * char[] chars = { 'a', 'b', 'c' };
049: * handler.characters(chars, 0, chars.length);
050: * handler.endDocument();
051: *
052: * ser.reset(); // get ready to use the serializer for another document
053: * // of the same output method (TEXT).
054: * </pre>
055: *
056: * <p>
057: * As an alternate to supplying a series of SAX events as input through the
058: * ContentHandler interface, the input to serialize may be given as a DOM.
059: * <p>
060: * For example:
061: * <pre>
062: * org.w3c.dom.Document inputDoc;
063: * org.apache.xml.serializer.Serializer ser;
064: * java.io.Writer owriter;
065: *
066: * java.util.Properties props =
067: * OutputPropertiesFactory.getDefaultMethodProperties(Method.XML);
068: * Serializer ser = SerializerFactory.getSerializer(props);
069: * owriter = ...; // create a writer to serialize the document to
070: * ser.setWriter( owriter );
071: *
072: * inputDoc = ...; // create the DOM document to be serialized
073: * DOMSerializer dser = ser.asDOMSerializer(); // a DOM will be serialized
074: * dser.serialize(inputDoc); // serialize the DOM, sending output to owriter
075: *
076: * ser.reset(); // get ready to use the serializer for another document
077: * // of the same output method.
078: * </pre>
079: *
080: * This interface is a public API.
081: *
082: * @see Method
083: * @see OutputPropertiesFactory
084: * @see SerializerFactory
085: * @see DOMSerializer
086: * @see ContentHandler
087: *
088: * @xsl.usage general
089: */
090: public interface Serializer {
091:
092: /**
093: * Specifies an output stream to which the document should be
094: * serialized. This method should not be called while the
095: * serializer is in the process of serializing a document.
096: * <p>
097: * The encoding specified in the output {@link Properties} is used, or
098: * if no encoding was specified, the default for the selected
099: * output method.
100: * <p>
101: * Only one of setWriter() or setOutputStream() should be called.
102: *
103: * @param output The output stream
104: */
105: public void setOutputStream(OutputStream output);
106:
107: /**
108: * Get the output stream where the events will be serialized to.
109: *
110: * @return reference to the result stream, or null if only a writer was
111: * set.
112: */
113: public OutputStream getOutputStream();
114:
115: /**
116: * Specifies a writer to which the document should be serialized.
117: * This method should not be called while the serializer is in
118: * the process of serializing a document.
119: * <p>
120: * The encoding specified for the output {@link Properties} must be
121: * identical to the output format used with the writer.
122: *
123: * <p>
124: * Only one of setWriter() or setOutputStream() should be called.
125: *
126: * @param writer The output writer stream
127: */
128: public void setWriter(Writer writer);
129:
130: /**
131: * Get the character stream where the events will be serialized to.
132: *
133: * @return Reference to the result Writer, or null.
134: */
135: public Writer getWriter();
136:
137: /**
138: * Specifies an output format for this serializer. It the
139: * serializer has already been associated with an output format,
140: * it will switch to the new format. This method should not be
141: * called while the serializer is in the process of serializing
142: * a document.
143: * <p>
144: * The standard property keys supported are: "method", "version", "encoding",
145: * "omit-xml-declaration", "standalone", doctype-public",
146: * "doctype-system", "cdata-section-elements", "indent", "media-type".
147: * These property keys and their values are described in the XSLT recommendation,
148: * see {@link <a href="http://www.w3.org/TR/1999/REC-xslt-19991116"> XSLT 1.0 recommendation</a>}
149: * <p>
150: * The non-standard property keys supported are defined in {@link OutputPropertiesFactory}.
151: *
152: * <p>
153: * This method can be called multiple times before a document is serialized. Each
154: * time it is called more, or over-riding property values, can be specified. One
155: * property value that can not be changed is that of the "method" property key.
156: * <p>
157: * The value of the "cdata-section-elements" property key is a whitespace
158: * separated list of elements. If the element is in a namespace then
159: * value is passed in this format: {uri}localName
160: * <p>
161: * If the "cdata-section-elements" key is specified on multiple calls
162: * to this method the set of elements specified in the value
163: * is not replaced from one call to the
164: * next, but it is cumulative across the calls.
165: *
166: * @param format The output format to use, as a set of key/value pairs.
167: */
168: public void setOutputFormat(Properties format);
169:
170: /**
171: * Returns the output format properties for this serializer.
172: *
173: * @return The output format key/value pairs in use.
174: */
175: public Properties getOutputFormat();
176:
177: /**
178: * Return a {@link ContentHandler} interface to provide SAX input to.
179: * Through the returned object the document to be serailized,
180: * as a series of SAX events, can be provided to the serialzier.
181: * If the serializer does not support the {@link ContentHandler}
182: * interface, it will return null.
183: * <p>
184: * In principle only one of asDOMSerializer() or asContentHander()
185: * should be called.
186: *
187: * @return A {@link ContentHandler} interface into this serializer,
188: * or null if the serializer is not SAX 2 capable
189: * @throws IOException An I/O exception occured
190: */
191: public ContentHandler asContentHandler() throws IOException;
192:
193: /**
194: * Return a {@link DOMSerializer} interface into this serializer.
195: * Through the returned object the document to be serialized,
196: * a DOM, can be provided to the serializer.
197: * If the serializer does not support the {@link DOMSerializer}
198: * interface, it should return null.
199: * <p>
200: * In principle only one of asDOMSerializer() or asContentHander()
201: * should be called.
202: *
203: * @return A {@link DOMSerializer} interface into this serializer,
204: * or null if the serializer is not DOM capable
205: * @throws IOException An I/O exception occured
206: */
207: public DOMSerializer asDOMSerializer() throws IOException;
208:
209: /**
210: * This method resets the serializer.
211: * If this method returns true, the
212: * serializer may be used for subsequent serialization of new
213: * documents. It is possible to change the output format and
214: * output stream prior to serializing, or to reuse the existing
215: * output format and output stream or writer.
216: *
217: * @return True if serializer has been reset and can be reused
218: */
219: public boolean reset();
220: }
|