XmlSerializer.java revision 524:dcaa586ab756 
1/*
2 * Copyright (c) 2005, 2012, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation.  Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26package com.sun.xml.internal.txw2.output;
27
28import com.sun.xml.internal.txw2.TypedXmlWriter;
29
30
31/**
32 * Low-level typeless XML writer driven from {@link TypedXmlWriter}.
33 *
34 * <p>
35 * Applications can use one of the predefined implementations to
36 * send TXW output to the desired location/format, or they can
37 * choose to implement this interface for custom output.
38 *
39 * <p>
40 * One {@link XmlSerializer} instance is responsible for writing
41 * one XML document.
42 *
43 * <h2>Call Sequence</h2>
44 * TXW calls methods on this interface in the following order:
45 *
46 * <pre>
47 * WHOLE_SEQUENCE := startDocument ELEMENT endDocument
48 * ELEMENT := beginStartTag writeXmlns* writeAttribute* endStartTag CONTENT endTag
49 * CONTENT := (text|ELEMENT)*
50 * </pre>
51 *
52 * <p>
53 * TXW maintains all the in-scope namespace bindings and prefix allocation.
54 * The {@link XmlSerializer} implementation should just use the prefix
55 * specified.
56 * </p>
57 *
58 * @author Kohsuke Kawaguchi (kohsuke.kawaguchi@sun.com)
59 */
60public interface XmlSerializer {
61    /**
62     * The first method to be called.
63     */
64    void startDocument();
65
66    /**
67     * Begins writing a start tag.
68     *
69     * @param uri
70     *      the namespace URI of the element. Can be empty but never be null.
71     * @param prefix
72     *      the prefix that should be used for this element. Can be empty,
73     *      but never null.
74     */
75    void beginStartTag(String uri,String localName,String prefix);
76
77    /**
78     * Writes an attribute.
79     *
80     * @param value
81     *      The value of the attribute. It's the callee's responsibility to
82     *      escape special characters (such as &lt;, &gt;, and &amp;) in this buffer.
83     *
84     * @param uri
85     *      the namespace URI of the attribute. Can be empty but never be null.
86     * @param prefix
87     *      the prefix that should be used for this attribute. Can be empty,
88     *      but never null.
89     */
90    void writeAttribute(String uri,String localName,String prefix,StringBuilder value);
91
92    /**
93     * Writes a namespace declaration.
94     *
95     * @param uri
96     *      the namespace URI to be declared. Can be empty but never be null.
97     * @param prefix
98     *      the prefix that is allocated. Can be empty but never be null.
99     */
100    void writeXmlns(String prefix,String uri);
101
102    /**
103     * Completes the start tag.
104     *
105     * @param uri
106     *      the namespace URI of the element. Can be empty but never be null.
107     * @param prefix
108     *      the prefix that should be used for this element. Can be empty,
109     *      but never null.
110     */
111    void endStartTag(String uri,String localName,String prefix);
112
113    /**
114     * Writes an end tag.
115     */
116    void endTag();
117
118    /**
119     * Writes PCDATA.
120     *
121     * @param text
122     *      The character data to be written. It's the callee's responsibility to
123     *      escape special characters (such as &lt;, &gt;, and &amp;) in this buffer.
124     */
125    void text(StringBuilder text);
126
127    /**
128     * Writes CDATA.
129     */
130    void cdata(StringBuilder text);
131
132    /**
133     * Writes a comment.
134     *
135     * @throws UnsupportedOperationException
136     *      if the writer doesn't support writing a comment, it can throw this exception.
137     */
138    void comment(StringBuilder comment);
139
140    /**
141     * The last method to be called.
142     */
143    void endDocument();
144
145    /**
146     * Flush the buffer.
147     *
148     * This method is called when applications invoke {@link TypedXmlWriter#commit(boolean)}
149     * method. If the implementation performs any buffering, it should flush the buffer.
150     */
151    void flush();
152}
153