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