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 com.sun.org.apache.xml.internal.serializer;

    23 

    24 import java.io.IOException;

    25 

    26 import org.w3c.dom.Node;

    27 import org.w3c.dom.DOMErrorHandler;

    28 import org.w3c.dom.ls.LSSerializerFilter;

    29 

    30 /**

    31  * Interface for a DOM serializer capable of serializing DOMs as specified in

    32  * the DOM Level 3 Save Recommendation.

    33  * <p>

    34  * The DOM3Serializer is a facet of a serializer and is obtained from the

    35  * asDOM3Serializer() method of the org.apache.xml.serializer.Serializer interface.

    36  * A serializer may or may not support a level 3 DOM serializer, if it does not then the

    37  * return value from asDOM3Serializer() is null.

    38  * <p>

    39  * Example:

    40  * <pre>

    41  * Document     doc;

    42  * Serializer   ser;

    43  * OutputStream os;

    44  * DOMErrorHandler handler;

    45  *

    46  * ser = ...;

    47  * os = ...;

    48  * handler = ...;

    49  *

    50  * ser.setOutputStream( os );

    51  * DOM3Serialzier dser = (DOM3Serialzier)ser.asDOM3Serializer();

    52  * dser.setErrorHandler(handler);

    53  * dser.serialize(doc);

    54  * </pre>

    55  *

    56  * @see org.apache.xml.serializer.Serializer

    57  *

    58  * @xsl.usage general

    59  *

    60  */

    61 public interface DOM3Serializer {

    62     /**

    63      * Serializes the Level 3 DOM node. Throws an exception only if an I/O

    64      * exception occured while serializing.

    65      *

    66      * This interface is a public API.

    67      *

    68      * @param node the Level 3 DOM node to serialize

    69      * @throws IOException if an I/O exception occured while serializing

    70      */

    71     public void serializeDOM3(Node node) throws IOException;

    72 

    73     /**

    74      * Sets a DOMErrorHandler on the DOM Level 3 Serializer.

    75      *

    76      * This interface is a public API.

    77      *

    78      * @param handler the Level 3 DOMErrorHandler

    79      */

    80     public void setErrorHandler(DOMErrorHandler handler);

    81 

    82     /**

    83      * Returns a DOMErrorHandler set on the DOM Level 3 Serializer.

    84      *

    85      * This interface is a public API.

    86      *

    87      * @return A Level 3 DOMErrorHandler

    88      */

    89     public DOMErrorHandler getErrorHandler();

    90 

    91     /**

    92      * Sets a LSSerializerFilter on the DOM Level 3 Serializer to filter nodes

    93      * during serialization.

    94      *

    95      * This interface is a public API.

    96      *

    97      * @param filter the Level 3 LSSerializerFilter

    98      */

    99     public void setNodeFilter(LSSerializerFilter filter);

   100 

   101     /**

   102      * Returns a LSSerializerFilter set on the DOM Level 3 Serializer to filter nodes

   103      * during serialization.

   104      *

   105      * This interface is a public API.

   106      *

   107      * @return The Level 3 LSSerializerFilter

   108      */

   109     public LSSerializerFilter getNodeFilter();

   110 

   111     /**

   112      * Sets the new line character to be used during serialization

   113      * @param newLine a String that is the end-of-line character sequence to be

   114      * used in serialization.

   115      */

   116     public void setNewLine(String newLine);

   117 }