1/* 2 * Copyright (c) 2017, Oracle and/or its affiliates. All rights reserved. 3 */ 4/* 5 * Licensed to the Apache Software Foundation (ASF) under one or more 6 * contributor license agreements. See the NOTICE file distributed with 7 * this work for additional information regarding copyright ownership. 8 * The ASF licenses this file to You under the Apache License, Version 2.0 9 * (the "License"); you may not use this file except in compliance with 10 * the License. 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 22package com.sun.org.apache.xml.internal.serialize; 23 24 25import java.io.IOException; 26import java.io.OutputStream; 27import java.io.Writer; 28 29import org.xml.sax.ContentHandler; 30import org.xml.sax.DocumentHandler; 31 32 33/** 34 * Interface for a DOM serializer implementation, factory for DOM and SAX 35 * serializers, and static methods for serializing DOM documents. 36 * <p> 37 * To serialize a document using SAX events, create a compatible serializer 38 * and pass it around as a {@link 39 * org.xml.sax.DocumentHandler}. If an I/O error occurs while serializing, it will 40 * be thrown by {@link DocumentHandler#endDocument}. The SAX serializer 41 * may also be used as {@link org.xml.sax.DTDHandler}, {@link org.xml.sax.ext.DeclHandler} and 42 * {@link org.xml.sax.ext.LexicalHandler}. 43 * <p> 44 * To serialize a DOM document or DOM element, create a compatible 45 * serializer and call it's {@link 46 * DOMSerializer#serialize(Document)} or {@link DOMSerializer#serialize(Element)} methods. 47 * Both methods would produce a full XML document, to serizlie only 48 * the portion of the document use {@link OutputFormat#setOmitXMLDeclaration} 49 * and specify no document type. 50 * <p> 51 * The {@link OutputFormat} dictates what underlying serialized is used 52 * to serialize the document based on the specified method. If the output 53 * format or method are missing, the default is an XML serializer with 54 * UTF-8 encoding and now indentation. 55 * 56 * 57 * @author <a href="mailto:arkin@intalio.com">Assaf Arkin</a> 58 * @author <a href="mailto:Scott_Boag/CAM/Lotus@lotus.com">Scott Boag</a> 59 * @see DocumentHandler 60 * @see ContentHandler 61 * @see OutputFormat 62 * @see DOMSerializer 63 * 64 * @deprecated As of JDK 9, Xerces 2.9.0, Xerces DOM L3 Serializer implementation 65 * is replaced by that of Xalan. Main class 66 * {@link com.sun.org.apache.xml.internal.serialize.DOMSerializerImpl} is replaced 67 * by {@link com.sun.org.apache.xml.internal.serializer.dom3.LSSerializerImpl}. 68 */ 69@Deprecated 70public 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} 130