19f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson/* 29f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * Licensed to the Apache Software Foundation (ASF) under one 39f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * or more contributor license agreements. See the NOTICE file 49f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * distributed with this work for additional information 59f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * regarding copyright ownership. The ASF licenses this file 69f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * to you under the Apache License, Version 2.0 (the "License"); 79f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * you may not use this file except in compliance with the License. 89f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * You may obtain a copy of the License at 99f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * 109f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * http://www.apache.org/licenses/LICENSE-2.0 119f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * 129f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * Unless required by applicable law or agreed to in writing, software 139f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * distributed under the License is distributed on an "AS IS" BASIS, 149f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 159f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * See the License for the specific language governing permissions and 169f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * limitations under the License. 179f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson */ 189f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson/* 199f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * $Id: Serializer.java 471981 2006-11-07 04:28:00Z minchau $ 209f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson */ 219f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilsonpackage org.apache.xml.serializer; 229f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilsonimport java.io.IOException; 239f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilsonimport java.io.OutputStream; 249f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilsonimport java.io.Writer; 259f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilsonimport java.util.Properties; 269f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 279f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilsonimport org.xml.sax.ContentHandler; 289f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 299f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson/** 309f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * The Serializer interface is implemented by a serializer to enable users to: 319f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * <ul> 329f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * <li>get and set streams or writers 339f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * <li>configure the serializer with key/value properties 349f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * <li>get an org.xml.sax.ContentHandler or a DOMSerializer to provide input to 359f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * </ul> 369f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * 379f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * <p> 389f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * Here is an example using the asContentHandler() method: 399f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * <pre> 409f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * java.util.Properties props = 419f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * OutputPropertiesFactory.getDefaultMethodProperties(Method.TEXT); 429f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * Serializer ser = SerializerFactory.getSerializer(props); 439f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * java.io.PrintStream ostream = System.out; 449f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * ser.setOutputStream(ostream); 459f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * 469f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * // Provide the SAX input events 479f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * ContentHandler handler = ser.asContentHandler(); 489f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * handler.startDocument(); 499f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * char[] chars = { 'a', 'b', 'c' }; 509f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * handler.characters(chars, 0, chars.length); 519f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * handler.endDocument(); 529f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * 539f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * ser.reset(); // get ready to use the serializer for another document 549f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * // of the same output method (TEXT). 559f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * </pre> 569f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * 579f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * <p> 589f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * As an alternate to supplying a series of SAX events as input through the 599f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * ContentHandler interface, the input to serialize may be given as a DOM. 609f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * <p> 619f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * For example: 629f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * <pre> 639f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * org.w3c.dom.Document inputDoc; 649f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * org.apache.xml.serializer.Serializer ser; 659f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * java.io.Writer owriter; 669f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * 679f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * java.util.Properties props = 689f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * OutputPropertiesFactory.getDefaultMethodProperties(Method.XML); 699f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * Serializer ser = SerializerFactory.getSerializer(props); 709f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * owriter = ...; // create a writer to serialize the document to 719f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * ser.setWriter( owriter ); 729f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * 739f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * inputDoc = ...; // create the DOM document to be serialized 749f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * DOMSerializer dser = ser.asDOMSerializer(); // a DOM will be serialized 759f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * dser.serialize(inputDoc); // serialize the DOM, sending output to owriter 769f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * 779f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * ser.reset(); // get ready to use the serializer for another document 789f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * // of the same output method. 799f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * </pre> 809f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * 819f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * This interface is a public API. 829f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * 839f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * @see Method 849f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * @see OutputPropertiesFactory 859f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * @see SerializerFactory 869f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * @see DOMSerializer 879f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * @see ContentHandler 889f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * 899f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * @xsl.usage general 909f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson */ 919f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilsonpublic interface Serializer { 929f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 939f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson /** 949f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * Specifies an output stream to which the document should be 959f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * serialized. This method should not be called while the 969f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * serializer is in the process of serializing a document. 979f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * <p> 989f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * The encoding specified in the output {@link Properties} is used, or 999f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * if no encoding was specified, the default for the selected 1009f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * output method. 1019f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * <p> 1029f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * Only one of setWriter() or setOutputStream() should be called. 1039f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * 1049f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * @param output The output stream 1059f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson */ 1069f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson public void setOutputStream(OutputStream output); 1079f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 1089f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson /** 1099f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * Get the output stream where the events will be serialized to. 1109f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * 1119f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * @return reference to the result stream, or null if only a writer was 1129f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * set. 1139f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson */ 1149f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson public OutputStream getOutputStream(); 1159f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 1169f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson /** 1179f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * Specifies a writer to which the document should be serialized. 1189f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * This method should not be called while the serializer is in 1199f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * the process of serializing a document. 1209f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * <p> 1219f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * The encoding specified for the output {@link Properties} must be 1229f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * identical to the output format used with the writer. 1239f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * 1249f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * <p> 1259f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * Only one of setWriter() or setOutputStream() should be called. 1269f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * 1279f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * @param writer The output writer stream 1289f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson */ 1299f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson public void setWriter(Writer writer); 1309f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 1319f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson /** 1329f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * Get the character stream where the events will be serialized to. 1339f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * 1349f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * @return Reference to the result Writer, or null. 1359f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson */ 1369f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson public Writer getWriter(); 1379f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 1389f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson /** 1399f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * Specifies an output format for this serializer. It the 1409f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * serializer has already been associated with an output format, 1419f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * it will switch to the new format. This method should not be 1429f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * called while the serializer is in the process of serializing 1439f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * a document. 1449f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * <p> 1459f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * The standard property keys supported are: "method", "version", "encoding", 1469f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * "omit-xml-declaration", "standalone", doctype-public", 1479f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * "doctype-system", "cdata-section-elements", "indent", "media-type". 1489f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * These property keys and their values are described in the XSLT recommendation, 1499f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * see {@link <a href="http://www.w3.org/TR/1999/REC-xslt-19991116"> XSLT 1.0 recommendation</a>} 1509f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * <p> 1519f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * The non-standard property keys supported are defined in {@link OutputPropertiesFactory}. 1529f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * 1539f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * <p> 1549f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * This method can be called multiple times before a document is serialized. Each 1559f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * time it is called more, or over-riding property values, can be specified. One 1569f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * property value that can not be changed is that of the "method" property key. 1579f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * <p> 1589f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * The value of the "cdata-section-elements" property key is a whitespace 1599f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * separated list of elements. If the element is in a namespace then 1609f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * value is passed in this format: {uri}localName 1619f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * <p> 1629f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * If the "cdata-section-elements" key is specified on multiple calls 1639f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * to this method the set of elements specified in the value 1649f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * is not replaced from one call to the 1659f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * next, but it is cumulative across the calls. 1669f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * 1679f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * @param format The output format to use, as a set of key/value pairs. 1689f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson */ 1699f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson public void setOutputFormat(Properties format); 1709f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 1719f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson /** 1729f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * Returns the output format properties for this serializer. 1739f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * 1749f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * @return The output format key/value pairs in use. 1759f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson */ 1769f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson public Properties getOutputFormat(); 1779f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 1789f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson /** 1799f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * Return a {@link ContentHandler} interface to provide SAX input to. 1809f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * Through the returned object the document to be serailized, 1819f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * as a series of SAX events, can be provided to the serialzier. 1829f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * If the serializer does not support the {@link ContentHandler} 1839f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * interface, it will return null. 1849f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * <p> 1859f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * In principle only one of asDOMSerializer() or asContentHander() 1869f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * should be called. 1879f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * 1889f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * @return A {@link ContentHandler} interface into this serializer, 1899f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * or null if the serializer is not SAX 2 capable 1909f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * @throws IOException An I/O exception occured 1919f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson */ 1929f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson public ContentHandler asContentHandler() throws IOException; 1939f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 1949f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson /** 1959f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * Return a {@link DOMSerializer} interface into this serializer. 1969f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * Through the returned object the document to be serialized, 1979f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * a DOM, can be provided to the serializer. 1989f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * If the serializer does not support the {@link DOMSerializer} 1999f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * interface, it should return null. 2009f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * <p> 2019f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * In principle only one of asDOMSerializer() or asContentHander() 2029f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * should be called. 2039f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * 2049f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * @return A {@link DOMSerializer} interface into this serializer, 2059f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * or null if the serializer is not DOM capable 2069f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * @throws IOException An I/O exception occured 2079f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson */ 2089f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson public DOMSerializer asDOMSerializer() throws IOException; 2099f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 2109f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson /** 2119f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * This method resets the serializer. 2129f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * If this method returns true, the 2139f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * serializer may be used for subsequent serialization of new 2149f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * documents. It is possible to change the output format and 2159f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * output stream prior to serializing, or to reuse the existing 2169f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * output format and output stream or writer. 2179f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * 2189f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * @return True if serializer has been reset and can be reused 2199f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson */ 2209f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson public boolean reset(); 2219f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 2229f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson /** 2239f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * Return an Object into this serializer to be cast to a DOM3Serializer. 2249f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * Through the returned object the document to be serialized, 2259f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * a DOM (Level 3), can be provided to the serializer. 2269f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * If the serializer does not support casting to a {@link DOM3Serializer} 2279f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * interface, it should return null. 2289f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * <p> 2299f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * In principle only one of asDOM3Serializer() or asContentHander() 2309f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * should be called. 2319f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * 2329f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * @return An Object to be cast to a DOM3Serializer interface into this serializer, 2339f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * or null if the serializer is not DOM capable 2349f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * @throws IOException An I/O exception occured 2359f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson */ 2369f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson public Object asDOM3Serializer() throws IOException; 2379f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson} 2389f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 239