Home | History | Annotate | Download | only in serializer 
      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 }
    146