1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18
19 package org.apache.xml.serialize;
20
21
22 import java.io.IOException;
23 import java.io.OutputStream;
24 import java.io.Writer;
25
26 import org.xml.sax.ContentHandler;
27 import org.xml.sax.DocumentHandler;
28
29
30 /**
31 * Interface for a DOM serializer implementation, factory for DOM and SAX
32 * serializers, and static methods for serializing DOM documents.
33 * <p>
34 * To serialize a document using SAX events, create a compatible serializer
35 * and pass it around as a {@link
36 * org.xml.sax.DocumentHandler}. If an I/O error occurs while serializing, it will
37 * be thrown by {@link DocumentHandler#endDocument}. The SAX serializer
38 * may also be used as {@link org.xml.sax.DTDHandler}, {@link org.xml.sax.ext.DeclHandler} and
39 * {@link org.xml.sax.ext.LexicalHandler}.
40 * <p>
41 * To serialize a DOM document or DOM element, create a compatible
42 * serializer and call it's {@link
43 * DOMSerializer#serialize(Document)} or {@link DOMSerializer#serialize(Element)} methods.
44 * Both methods would produce a full XML document, to serizlie only
45 * the portion of the document use {@link OutputFormat#setOmitXMLDeclaration}
46 * and specify no document type.
47 * <p>
48 * The {@link OutputFormat} dictates what underlying serialized is used
49 * to serialize the document based on the specified method. If the output
50 * format or method are missing, the default is an XML serializer with
51 * UTF-8 encoding and now indentation.
52 *
53 * @deprecated This class was deprecated in Xerces 2.9.0. It is recommended
54 * that new applications use the DOM Level 3 LSSerializer or JAXP's Transformation
55 * API for XML (TrAX) for serializing XML and HTML. See the Xerces documentation for more
56 * information.
57 * @version $Revision: 476047 $ $Date: 2006-11-16 23:27:45 -0500 (Thu, 16 Nov 2006) $
58 * @author <a href="mailto:arkin@intalio.com">Assaf Arkin</a>
59 * @author <a href="mailto:Scott_Boag/CAM/Lotus@lotus.com">Scott Boag</a>
60 * @see DocumentHandler
61 * @see ContentHandler
62 * @see OutputFormat
63 * @see DOMSerializer
64 */
65 public interface Serializer
66 {
67
68
69 /**
70 * Specifies an output stream to which the document should be
71 * serialized. This method should not be called while the
72 * serializer is in the process of serializing a document.
73 */
74 public void setOutputByteStream(OutputStream output);
75
76
77 /**
78 * Specifies a writer to which the document should be serialized.
79 * This method should not be called while the serializer is in
80 * the process of serializing a document.
81 */
82 public void setOutputCharStream( Writer output );
83
84
85 /**
86 * Specifies an output format for this serializer. It the
87 * serializer has already been associated with an output format,
88 * it will switch to the new format. This method should not be
89 * called while the serializer is in the process of serializing
90 * a document.
91 *
92 * @param format The output format to use
93 */
94 public void setOutputFormat( OutputFormat format );
95
96
97 /**
98 * Return a {@link DocumentHandler} interface into this serializer.
99 * If the serializer does not support the {@link DocumentHandler}
100 * interface, it should return null.
101 */
102 public DocumentHandler asDocumentHandler()
103 throws IOException;
104
105
106 /**
107 * Return a {@link ContentHandler} interface into this serializer.
108 * If the serializer does not support the {@link ContentHandler}
109 * interface, it should return null.
110 */
111 public ContentHandler asContentHandler()
112 throws IOException;
113
114
115 /**
116 * Return a {@link DOMSerializer} interface into this serializer.
117 * If the serializer does not support the {@link DOMSerializer}
118 * interface, it should return null.
119 */
120 public DOMSerializer asDOMSerializer()
121 throws IOException;
122
123
124 }
125
126
127
128
129
Save This Page