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