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$
20 */
21
22package org.apache.xml.serializer;
23
24import java.io.IOException;
25
26import org.w3c.dom.DOMErrorHandler;
27import org.w3c.dom.Node;
28import org.w3c.dom.ls.LSSerializerFilter;
29
30/**
31 * This interface is not intended to be used
32 * by an end user, but rather by an XML parser that is implementing the DOM
33 * Level 3 Load and Save APIs.
34 * <p>
35 *
36 * 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>.
37 *
38 * 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>.
39 * For additional configuration parameters available with the DOM Level 3 Load and Save API LSSerializer see
40 * <a href="http://www.w3.org/TR/2004/REC-DOM-Level-3-LS-20040407/load-save.html#LS-LSSerializer-config">LSerializer config</a>.
41 * <p>
42 * The following example uses a DOM3Serializer indirectly, through an an XML
43 * parser that uses this class as part of its implementation of the DOM Level 3
44 * Load and Save APIs, and is the prefered way to serialize with DOM Level 3 APIs.
45 * <p>
46 * Example:
47 * <pre>
48 *    public class TestDOM3 {
49 *
50 *    public static void main(String args[]) throws Exception {
51 *        // Get document to serialize
52 *        TestDOM3 test = new TestDOM3();
53 *
54 *        // Serialize using standard DOM Level 3 Load/Save APIs
55 *        System.out.println(test.testDOM3LS());
56 *    }
57 *
58 *    public org.w3c.dom.Document getDocument() throws Exception {
59 *        // Create a simple DOM Document.
60 *        javax.xml.parsers.DocumentBuilderFactory factory =
61 *            javax.xml.parsers.DocumentBuilderFactory.newInstance();
62 *        javax.xml.parsers.DocumentBuilder builder = factory.newDocumentBuilder();
63 *        byte[] bytes = "<parent><child/></parent>".getBytes();
64 *        java.io.InputStream is = new java.io.ByteArrayInputStream(bytes);
65 *        org.w3c.dom.Document doc = builder.parse(is);
66 *        return doc;
67 *    }
68 *
69 *    //
70 *    // This method uses standard DOM Level 3 Load Save APIs:
71 *    //   org.w3c.dom.bootstrap.DOMImplementationRegistry
72 *    //   org.w3c.dom.ls.DOMImplementationLS
73 *    //   org.w3c.dom.ls.DOMImplementationLS
74 *    //   org.w3c.dom.ls.LSSerializer
75 *    //   org.w3c.dom.DOMConfiguration
76 *    //
77 *    // The only thing non-standard in this method is the value set for the
78 *    // name of the class implementing the DOM Level 3 Load Save APIs,
79 *    // which in this case is:
80 *    //   org.apache.xerces.dom.DOMImplementationSourceImpl
81 *    //
82 *
83 *    public String testDOM3LS() throws Exception {
84 *
85 *        // Get a simple DOM Document that will be serialized.
86 *        org.w3c.dom.Document docToSerialize = getDocument();
87 *
88 *        // Get a factory (DOMImplementationLS) for creating a Load and Save object.
89 *        org.w3c.dom.ls.DOMImplementationLS impl =
90 *            (org.w3c.dom.ls.DOMImplementationLS)
91 *            org.w3c.dom.bootstrap.DOMImplementationRegistry.newInstance().getDOMImplementation("LS");
92 *
93 *        // Use the factory to create an object (LSSerializer) used to
94 *        // write out or save the document.
95 *        org.w3c.dom.ls.LSSerializer writer = impl.createLSSerializer();
96 *        org.w3c.dom.DOMConfiguration config = writer.getDomConfig();
97 *        config.setParameter("format-pretty-print", Boolean.TRUE);
98 *
99 *        // 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 */
115public 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}
171