/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements. See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership. The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the  "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/*
 * $Id:  $
 */

package org.apache.xml.serializer;

import java.io.IOException;

import org.w3c.dom.DOMErrorHandler;
import org.w3c.dom.Node;
import org.w3c.dom.ls.LSSerializerFilter;

/**
 * Interface for a DOM serializer capable of serializing DOMs as specified in 
 * the DOM Level 3 Save Recommendation. This interface is not intended to be used
 * by an end user, but rather by an XML parser that is implementing the DOM 
 * Level 3 Load and Save APIs.
 * <p>
 * 
 * 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>.
 * 
 * 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>.
 * For additional configuration parameters available with the DOM Level 3 Load and Save API LSSerializer see
 * <a href="http://www.w3.org/TR/2004/REC-DOM-Level-3-LS-20040407/load-save.html#LS-LSSerializer-config">LSerializer config</a>.
 * <p>
 * The following example uses a DOM3Serializer indirectly, through an an XML
 * parser that uses this class as part of its implementation of the DOM Level 3
 * Load and Save APIs, and is the prefered way to serialize with DOM Level 3 APIs.
 * <p>
 * Example:
 * <pre>
 *    public class TestDOM3 {
 *
 *    public static void main(String args[]) throws Exception {
 *        // Get document to serialize
 *        TestDOM3 test = new TestDOM3();
 *        
 *        // Serialize using standard DOM Level 3 Load/Save APIs        
 *        System.out.println(test.testDOM3LS());
 *    }
 *
 *    public org.w3c.dom.Document getDocument() throws Exception {
 *        // Create a simple DOM Document.
 *        javax.xml.parsers.DocumentBuilderFactory factory = 
 *            javax.xml.parsers.DocumentBuilderFactory.newInstance();
 *        javax.xml.parsers.DocumentBuilder builder = factory.newDocumentBuilder();
 *        byte[] bytes = "<parent><child/></parent>".getBytes();
 *        java.io.InputStream is = new java.io.ByteArrayInputStream(bytes);
 *        org.w3c.dom.Document doc = builder.parse(is);
 *        return doc;
 *    }
 *    
 *    //
 *    // This method uses standard DOM Level 3 Load Save APIs:
 *    //   org.w3c.dom.bootstrap.DOMImplementationRegistry
 *    //   org.w3c.dom.ls.DOMImplementationLS
 *    //   org.w3c.dom.ls.DOMImplementationLS
 *    //   org.w3c.dom.ls.LSSerializer
 *    //   org.w3c.dom.DOMConfiguration
 *    //   
 *    // The only thing non-standard in this method is the value set for the
 *    // name of the class implementing the DOM Level 3 Load Save APIs,
 *    // which in this case is:
 *    //   org.apache.xerces.dom.DOMImplementationSourceImpl
 *    //
 *
 *    public String testDOM3LS() throws Exception {
 *        
 *        // Get a simple DOM Document that will be serialized.
 *        org.w3c.dom.Document docToSerialize = getDocument();
 *
 *        // Get a factory (DOMImplementationLS) for creating a Load and Save object.
 *        System.setProperty(org.w3c.dom.bootstrap.DOMImplementationRegistry.PROPERTY,
 *                "org.apache.xerces.dom.DOMImplementationSourceImpl");
 *        org.w3c.dom.ls.DOMImplementationLS impl = 
 *            (org.w3c.dom.ls.DOMImplementationLS) 
 *            org.w3c.dom.bootstrap.DOMImplementationRegistry.newInstance().getDOMImplementation("LS");
 *
 *        // Use the factory to create an object (LSSerializer) used to 
 *        // write out or save the document.
 *        org.w3c.dom.ls.LSSerializer writer = impl.createLSSerializer();
 *        org.w3c.dom.DOMConfiguration config = writer.getDomConfig();
 *        config.setParameter("format-pretty-print", Boolean.TRUE);
 *        
 *        // Use the LSSerializer to write out or serialize the document to a String.
 *        String serializedXML = writer.writeToString(docToSerialize);
 *        return serializedXML;
 *    }
 *    
 *    }  // end of class TestDOM3
 * </pre>
 * <p>
 * The DOM3Serializer is a facet of a serializer and is obtained from the
 * asDOM3Serializer() method of the org.apache.xml.serializer.Serializer interface. 
 * A serializer may or may not support a level 3 DOM serializer, if it does not then the 
 * return value from asDOM3Serializer() is null.
 * <p>
 * Using the DOM3Serializer interface directly is discouraged for use by end users.
 * <p>
 * Example:
 * <pre>
 *   public class TestDOM3 {
 *
 *   public static void main(String args[]) throws Exception {
 *       // Get document to serialize
 *       TestDOM3 test = new TestDOM3();
 *       
 *       // Serialize using implementation specific
 *       // non-standard serialization
 *       // APIs (use standard DOM Level 3 if you can) 
 *       System.out.println(test.testDOM3Xalan());
 *   }
 *   
 *   //
 *   // This method uses non-standard, implementation specific
 *   // classes:
 *   //   org.apache.xml.serializer.OutputPropertiesFactory
 *   //   org.apache.xml.serializer.SerializerFactory
 *   //   org.apache.xml.serializer.Serializer
 *   //   org.apache.xml.serializer.DOM3Serializer
 *   // to serialize a Document.
 *   // 
 *   // These classes are intended to be used by an XML
 *   // parser to implement Load Save support for DOM Level 3.
 *   // They are not intended for use by an end user.
 *   //
 *   public String testDOM3Xalan() throws Exception {
 *       // Get a simple DOM Document that will be serialized.
 *       org.w3c.dom.Document doc = getDocument();
 *    
 *       // Get the default properties for serializing XML
 *       java.util.Properties configProps = org.apache.xml.serializer.OutputPropertiesFactory
 *               .getDefaultMethodProperties("xml");
 *       
 *       // Get a Serializer from the non-standard factory
 *       org.apache.xml.serializer.Serializer ser = org.apache.xml.serializer.SerializerFactory
 *               .getSerializer(configProps);
 *       java.io.StringWriter sw = new java.io.StringWriter();
 *       // Set the writer where the Serializer should write its output to.
 *       ser.setWriter(sw);
 *    
 *       // Configure the Serializer with additional non-standard properties
 *       // for DOM Level 3 serialization:
 *       java.util.Properties props = new java.util.Properties();
 *       props.setProperty(
 *               "{http://www.w3.org/TR/DOM-Level-3-LS}format-pretty-print",
 *               "explicit:yes");
 *       ser.setOutputFormat(props);
 *    
 *       // Cast the Serializer to a DOM3Serializer and use it to serialize the Document.
 *       org.apache.xml.serializer.DOM3Serializer dser = (org.apache.xml.serializer.DOM3Serializer) ser
 *               .asDOM3Serializer();
 *       dser.serializeDOM3(doc);
 *       String serializedXML = sw.toString();
 *       return serializedXML;
 *   }
 *   
 *   }  // end of class TestDOM3
 *   
 * </pre>
 * <p>
 * If a DOM3Serializer is used directly (not through the DOM Level 3 API LSSerializer,
 * then the configuration properties for DOM Level 3 are supported:
 * <ul>
 * <li> "cdata-sections"
 * <li> "comments"
 * <li> "element-content-whitespace"
 * <li> "entities"
 * <li> "infoset"
 * <li> "namespaces"
 * <li> "namespace-declarations"
 * <li> "split-cdata-sections"
 * <li> "well-formed"
 * </ul>
 * <p>
 * Also the following propertes for DOM Level 3 Load and Save are supported:
 * <ul>
 * <li> "{http://www.w3.org/TR/DOM-Level-3-LS}format-pretty-print" 
 * <li> "format-pretty-print"
 * <li> "xml-declaration"
 * </ul>
 * 
 * @see <a href="http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407/core.html#DOMConfiguration">DOMConfiguration</a>
 * @see <a href="http://www.w3.org/TR/2004/REC-DOM-Level-3-LS-20040407/load-save.html#LS-LSSerializer-config">LSSerializer</a>
 * @see org.apache.xml.serializer.Serializer
 * @see org.apache.xml.serializer.DOMSerializer
 * 
 * @xsl.usage general
 *
 */
public interface DOM3Serializer {
    /**
     * Serializes the Level 3 DOM node. Throws an exception only if an I/O
     * exception occured while serializing.
     * 
     * This interface is a public API.
     *
     * @param node the Level 3 DOM node to serialize
     * @throws IOException if an I/O exception occured while serializing
     */
    public void serializeDOM3(Node node) throws IOException;

    /**
     * Sets a DOMErrorHandler on the DOM Level 3 Serializer.
     * 
     * This interface is a public API.
     *
     * @param handler the Level 3 DOMErrorHandler
     */
    public void setErrorHandler(DOMErrorHandler handler);

    /**
     * Returns a DOMErrorHandler set on the DOM Level 3 Serializer.
     * 
     * This interface is a public API.
     *
     * @return A Level 3 DOMErrorHandler
     */
    public DOMErrorHandler getErrorHandler();

    /**
     * Sets a LSSerializerFilter on the DOM Level 3 Serializer to filter nodes
     * during serialization.
     * 
     * This interface is a public API.
     *
     * @param filter the Level 3 LSSerializerFilter
     */
    public void setNodeFilter(LSSerializerFilter filter);

    /**
     * Returns a LSSerializerFilter set on the DOM Level 3 Serializer to filter nodes
     * during serialization.
     * 
     * This interface is a public API.
     *
     * @return The Level 3 LSSerializerFilter
     */
    public LSSerializerFilter getNodeFilter();

    /**
     * Sets the end-of-line sequence of characters to be used during serialization
     * @param newLine The end-of-line sequence of characters to be used during serialization
     */
    public void setNewLine(char[] newLine);
}