1/*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the  "License");
7 * you may not use this file except in compliance with the License.
8 * You may obtain a copy of the License at
9 *
10 *     http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing, software
13 * distributed under the License is distributed on an "AS IS" BASIS,
14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 * See the License for the specific language governing permissions and
16 * limitations under the License.
17 */
18/*
19 * $Id: Serializer.java 471981 2006-11-07 04:28:00Z minchau $
20 */
21package org.apache.xml.serializer;
22import java.io.IOException;
23import java.io.OutputStream;
24import java.io.Writer;
25import java.util.Properties;
26
27import org.xml.sax.ContentHandler;
28
29/**
30 * The Serializer interface is implemented by a serializer to enable users to:
31 * <ul>
32 * <li>get and set streams or writers
33 * <li>configure the serializer with key/value properties
34 * <li>get an org.xml.sax.ContentHandler or a DOMSerializer to provide input to
35 * </ul>
36 *
37 * <p>
38 * Here is an example using the asContentHandler() method:
39 * <pre>
40 * java.util.Properties props =
41 *   OutputPropertiesFactory.getDefaultMethodProperties(Method.TEXT);
42 * Serializer ser = SerializerFactory.getSerializer(props);
43 * java.io.PrintStream ostream = System.out;
44 * ser.setOutputStream(ostream);
45 *
46 * // Provide the SAX input events
47 * ContentHandler handler = ser.asContentHandler();
48 * handler.startDocument();
49 * char[] chars = { 'a', 'b', 'c' };
50 * handler.characters(chars, 0, chars.length);
51 * handler.endDocument();
52 *
53 * ser.reset(); // get ready to use the serializer for another document
54 *              // of the same output method (TEXT).
55 * </pre>
56 *
57 * <p>
58 * As an alternate to supplying a series of SAX events as input through the
59 * ContentHandler interface, the input to serialize may be given as a DOM.
60 * <p>
61 * For example:
62 * <pre>
63 * org.w3c.dom.Document     inputDoc;
64 * org.apache.xml.serializer.Serializer   ser;
65 * java.io.Writer owriter;
66 *
67 * java.util.Properties props =
68 *   OutputPropertiesFactory.getDefaultMethodProperties(Method.XML);
69 * Serializer ser = SerializerFactory.getSerializer(props);
70 * owriter = ...;  // create a writer to serialize the document to
71 * ser.setWriter( owriter );
72 *
73 * inputDoc = ...; // create the DOM document to be serialized
74 * DOMSerializer dser = ser.asDOMSerializer(); // a DOM will be serialized
75 * dser.serialize(inputDoc); // serialize the DOM, sending output to owriter
76 *
77 * ser.reset(); // get ready to use the serializer for another document
78 *              // of the same output method.
79 * </pre>
80 *
81 * This interface is a public API.
82 *
83 * @see Method
84 * @see OutputPropertiesFactory
85 * @see SerializerFactory
86 * @see DOMSerializer
87 * @see ContentHandler
88 *
89 * @xsl.usage general
90 */
91public interface Serializer {
92
93    /**
94     * Specifies an output stream to which the document should be
95     * serialized. This method should not be called while the
96     * serializer is in the process of serializing a document.
97     * <p>
98     * The encoding specified in the output {@link Properties} is used, or
99     * if no encoding was specified, the default for the selected
100     * output method.
101     * <p>
102     * Only one of setWriter() or setOutputStream() should be called.
103     *
104     * @param output The output stream
105     */
106    public void setOutputStream(OutputStream output);
107
108    /**
109     * Get the output stream where the events will be serialized to.
110     *
111     * @return reference to the result stream, or null if only a writer was
112     * set.
113     */
114    public OutputStream getOutputStream();
115
116    /**
117     * Specifies a writer to which the document should be serialized.
118     * This method should not be called while the serializer is in
119     * the process of serializing a document.
120     * <p>
121     * The encoding specified for the output {@link Properties} must be
122     * identical to the output format used with the writer.
123     *
124     * <p>
125     * Only one of setWriter() or setOutputStream() should be called.
126     *
127     * @param writer The output writer stream
128     */
129    public void setWriter(Writer writer);
130
131    /**
132     * Get the character stream where the events will be serialized to.
133     *
134     * @return Reference to the result Writer, or null.
135     */
136    public Writer getWriter();
137
138    /**
139     * Specifies an output format for this serializer. It the
140     * serializer has already been associated with an output format,
141     * it will switch to the new format. This method should not be
142     * called while the serializer is in the process of serializing
143     * a document.
144     * <p>
145     * The standard property keys supported are: "method", "version", "encoding",
146     * "omit-xml-declaration", "standalone", doctype-public",
147     * "doctype-system", "cdata-section-elements", "indent", "media-type".
148     * These property keys and their values are described in the XSLT recommendation,
149     * see {@link <a href="http://www.w3.org/TR/1999/REC-xslt-19991116"> XSLT 1.0 recommendation</a>}
150     * <p>
151     * The non-standard property keys supported are defined in {@link OutputPropertiesFactory}.
152     *
153     * <p>
154     * This method can be called multiple times before a document is serialized. Each
155     * time it is called more, or over-riding property values, can be specified. One
156     * property value that can not be changed is that of the "method" property key.
157     * <p>
158     * The value of the "cdata-section-elements" property key is a whitespace
159     * separated list of elements. If the element is in a namespace then
160     * value is passed in this format: {uri}localName
161     * <p>
162     * If the "cdata-section-elements" key is specified on multiple calls
163     * to this method the set of elements specified in the value
164     * is not replaced from one call to the
165     * next, but it is cumulative across the calls.
166     *
167     * @param format The output format to use, as a set of key/value pairs.
168     */
169    public void setOutputFormat(Properties format);
170
171    /**
172     * Returns the output format properties for this serializer.
173     *
174     * @return The output format key/value pairs in use.
175     */
176    public Properties getOutputFormat();
177
178    /**
179     * Return a {@link ContentHandler} interface to provide SAX input to.
180     * Through the returned object the document to be serailized,
181     * as a series of SAX events, can be provided to the serialzier.
182     * If the serializer does not support the {@link ContentHandler}
183     * interface, it will return null.
184     * <p>
185     * In principle only one of asDOMSerializer() or asContentHander()
186     * should be called.
187     *
188     * @return A {@link ContentHandler} interface into this serializer,
189     *  or null if the serializer is not SAX 2 capable
190     * @throws IOException An I/O exception occured
191     */
192    public ContentHandler asContentHandler() throws IOException;
193
194    /**
195     * Return a {@link DOMSerializer} interface into this serializer.
196     * Through the returned object the document to be serialized,
197     * a DOM, can be provided to the serializer.
198     * If the serializer does not support the {@link DOMSerializer}
199     * interface, it should return null.
200     * <p>
201     * In principle only one of asDOMSerializer() or asContentHander()
202     * should be called.
203     *
204     * @return A {@link DOMSerializer} interface into this serializer,
205     *  or null if the serializer is not DOM capable
206     * @throws IOException An I/O exception occured
207     */
208    public DOMSerializer asDOMSerializer() throws IOException;
209
210    /**
211     * This method resets the serializer.
212     * If this method returns true, the
213     * serializer may be used for subsequent serialization of new
214     * documents. It is possible to change the output format and
215     * output stream prior to serializing, or to reuse the existing
216     * output format and output stream or writer.
217     *
218     * @return True if serializer has been reset and can be reused
219     */
220    public boolean reset();
221
222    /**
223     * Return an Object into this serializer to be cast to a DOM3Serializer.
224     * Through the returned object the document to be serialized,
225     * a DOM (Level 3), can be provided to the serializer.
226     * If the serializer does not support casting to a {@link DOM3Serializer}
227     * interface, it should return null.
228     * <p>
229     * In principle only one of asDOM3Serializer() or asContentHander()
230     * should be called.
231     *
232     * @return An Object to be cast to a DOM3Serializer interface into this serializer,
233     *  or null if the serializer is not DOM capable
234     * @throws IOException An I/O exception occured
235     */
236    public Object asDOM3Serializer() throws IOException;
237}
238
239