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    }