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