001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements. See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership. The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the "License");
007 * you may not use this file except in compliance with the License.
008 * You may obtain a copy of the License at
009 *
010 * http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018 /*
019 * $Id: Serializer.java 471981 2006-11-07 04:28:00Z minchau $
020 */
021 package org.apache.xml.serializer;
022 import java.io.IOException;
023 import java.io.OutputStream;
024 import java.io.Writer;
025 import java.util.Properties;
026
027 import org.xml.sax.ContentHandler;
028
029 /**
030 * The Serializer interface is implemented by a serializer to enable users to:
031 * <ul>
032 * <li>get and set streams or writers
033 * <li>configure the serializer with key/value properties
034 * <li>get an org.xml.sax.ContentHandler or a DOMSerializer to provide input to
035 * </ul>
036 *
037 * <p>
038 * Here is an example using the asContentHandler() method:
039 * <pre>
040 * java.util.Properties props =
041 * OutputPropertiesFactory.getDefaultMethodProperties(Method.TEXT);
042 * Serializer ser = SerializerFactory.getSerializer(props);
043 * java.io.PrintStream ostream = System.out;
044 * ser.setOutputStream(ostream);
045 *
046 * // Provide the SAX input events
047 * ContentHandler handler = ser.asContentHandler();
048 * handler.startDocument();
049 * char[] chars = { 'a', 'b', 'c' };
050 * handler.characters(chars, 0, chars.length);
051 * handler.endDocument();
052 *
053 * ser.reset(); // get ready to use the serializer for another document
054 * // of the same output method (TEXT).
055 * </pre>
056 *
057 * <p>
058 * As an alternate to supplying a series of SAX events as input through the
059 * ContentHandler interface, the input to serialize may be given as a DOM.
060 * <p>
061 * For example:
062 * <pre>
063 * org.w3c.dom.Document inputDoc;
064 * org.apache.xml.serializer.Serializer ser;
065 * java.io.Writer owriter;
066 *
067 * java.util.Properties props =
068 * OutputPropertiesFactory.getDefaultMethodProperties(Method.XML);
069 * Serializer ser = SerializerFactory.getSerializer(props);
070 * owriter = ...; // create a writer to serialize the document to
071 * ser.setWriter( owriter );
072 *
073 * inputDoc = ...; // create the DOM document to be serialized
074 * DOMSerializer dser = ser.asDOMSerializer(); // a DOM will be serialized
075 * dser.serialize(inputDoc); // serialize the DOM, sending output to owriter
076 *
077 * ser.reset(); // get ready to use the serializer for another document
078 * // of the same output method.
079 * </pre>
080 *
081 * This interface is a public API.
082 *
083 * @see Method
084 * @see OutputPropertiesFactory
085 * @see SerializerFactory
086 * @see DOMSerializer
087 * @see ContentHandler
088 *
089 * @xsl.usage general
090 */
091 public interface Serializer {
092
093 /**
094 * Specifies an output stream to which the document should be
095 * serialized. This method should not be called while the
096 * serializer is in the process of serializing a document.
097 * <p>
098 * The encoding specified in the output {@link Properties} is used, or
099 * 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