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