Java example source code file (XmlSerializer.java)

This example Java source code file (XmlSerializer.java) is included in the alvinalexander.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" ^TM.

Learn more about this Java project at its project page.

Java - Java tags/keywords

xmlserializer

The XmlSerializer.java Java example source code

/*
 * Copyright (c) 2005, 2010, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package com.sun.xml.internal.txw2.output;

import com.sun.xml.internal.txw2.TypedXmlWriter;


/**
 * Low-level typeless XML writer driven from {@link TypedXmlWriter}.
 *
 * <p>
 * Applications can use one of the predefined implementations to
 * send TXW output to the desired location/format, or they can
 * choose to implement this interface for custom output.
 *
 * <p>
 * One {@link XmlSerializer} instance is responsible for writing
 * one XML document.
 *
 * <h2>Call Sequence
 * TXW calls methods on this interface in the following order:
 *
 * <pre>
 * WHOLE_SEQUENCE := startDocument ELEMENT endDocument
 * ELEMENT := beginStartTag writeXmlns* writeAttribute* endStartTag CONTENT endTag
 * CONTENT := (text|ELEMENT)*
 * </pre>
 *
 * <p>
 * TXW maintains all the in-scope namespace bindings and prefix allocation.
 * The {@link XmlSerializer} implementation should just use the prefix
 * specified.
 * </p>
 *
 * @author Kohsuke Kawaguchi (kohsuke.kawaguchi@sun.com)
 */
public interface XmlSerializer {
    /**
     * The first method to be called.
     */
    void startDocument();

    /**
     * Begins writing a start tag.
     *
     * @param uri
     *      the namespace URI of the element. Can be empty but never be null.
     * @param prefix
     *      the prefix that should be used for this element. Can be empty,
     *      but never null.
     */
    void beginStartTag(String uri,String localName,String prefix);

    /**
     * Writes an attribute.
     *
     * @param value
     *      The value of the attribute. It's the callee's responsibility to
     *      escape special characters (such as <, >, and &) in this buffer.
     *
     * @param uri
     *      the namespace URI of the attribute. Can be empty but never be null.
     * @param prefix
     *      the prefix that should be used for this attribute. Can be empty,
     *      but never null.
     */
    void writeAttribute(String uri,String localName,String prefix,StringBuilder value);

    /**
     * Writes a namespace declaration.
     *
     * @param uri
     *      the namespace URI to be declared. Can be empty but never be null.
     * @param prefix
     *      the prefix that is allocated. Can be empty but never be null.
     */
    void writeXmlns(String prefix,String uri);

    /**
     * Completes the start tag.
     *
     * @param uri
     *      the namespace URI of the element. Can be empty but never be null.
     * @param prefix
     *      the prefix that should be used for this element. Can be empty,
     *      but never null.
     */
    void endStartTag(String uri,String localName,String prefix);

    /**
     * Writes an end tag.
     */
    void endTag();

    /**
     * Writes PCDATA.
     *
     * @param text
     *      The character data to be written. It's the callee's responsibility to
     *      escape special characters (such as <, >, and &) in this buffer.
     */
    void text(StringBuilder text);

    /**
     * Writes CDATA.
     */
    void cdata(StringBuilder text);

    /**
     * Writes a comment.
     *
     * @throws UnsupportedOperationException
     *      if the writer doesn't support writing a comment, it can throw this exception.
     */
    void comment(StringBuilder comment);

    /**
     * The last method to be called.
     */
    void endDocument();

    /**
     * Flush the buffer.
     *
     * This method is called when applications invoke {@link TypedXmlWriter#commit(boolean)}
     * method. If the implementation performs any buffering, it should flush the buffer.
     */
    void flush();
}