/*
* 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;
/**
* 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.
* 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>
*
* @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 advanced
*
*/
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);
}