/* * 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. *

* * See the DOM Level 3 Load and Save interface at LSSeializer. * * For a list of configuration parameters for DOM Level 3 see DOMConfiguration. * For additional configuration parameters available with the DOM Level 3 Load and Save API LSSerializer see * LSerializer config. *

* 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. *

* Example: * 

 *    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 = "".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
 *
* * @see DOMConfiguration * @see LSSerializer * @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); }