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: SerializationHandler.java 471981 2006-11-07 04:28:00Z minchau $
20  */
21 package org.apache.xml.serializer;
22 
23 import java.io.IOException;
24 
25 import javax.xml.transform.Transformer;
26 
27 import org.w3c.dom.Node;
28 import org.xml.sax.ContentHandler;
29 import org.xml.sax.ErrorHandler;
30 import org.xml.sax.SAXException;
31 import org.xml.sax.ext.DeclHandler;
32 
33 /**
34  * This interface is the one that a serializer implements. It is a group of
35  * other interfaces, such as ExtendedContentHandler, ExtendedLexicalHandler etc.
36  * In addition there are other methods, such as reset().
37  *
38  * This class is public only because it is used in another package,
39  * it is not a public API.
40  *
41  * @xsl.usage internal
42  */
43 public interface SerializationHandler
44     extends
45         ExtendedContentHandler,
46         ExtendedLexicalHandler,
47         XSLOutputAttributes,
48         DeclHandler,
49         org.xml.sax.DTDHandler,
50         ErrorHandler,
51         DOMSerializer,
52         Serializer
53 {
54     /**
55      * Set the SAX Content handler that the serializer sends its output to. This
56      * method only applies to a ToSAXHandler, not to a ToStream serializer.
57      *
58      * @see Serializer#asContentHandler()
59      * @see ToSAXHandler
60      */
setContentHandler(ContentHandler ch)61     public void setContentHandler(ContentHandler ch);
62 
close()63     public void close();
64 
65     /**
66      * Notify that the serializer should take this DOM node as input to be
67      * serialized.
68      *
69      * @param node the DOM node to be serialized.
70      * @throws IOException
71      */
serialize(Node node)72     public void serialize(Node node) throws IOException;
73     /**
74      * Turns special character escaping on/off.
75      *
76      * Note that characters will
77      * never, even if this option is set to 'true', be escaped within
78      * CDATA sections in output XML documents.
79      *
80      * @param escape true if escaping is to be set on.
81      */
setEscaping(boolean escape)82     public boolean setEscaping(boolean escape) throws SAXException;
83 
84     /**
85      * Set the number of spaces to indent for each indentation level.
86      * @param spaces the number of spaces to indent for each indentation level.
87      */
setIndentAmount(int spaces)88     public void setIndentAmount(int spaces);
89 
90     /**
91      * Set the transformer associated with the serializer.
92      * @param transformer the transformer associated with the serializer.
93      */
setTransformer(Transformer transformer)94     public void setTransformer(Transformer transformer);
95 
96     /**
97      * Get the transformer associated with the serializer.
98      * @return Transformer the transformer associated with the serializer.
99      */
getTransformer()100     public Transformer getTransformer();
101 
102     /**
103      * Used only by TransformerSnapshotImpl to restore the serialization
104      * to a previous state.
105      *
106      * @param mappings NamespaceMappings
107      */
setNamespaceMappings(NamespaceMappings mappings)108     public void setNamespaceMappings(NamespaceMappings mappings);
109 
110     /**
111      * A SerializationHandler accepts SAX-like events, so
112      * it can accumulate attributes or namespace nodes after
113      * a startElement().
114      * <p>
115      * If the SerializationHandler has a Writer or OutputStream,
116      * a call to this method will flush such accumulated
117      * events as a closed start tag for an element.
118      * <p>
119      * If the SerializationHandler wraps a ContentHandler,
120      * a call to this method will flush such accumulated
121      * events as a SAX (not SAX-like) calls to
122      * startPrefixMapping() and startElement().
123      * <p>
124      * If one calls endDocument() then one need not call
125      * this method since a call to endDocument() will
126      * do what this method does. However, in some
127      * circumstances, such as with document fragments,
128      * endDocument() is not called and it may be
129      * necessary to call this method to flush
130      * any pending events.
131      * <p>
132      * For performance reasons this method should not be called
133      * very often.
134      */
flushPending()135     public void flushPending() throws SAXException;
136 
137     /**
138      * Default behavior is to expand DTD entities,
139      * that is the initall default value is true.
140      * @param expand true if DTD entities are to be expanded,
141      * false if they are to be left as DTD entity references.
142      */
setDTDEntityExpansion(boolean expand)143     public void setDTDEntityExpansion(boolean expand);
144 
145 }
146