001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements. See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership. The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the "License");
007 * you may not use this file except in compliance with the License.
008 * You may obtain a copy of the License at
009 *
010 * http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018 /*
019 * $Id: DOM3Serializer.java 1225426 2011-12-29 04:13:08Z mrglavas $
020 */
021
022 package org.apache.xml.serializer;
023
024 import java.io.IOException;
025
026 import org.w3c.dom.DOMErrorHandler;
027 import org.w3c.dom.Node;
028 import org.w3c.dom.ls.LSSerializerFilter;
029
030 /**
031 * This interface is not intended to be used
032 * by an end user, but rather by an XML parser that is implementing the DOM
033 * Level 3 Load and Save APIs.
034 * <p>
035 *
036 * See the DOM Level 3 Load and Save interface at <a href="http://www.w3.org/TR/2004/REC-DOM-Level-3-LS-20040407/load-save.html#LS-LSSerializer">LSSeializer</a>.
037 *
038 * For a list of configuration parameters for DOM Level 3 see <a href="http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407/core.html#DOMConfiguration">DOMConfiguration</a>.
039 * For additional configuration parameters available with the DOM Level 3 Load and Save API LSSerializer see
040 * <a href="http://www.w3.org/TR/2004/REC-DOM-Level-3-LS-20040407/load-save.html#LS-LSSerializer-config">LSerializer config</a>.
041 * <p>
042 * The following example uses a DOM3Serializer indirectly, through an an XML
043 * parser that uses this class as part of its implementation of the DOM Level 3
044 * Load and Save APIs, and is the prefered way to serialize with DOM Level 3 APIs.
045 * <p>
046 * Example:
047 * <pre>
048 * public class TestDOM3 {
049 *
050 * public static void main(String args[]) throws Exception {
051 * // Get document to serialize
052 * TestDOM3 test = new TestDOM3();
053 *
054 * // Serialize using standard DOM Level 3 Load/Save APIs
055 * System.out.println(test.testDOM3LS());
056 * }
057 *
058 * public org.w3c.dom.Document getDocument() throws Exception {
059 * // Create a simple DOM Document.
060 * javax.xml.parsers.DocumentBuilderFactory factory =
061 * javax.xml.parsers.DocumentBuilderFactory.newInstance();
062 * javax.xml.parsers.DocumentBuilder builder = factory.newDocumentBuilder();
063 * byte[] bytes = "<parent><child/></parent>".getBytes();
064 * java.io.InputStream is = new java.io.ByteArrayInputStream(bytes);
065 * org.w3c.dom.Document doc = builder.parse(is);
066 * return doc;
067 * }
068 *
069 * //
070 * // This method uses standard DOM Level 3 Load Save APIs:
071 * // org.w3c.dom.bootstrap.DOMImplementationRegistry
072 * // org.w3c.dom.ls.DOMImplementationLS
073 * // org.w3c.dom.ls.DOMImplementationLS
074 * // org.w3c.dom.ls.LSSerializer
075 * // org.w3c.dom.DOMConfiguration
076 * //
077 * // The only thing non-standard in this method is the value set for the
078 * // name of the class implementing the DOM Level 3 Load Save APIs,
079 * // which in this case is:
080 * // org.apache.xerces.dom.DOMImplementationSourceImpl
081 * //
082 *
083 * public String testDOM3LS() throws Exception {
084 *
085 * // Get a simple DOM Document that will be serialized.
086 * org.w3c.dom.Document docToSerialize = getDocument();
087 *
088 * // Get a factory (DOMImplementationLS) for creating a Load and Save object.
089 * org.w3c.dom.ls.DOMImplementationLS impl =
090 * (org.w3c.dom.ls.DOMImplementationLS)
091 * org.w3c.dom.bootstrap.DOMImplementationRegistry.newInstance().getDOMImplementation("LS");
092 *
093 * // Use the factory to create an object (LSSerializer) used to
094 * // write out or save the document.
095 * org.w3c.dom.ls.LSSerializer writer = impl.createLSSerializer();
096 * org.w3c.dom.DOMConfiguration config = writer.getDomConfig();
097 * config.setParameter("format-pretty-print", Boolean.TRUE);
098 *
099 * // Use the LSSerializer to write out or serialize the document to a String.
100 * String serializedXML = writer.writeToString(docToSerialize);
101 * return serializedXML;
102 * }
103 *
104 * } // end of class TestDOM3
105 * </pre>
106 *
107 * @see <a href="http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407/core.html#DOMConfiguration">DOMConfiguration</a>
108 * @see <a href="http://www.w3.org/TR/2004/REC-DOM-Level-3-LS-20040407/load-save.html#LS-LSSerializer-config">LSSerializer</a>
109 * @see org.apache.xml.serializer.Serializer
110 * @see org.apache.xml.serializer.DOMSerializer
111 *
112 * @xsl.usage advanced
113 *
114 */
115 public interface DOM3Serializer {
116 /**
117 * Serializes the Level 3 DOM node. Throws an exception only if an I/O
118 * exception occured while serializing.
119 *
120 * This interface is a public API.
121 *
122 * @param node the Level 3 DOM node to serialize
123 * @throws IOException if an I/O exception occured while serializing
124 */
125 public void serializeDOM3(Node node) throws IOException;
126
127 /**
128 * Sets a DOMErrorHandler on the DOM Level 3 Serializer.
129 *
130 * This interface is a public API.
131 *
132 * @param handler the Level 3 DOMErrorHandler
133 */
134 public void setErrorHandler(DOMErrorHandler handler);
135
136 /**
137 * Returns a DOMErrorHandler set on the DOM Level 3 Serializer.
138 *
139 * This interface is a public API.
140 *
141 * @return A Level 3 DOMErrorHandler
142 */
143 public DOMErrorHandler getErrorHandler();
144
145 /**
146 * Sets a LSSerializerFilter on the DOM Level 3 Serializer to filter nodes
147 * during serialization.
148 *
149 * This interface is a public API.
150 *
151 * @param filter the Level 3 LSSerializerFilter
152 */
153 public void setNodeFilter(LSSerializerFilter filter);
154
155 /**
156 * Returns a LSSerializerFilter set on the DOM Level 3 Serializer to filter nodes
157 * during serialization.
158 *
159 * This interface is a public API.
160 *
161 * @return The Level 3 LSSerializerFilter
162 */
163 public LSSerializerFilter getNodeFilter();
164
165 /**
166 * Sets the end-of-line sequence of characters to be used during serialization
167 * @param newLine The end-of-line sequence of characters to be used during serialization
168 */
169 public void setNewLine(char[] newLine);
170 }