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 22 package org.apache.xml.serializer; 23 24 import java.io.IOException; 25 26 import org.w3c.dom.DOMErrorHandler; 27 import org.w3c.dom.Node; 28 import 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 */ 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 */ serializeDOM3(Node node)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 */ setErrorHandler(DOMErrorHandler handler)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 */ getErrorHandler()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 */ setNodeFilter(LSSerializerFilter filter)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 */ getNodeFilter()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 */ setNewLine(char[] newLine)169 public void setNewLine(char[] newLine); 170 } 171