001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017:
018: package org.apache.xml.serialize;
019:
020: import java.io.IOException;
021: import java.io.OutputStream;
022: import java.io.Writer;
023:
024: import org.xml.sax.ContentHandler;
025: import org.xml.sax.DocumentHandler;
026:
027: /**
028: * Interface for a DOM serializer implementation, factory for DOM and SAX
029: * serializers, and static methods for serializing DOM documents.
030: * <p>
031: * To serialize a document using SAX events, create a compatible serializer
032: * and pass it around as a {@link
033: * org.xml.sax.DocumentHandler}. If an I/O error occurs while serializing, it will
034: * be thrown by {@link DocumentHandler#endDocument}. The SAX serializer
035: * may also be used as {@link org.xml.sax.DTDHandler}, {@link org.xml.sax.ext.DeclHandler} and
036: * {@link org.xml.sax.ext.LexicalHandler}.
037: * <p>
038: * To serialize a DOM document or DOM element, create a compatible
039: * serializer and call it's {@link
040: * DOMSerializer#serialize(Document)} or {@link DOMSerializer#serialize(Element)} methods.
041: * Both methods would produce a full XML document, to serizlie only
042: * the portion of the document use {@link OutputFormat#setOmitXMLDeclaration}
043: * and specify no document type.
044: * <p>
045: * The {@link OutputFormat} dictates what underlying serialized is used
046: * to serialize the document based on the specified method. If the output
047: * format or method are missing, the default is an XML serializer with
048: * UTF-8 encoding and now indentation.
049: *
050: * @deprecated This class was deprecated in Xerces 2.9.0. It is recommended
051: * that new applications use the DOM Level 3 LSSerializer or JAXP's Transformation
052: * API for XML (TrAX) for serializing XML and HTML. See the Xerces documentation for more
053: * information.
054: * @version $Revision: 476047 $ $Date: 2006-11-16 23:27:45 -0500 (Thu, 16 Nov 2006) $
055: * @author <a href="mailto:arkin@intalio.com">Assaf Arkin</a>
056: * @author <a href="mailto:Scott_Boag/CAM/Lotus@lotus.com">Scott Boag</a>
057: * @see DocumentHandler
058: * @see ContentHandler
059: * @see OutputFormat
060: * @see DOMSerializer
061: */
062: public interface Serializer {
063:
064: /**
065: * Specifies an output stream to which the document should be
066: * serialized. This method should not be called while the
067: * serializer is in the process of serializing a document.
068: */
069: public void setOutputByteStream(OutputStream output);
070:
071: /**
072: * Specifies a writer to which the document should be serialized.
073: * This method should not be called while the serializer is in
074: * the process of serializing a document.
075: */
076: public void setOutputCharStream(Writer output);
077:
078: /**
079: * Specifies an output format for this serializer. It the
080: * serializer has already been associated with an output format,
081: * it will switch to the new format. This method should not be
082: * called while the serializer is in the process of serializing
083: * a document.
084: *
085: * @param format The output format to use
086: */
087: public void setOutputFormat(OutputFormat format);
088:
089: /**
090: * Return a {@link DocumentHandler} interface into this serializer.
091: * If the serializer does not support the {@link DocumentHandler}
092: * interface, it should return null.
093: */
094: public DocumentHandler asDocumentHandler() throws IOException;
095:
096: /**
097: * Return a {@link ContentHandler} interface into this serializer.
098: * If the serializer does not support the {@link ContentHandler}
099: * interface, it should return null.
100: */
101: public ContentHandler asContentHandler() throws IOException;
102:
103: /**
104: * Return a {@link DOMSerializer} interface into this serializer.
105: * If the serializer does not support the {@link DOMSerializer}
106: * interface, it should return null.
107: */
108: public DOMSerializer asDOMSerializer() throws IOException;
109:
110: }
|