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