001: /*
002: * Copyright 2006 Sun Microsystems, Inc. All Rights Reserved.
003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004: *
005: * This code is free software; you can redistribute it and/or modify it
006: * under the terms of the GNU General Public License version 2 only, as
007: * published by the Free Software Foundation. Sun designates this
008: * particular file as subject to the "Classpath" exception as provided
009: * by Sun in the LICENSE file that accompanied this code.
010: *
011: * This code is distributed in the hope that it will be useful, but WITHOUT
012: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014: * version 2 for more details (a copy is included in the LICENSE file that
015: * accompanied this code).
016: *
017: * You should have received a copy of the GNU General Public License version
018: * 2 along with this work; if not, write to the Free Software Foundation,
019: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022: * CA 95054 USA or visit www.sun.com if you need additional information or
023: * have any questions.
024: */
025: package com.sun.xml.internal.txw2;
026:
027: import com.sun.xml.internal.txw2.annotation.XmlElement;
028: import com.sun.xml.internal.txw2.output.XmlSerializer;
029:
030: import javax.xml.namespace.QName;
031:
032: /**
033: * Defines common operations for all typed XML writers.
034: * Root of all typed XML writer interfaces.
035: *
036: * <p>
037: * This interface defines a series of methods to allow client applications
038: * to write arbitrary well-formed documents.
039: *
040: * @author Kohsuke Kawaguchi
041: */
042: public interface TypedXmlWriter {
043: /**
044: * Commits this element (and all its descendants) to the output.
045: *
046: * <p>
047: * Short for <tt>_commit(true)</tt>.
048: */
049: void commit();
050:
051: /**
052: * Commits this element (and all its descendants) to the output.
053: *
054: * <p>
055: * Once a writer is committed, nothing can be added to it further.
056: * Committing allows TXW to output a part of the document even
057: * if the rest has not yet been written.
058: *
059: * @param includingAllPredecessors
060: * if false, this operation will _commit this writer and all its
061: * descendants writers. If true, in addition to those writers,
062: * this operation will close all the writers before this writer
063: * in the document order.
064: */
065: void commit(boolean includingAllPredecessors);
066:
067: /**
068: * Blocks the writing of the start tag so that
069: * new attributes can be added even after child
070: * elements are appended.
071: *
072: * <p>
073: * This blocks the output at the token before the start tag until
074: * the {@link #commit()} method is called to _commit this element.
075: *
076: * <p>
077: * For more information, see the TXW documentation.
078: */
079: void block();
080:
081: /**
082: * Gets the {@link Document} object that this writer is writing to.
083: *
084: * @return
085: * always non-null.
086: */
087: Document getDocument();
088:
089: /**
090: * Adds an attribute of the given name and the value.
091: *
092: * <p>
093: * Short for <pre>_attribute("",localName,value);</pre>
094: *
095: * @see #_attribute(String, String, Object)
096: */
097: void _attribute(String localName, Object value);
098:
099: /**
100: * Adds an attribute of the given name and the value.
101: *
102: * <p>
103: * Short for <pre>_attribute(new QName(nsUri,localName),value);</pre>
104: *
105: * @see #_attribute(QName, Object)
106: */
107: void _attribute(String nsUri, String localName, Object value);
108:
109: /**
110: * Adds an attribute of the given name and the value.
111: *
112: * @param attributeName
113: * must not be null.
114: * @param value
115: * value of the attribute.
116: * must not be null.
117: * See the documentation for the conversion rules.
118: */
119: void _attribute(QName attributeName, Object value);
120:
121: /**
122: * Declares a new namespace URI on this element.
123: *
124: * <p>
125: * The runtime system will assign an unique prefix for the URI.
126: *
127: * @param uri
128: * can be empty, but must not be null.
129: */
130: void _namespace(String uri);
131:
132: /**
133: * Declares a new namespace URI on this element to
134: * a specific prefix.
135: *
136: * @param uri
137: * can be empty, but must not be null.
138: * @param prefix
139: * If non-empty, this prefix is bound to the URI
140: * on this element. If empty, then the runtime will still try to
141: * use the URI as the default namespace, but it may fail to do so
142: * because of the constraints in the XML.
143: *
144: * @throws IllegalArgumentException
145: * if the same prefix is already declared on this element.
146: */
147: void _namespace(String uri, String prefix);
148:
149: /**
150: * Declares a new namespace URI on this element.
151: *
152: * <p>
153: * The runtime system will assign an unique prefix for the URI.
154: *
155: * @param uri
156: * can be empty, but must not be null.
157: * @param requirePrefix
158: * if false, this method behaves just like {@link #_namespace(String)}.
159: * if true, this guarantees that the URI is bound to a non empty prefix.
160: */
161: void _namespace(String uri, boolean requirePrefix);
162:
163: /**
164: * Appends text data.
165: *
166: * @param value
167: * must not be null.
168: * See the documentation for the conversion rules.
169: */
170: void _pcdata(Object value);
171:
172: /**
173: * Appends CDATA section.
174: *
175: * @param value
176: * must not be null.
177: * See the documentation for the conversion rules.
178: */
179: void _cdata(Object value);
180:
181: /**
182: * Appends a comment.
183: *
184: * @param value
185: * must not be null.
186: * See the documentation for the conversion rules.
187: *
188: * @throws UnsupportedOperationException
189: * if the underlying {@link XmlSerializer} does not support
190: * writing comments, this exception can be thrown.
191: */
192: void _comment(Object value) throws UnsupportedOperationException;
193:
194: /**
195: * Appends a new child element.
196: *
197: * <p>
198: * Short for <pre>_element(<i>URI of this element</i>,localName,contentModel);</pre>
199: *
200: * <p>
201: * The namespace URI will be inherited from the parent element.
202: *
203: * @see #_element(String, String, Class)
204: */
205: <T extends TypedXmlWriter> T _element(String localName,
206: Class<T> contentModel);
207:
208: /**
209: * Appends a new child element.
210: *
211: * <p>
212: * The newly created child element is appended at the end of the children.
213: *
214: * @param nsUri
215: * The namespace URI of the newly created element.
216: * @param localName
217: * The local name of the newly created element.
218: * @param contentModel
219: * The typed XML writer interface used to write the children of
220: * the new child element.
221: *
222: * @return
223: * always return non-null {@link TypedXmlWriter} that can be used
224: * to write the contents of the newly created child element.
225: */
226: <T extends TypedXmlWriter> T _element(String nsUri,
227: String localName, Class<T> contentModel);
228:
229: /**
230: * Appends a new child element.
231: *
232: * <p>
233: * Short for <pre>_element(tagName.getNamespaceURI(),tagName.getLocalPart(),contentModel);</pre>
234: *
235: * @see #_element(String, String, Class)
236: */
237: <T extends TypedXmlWriter> T _element(QName tagName,
238: Class<T> contentModel);
239:
240: /**
241: * Appends a new child element.
242: *
243: * <p>
244: * This version of the _element method requires the <i>T</i> class to be
245: * annotated with {@link XmlElement} annotation. The element name will be
246: * taken from there.
247: *
248: * @see #_element(String, String, Class)
249: */
250: <T extends TypedXmlWriter> T _element(Class<T> contentModel);
251:
252: /**
253: * Returns a different interface for this typed XML Writer.
254: *
255: * <p>
256: * Semantically, this operation is a 'cast' --- it returns the same underlying
257: * writer in a different interface. The returned new writer and the current writer
258: * will write to the same element.
259: *
260: * <p>
261: * But this is different from Java's ordinary cast because the returned object
262: * is not always the same as the current object.
263: *
264: * @return
265: * always return non-null.
266: */
267: <T extends TypedXmlWriter> T _cast(Class<T> targetInterface);
268: }
|