1 /* 2 * reserved comment block 3 * DO NOT REMOVE OR ALTER! 4 */ 5 /* 6 * Copyright 1999-2004 The Apache Software Foundation. 7 * 8 * Licensed under the Apache License, Version 2.0 (the "License"); 9 * you may not use this file except in compliance with the License. 10 * You may obtain a copy of the License at 11 * 12 * http://www.apache.org/licenses/LICENSE-2.0 13 * 14 * Unless required by applicable law or agreed to in writing, software 15 * distributed under the License is distributed on an "AS IS" BASIS, 16 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 17 * See the License for the specific language governing permissions and 18 * limitations under the License. 19 */ 20 /* 21 * $Id: Serializer.java,v 1.2.4.1 2005/09/15 08:15:22 suresh_emailid Exp $ 22 */ 23 package com.sun.org.apache.xml.internal.serializer; 24 import java.io.IOException; 25 import java.io.OutputStream; 26 import java.io.Writer; 27 import java.util.Properties; 28 29 import org.xml.sax.ContentHandler; 30 31 /** 32 * The Serializer interface is implemented by a serializer to enable users to: 33 * <ul> 34 * <li>get and set streams or writers 35 * <li>configure the serializer with key/value properties 36 * <li>get an org.xml.sax.ContentHandler or a DOMSerializer to provide input to 37 * </ul> 38 * 39 * <p> 40 * Here is an example using the asContentHandler() method: 41 * <pre> 42 * java.util.Properties props = 43 * OutputPropertiesFactory.getDefaultMethodProperties(Method.TEXT); 44 * Serializer ser = SerializerFactory.getSerializer(props); 45 * java.io.PrintStream ostream = System.out; 46 * ser.setOutputStream(ostream); 47 * 48 * // Provide the SAX input events 49 * ContentHandler handler = ser.asContentHandler(); 50 * handler.startDocument(); 51 * char[] chars = { 'a', 'b', 'c' }; 52 * handler.characters(chars, 0, chars.length); 53 * handler.endDocument(); 54 * 55 * ser.reset(); // get ready to use the serializer for another document 56 * // of the same output method (TEXT). 57 * </pre> 58 * 59 * <p> 60 * As an alternate to supplying a series of SAX events as input through the 61 * ContentHandler interface, the input to serialize may be given as a DOM. 62 * <p> 63 * For example: 64 * <pre> 65 * org.w3c.dom.Document inputDoc; 66 * com.sun.org.apache.xml.internal.serializer.Serializer ser; 67 * java.io.Writer owriter; 68 * 69 * java.util.Properties props = 70 * OutputPropertiesFactory.getDefaultMethodProperties(Method.XML); 71 * Serializer ser = SerializerFactory.getSerializer(props); 72 * owriter = ...; // create a writer to serialize the document to 73 * ser.setWriter( owriter ); 74 * 75 * inputDoc = ...; // create the DOM document to be serialized 76 * DOMSerializer dser = ser.asDOMSerializer(); // a DOM will be serialized 77 * dser.serialize(inputDoc); // serialize the DOM, sending output to owriter 78 * 79 * ser.reset(); // get ready to use the serializer for another document 80 * // of the same output method. 81 * </pre> 82 * 83 * This interface is a public API. 84 * 85 * @see Method 86 * @see OutputPropertiesFactory 87 * @see SerializerFactory 88 * @see DOMSerializer 89 * @see ContentHandler 90 * 91 * @xsl.usage general 92 */ 93 public interface Serializer { 94 95 /** 96 * Specifies an output stream to which the document should be 97 * serialized. This method should not be called while the 98 * serializer is in the process of serializing a document. 99 * <p> 100 * The encoding specified in the output {@link Properties} is used, or 101 * if no encoding was specified, the default for the selected 102 * output method. 103 * <p> 104 * Only one of setWriter() or setOutputStream() should be called. 105 * 106 * @param output The output stream 107 */ setOutputStream(OutputStream output)108 public void setOutputStream(OutputStream output); 109 110 /** 111 * Get the output stream where the events will be serialized to. 112 * 113 * @return reference to the result stream, or null if only a writer was 114 * set. 115 */ getOutputStream()116 public OutputStream getOutputStream(); 117 118 /** 119 * Specifies a writer to which the document should be serialized. 120 * This method should not be called while the serializer is in 121 * the process of serializing a document. 122 * <p> 123 * The encoding specified for the output {@link Properties} must be 124 * identical to the output format used with the writer. 125 * 126 * <p> 127 * Only one of setWriter() or setOutputStream() should be called. 128 * 129 * @param writer The output writer stream 130 */ setWriter(Writer writer)131 public void setWriter(Writer writer); 132 133 /** 134 * Get the character stream where the events will be serialized to. 135 * 136 * @return Reference to the result Writer, or null. 137 */ getWriter()138 public Writer getWriter(); 139 140 /** 141 * Specifies an output format for this serializer. It the 142 * serializer has already been associated with an output format, 143 * it will switch to the new format. This method should not be 144 * called while the serializer is in the process of serializing 145 * a document. 146 * <p> 147 * The standard property keys supported are: "method", "version", "encoding", 148 * "omit-xml-declaration", "standalone", doctype-public", 149 * "doctype-system", "cdata-section-elements", "indent", "media-type". 150 * These property keys and their values are described in the XSLT recommendation, 151 * see {@link <a href="http://www.w3.org/TR/1999/REC-xslt-19991116"> XSLT 1.0 recommendation</a>} 152 * <p> 153 * The non-standard property keys supported are defined in {@link OutputPropertiesFactory}. 154 * 155 * <p> 156 * This method can be called multiple times before a document is serialized. Each 157 * time it is called more, or over-riding property values, can be specified. One 158 * property value that can not be changed is that of the "method" property key. 159 * <p> 160 * The value of the "cdata-section-elements" property key is a whitespace 161 * separated list of elements. If the element is in a namespace then 162 * value is passed in this format: {uri}localName 163 * <p> 164 * If the "cdata-section-elements" key is specified on multiple calls 165 * to this method the set of elements specified in the value 166 * is not replaced from one call to the 167 * next, but it is cumulative across the calls. 168 * 169 * @param format The output format to use, as a set of key/value pairs. 170 */ setOutputFormat(Properties format)171 public void setOutputFormat(Properties format); 172 173 /** 174 * Returns the output format properties for this serializer. 175 * 176 * @return The output format key/value pairs in use. 177 */ getOutputFormat()178 public Properties getOutputFormat(); 179 180 /** 181 * Return a {@link ContentHandler} interface to provide SAX input to. 182 * Through the returned object the document to be serailized, 183 * as a series of SAX events, can be provided to the serialzier. 184 * If the serializer does not support the {@link ContentHandler} 185 * interface, it will return null. 186 * <p> 187 * In principle only one of asDOMSerializer() or asContentHander() 188 * should be called. 189 * 190 * @return A {@link ContentHandler} interface into this serializer, 191 * or null if the serializer is not SAX 2 capable 192 * @throws IOException An I/O exception occured 193 */ asContentHandler()194 public ContentHandler asContentHandler() throws IOException; 195 196 /** 197 * Return a {@link DOMSerializer} interface into this serializer. 198 * Through the returned object the document to be serialized, 199 * a DOM, can be provided to the serializer. 200 * If the serializer does not support the {@link DOMSerializer} 201 * interface, it should return null. 202 * <p> 203 * In principle only one of asDOMSerializer() or asContentHander() 204 * should be called. 205 * 206 * @return A {@link DOMSerializer} interface into this serializer, 207 * or null if the serializer is not DOM capable 208 * @throws IOException An I/O exception occured 209 */ asDOMSerializer()210 public DOMSerializer asDOMSerializer() throws IOException; 211 212 /** 213 * This method resets the serializer. 214 * If this method returns true, the 215 * serializer may be used for subsequent serialization of new 216 * documents. It is possible to change the output format and 217 * output stream prior to serializing, or to reuse the existing 218 * output format and output stream or writer. 219 * 220 * @return True if serializer has been reset and can be reused 221 */ reset()222 public boolean reset(); 223 } 224