libcore/luni/src/main/java/org/apache/xml/serializer/SerializationHandler.java

   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      */
  61     public void setContentHandler(ContentHandler ch);
  62
  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      */
  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      */
  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      */
  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      */
  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      */
 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      */
 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      */
 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      */
 143     public void setDTDEntityExpansion(boolean expand);
 144
 145 }