001: /*
002: * The contents of this file are subject to the terms
003: * of the Common Development and Distribution License
004: * (the "License"). You may not use this file except
005: * in compliance with the License.
006: *
007: * You can obtain a copy of the license at
008: * https://jwsdp.dev.java.net/CDDLv1.0.html
009: * See the License for the specific language governing
010: * permissions and limitations under the License.
011: *
012: * When distributing Covered Code, include this CDDL
013: * HEADER in each file and include the License file at
014: * https://jwsdp.dev.java.net/CDDLv1.0.html If applicable,
015: * add the following below this CDDL HEADER, with the
016: * fields enclosed by brackets "[]" replaced with your
017: * own identifying information: Portions Copyright [yyyy]
018: * [name of copyright owner]
019: */
020:
021: package com.sun.xml.txw2.output;
022:
023: import com.sun.xml.txw2.TypedXmlWriter;
024:
025: /**
026: * Low-level typeless XML writer driven from {@link TypedXmlWriter}.
027: *
028: * <p>
029: * Applications can use one of the predefined implementations to
030: * send TXW output to the desired location/format, or they can
031: * choose to implement this interface for custom output.
032: *
033: * <p>
034: * One {@link XmlSerializer} instance is responsible for writing
035: * one XML document.
036: *
037: * <h2>Call Sequence</h2>
038: * TXW calls methods on this interface in the following order:
039: *
040: * <pre>
041: * WHOLE_SEQUENCE := startDocument ELEMENT endDocument
042: * ELEMENT := beginStartTag writeXmlns* writeAttribute* endStartTag CONTENT endTag
043: * CONTENT := (text|ELEMENT)*
044: * </pre>
045: *
046: * <p>
047: * TXW maintains all the in-scope namespace bindings and prefix allocation.
048: * The {@link XmlSerializer} implementation should just use the prefix
049: * specified.
050: * </p>
051: *
052: * @author Kohsuke Kawaguchi (kohsuke.kawaguchi@sun.com)
053: */
054: public interface XmlSerializer {
055: /**
056: * The first method to be called.
057: */
058: void startDocument();
059:
060: /**
061: * Begins writing a start tag.
062: *
063: * @param uri
064: * the namespace URI of the element. Can be empty but never be null.
065: * @param prefix
066: * the prefix that should be used for this element. Can be empty,
067: * but never null.
068: */
069: void beginStartTag(String uri, String localName, String prefix);
070:
071: /**
072: * Writes an attribute.
073: *
074: * @param value
075: * The value of the attribute. It's the callee's responsibility to
076: * escape special characters (such as <, >, and &) in this buffer.
077: *
078: * @param uri
079: * the namespace URI of the attribute. Can be empty but never be null.
080: * @param prefix
081: * the prefix that should be used for this attribute. Can be empty,
082: * but never null.
083: */
084: void writeAttribute(String uri, String localName, String prefix,
085: StringBuilder value);
086:
087: /**
088: * Writes a namespace declaration.
089: *
090: * @param uri
091: * the namespace URI to be declared. Can be empty but never be null.
092: * @param prefix
093: * the prefix that is allocated. Can be empty but never be null.
094: */
095: void writeXmlns(String prefix, String uri);
096:
097: /**
098: * Completes the start tag.
099: *
100: * @param uri
101: * the namespace URI of the element. Can be empty but never be null.
102: * @param prefix
103: * the prefix that should be used for this element. Can be empty,
104: * but never null.
105: */
106: void endStartTag(String uri, String localName, String prefix);
107:
108: /**
109: * Writes an end tag.
110: */
111: void endTag();
112:
113: /**
114: * Writes PCDATA.
115: *
116: * @param text
117: * The character data to be written. It's the callee's responsibility to
118: * escape special characters (such as <, >, and &) in this buffer.
119: */
120: void text(StringBuilder text);
121:
122: /**
123: * Writes CDATA.
124: */
125: void cdata(StringBuilder text);
126:
127: /**
128: * Writes a comment.
129: *
130: * @throws UnsupportedOperationException
131: * if the writer doesn't support writing a comment, it can throw this exception.
132: */
133: void comment(StringBuilder comment);
134:
135: /**
136: * The last method to be called.
137: */
138: void endDocument();
139:
140: /**
141: * Flush the buffer.
142: *
143: * This method is called when applications invoke {@link TypedXmlWriter#commit(boolean)}
144: * method. If the implementation performs any buffering, it should flush the buffer.
145: */
146: void flush();
147: }
|