Serializer


1   /*
2    * Copyright 1999-2002,2004 The Apache Software Foundation.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    * 
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  
17  
18  package org.apache.xml.serialize;
19  
20  
21  import java.io.IOException  ;
22  import java.io.OutputStream  ;
23  import java.io.Writer  ;
24  
25  import org.xml.sax.ContentHandler  ;
26  import org.xml.sax.DocumentHandler  ;
27  
28  
29  /**
30   * Interface for a DOM serializer implementation, factory for DOM and SAX
31   * serializers, and static methods for serializing DOM documents.
32   * <p>
33   * To serialize a document using SAX events, create a compatible serializer
34   * and pass it around as a {@link
35   * org.xml.sax.DocumentHandler}. If an I/O error occurs while serializing, it will
36   * be thrown by {@link DocumentHandler#endDocument}. The SAX serializer
37   * may also be used as {@link org.xml.sax.DTDHandler}, {@link org.xml.sax.ext.DeclHandler} and
38   * {@link org.xml.sax.ext.LexicalHandler}.
39   * <p>
40   * To serialize a DOM document or DOM element, create a compatible
41   * serializer and call it's {@link
42   * DOMSerializer#serialize(Document)} or {@link DOMSerializer#serialize(Element)} methods.
43   * Both methods would produce a full XML document, to serizlie only
44   * the portion of the document use {@link OutputFormat#setOmitXMLDeclaration}
45   * and specify no document type.
46   * <p>
47   * The {@link OutputFormat} dictates what underlying serialized is used
48   * to serialize the document based on the specified method. If the output
49   * format or method are missing, the default is an XML serializer with
50   * UTF-8 encoding and now indentation.
51   * 
52   *
53   * @version $Revision: 1.14 $ $Date: 2004/02/24 23:34:03 $
54   * @author <a HREF="mailto:arkin@intalio.com">Assaf Arkin</a>
55   * @author <a HREF="mailto:Scott_Boag/CAM/Lotus@lotus.com">Scott Boag</a>
56   * @see DocumentHandler
57   * @see ContentHandler
58   * @see OutputFormat
59   * @see DOMSerializer
60   */
61  public interface Serializer
62  {
63  
64  
65      /**
66       * Specifies an output stream to which the document should be
67       * serialized. This method should not be called while the
68       * serializer is in the process of serializing a document.
69       */
70      public void setOutputByteStream(OutputStream   output);
71      
72  
73      /**
74       * Specifies a writer to which the document should be serialized.
75       * This method should not be called while the serializer is in
76       * the process of serializing a document.
77       */
78      public void setOutputCharStream( Writer   output );
79  
80  
81      /**
82       * Specifies an output format for this serializer. It the
83       * serializer has already been associated with an output format,
84       * it will switch to the new format. This method should not be
85       * called while the serializer is in the process of serializing
86       * a document.
87       *
88       * @param format The output format to use
89       */
90      public void setOutputFormat( OutputFormat format );
91  
92  
93      /**
94       * Return a {@link DocumentHandler} interface into this serializer.
95       * If the serializer does not support the {@link DocumentHandler}
96       * interface, it should return null.
97       */
98      public DocumentHandler   asDocumentHandler()
99          throws IOException  ;
100 
101 
102     /**
103      * Return a {@link ContentHandler} interface into this serializer.
104      * If the serializer does not support the {@link ContentHandler}
105      * interface, it should return null.
106      */
107     public ContentHandler   asContentHandler()
108         throws IOException  ;
109 
110 
111     /**
112      * Return a {@link DOMSerializer} interface into this serializer.
113      * If the serializer does not support the {@link DOMSerializer}
114      * interface, it should return null.
115      */
116     public DOMSerializer asDOMSerializer()
117         throws IOException  ;
118 
119 
120 }
121 
122 
123 
124 
125 
126
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags