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