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;
022:
023: import com.sun.xml.txw2.annotation.XmlElement;
024: import com.sun.xml.txw2.output.XmlSerializer;
025:
026: import javax.xml.namespace.QName;
027:
028: /**
029: * Defines common operations for all typed XML writers.
030: * Root of all typed XML writer interfaces.
031: *
032: * <p>
033: * This interface defines a series of methods to allow client applications
034: * to write arbitrary well-formed documents.
035: *
036: * @author Kohsuke Kawaguchi
037: */
038: public interface TypedXmlWriter {
039: /**
040: * Commits this element (and all its descendants) to the output.
041: *
042: * <p>
043: * Short for <tt>_commit(true)</tt>.
044: */
045: void commit();
046:
047: /**
048: * Commits this element (and all its descendants) to the output.
049: *
050: * <p>
051: * Once a writer is committed, nothing can be added to it further.
052: * Committing allows TXW to output a part of the document even
053: * if the rest has not yet been written.
054: *
055: * @param includingAllPredecessors
056: * if false, this operation will _commit this writer and all its
057: * descendants writers. If true, in addition to those writers,
058: * this operation will close all the writers before this writer
059: * in the document order.
060: */
061: void commit(boolean includingAllPredecessors);
062:
063: /**
064: * Blocks the writing of the start tag so that
065: * new attributes can be added even after child
066: * elements are appended.
067: *
068: * <p>
069: * This blocks the output at the token before the start tag until
070: * the {@link #commit()} method is called to _commit this element.
071: *
072: * <p>
073: * For more information, see the TXW documentation.
074: */
075: void block();
076:
077: /**
078: * Gets the {@link Document} object that this writer is writing to.
079: *
080: * @return
081: * always non-null.
082: */
083: Document getDocument();
084:
085: /**
086: * Adds an attribute of the given name and the value.
087: *
088: * <p>
089: * Short for <pre>_attribute("",localName,value);</pre>
090: *
091: * @see #_attribute(String, String, Object)
092: */
093: void _attribute(String localName, Object value);
094:
095: /**
096: * Adds an attribute of the given name and the value.
097: *
098: * <p>
099: * Short for <pre>_attribute(new QName(nsUri,localName),value);</pre>
100: *
101: * @see #_attribute(QName, Object)
102: */
103: void _attribute(String nsUri, String localName, Object value);
104:
105: /**
106: * Adds an attribute of the given name and the value.
107: *
108: * @param attributeName
109: * must not be null.
110: * @param value
111: * value of the attribute.
112: * must not be null.
113: * See the documentation for the conversion rules.
114: */
115: void _attribute(QName attributeName, Object value);
116:
117: /**
118: * Declares a new namespace URI on this element.
119: *
120: * <p>
121: * The runtime system will assign an unique prefix for the URI.
122: *
123: * @param uri
124: * can be empty, but must not be null.
125: */
126: void _namespace(String uri);
127:
128: /**
129: * Declares a new namespace URI on this element to
130: * a specific prefix.
131: *
132: * @param uri
133: * can be empty, but must not be null.
134: * @param prefix
135: * If non-empty, this prefix is bound to the URI
136: * on this element. If empty, then the runtime will still try to
137: * use the URI as the default namespace, but it may fail to do so
138: * because of the constraints in the XML.
139: *
140: * @throws IllegalArgumentException
141: * if the same prefix is already declared on this element.
142: */
143: void _namespace(String uri, String prefix);
144:
145: /**
146: * Declares a new namespace URI on this element.
147: *
148: * <p>
149: * The runtime system will assign an unique prefix for the URI.
150: *
151: * @param uri
152: * can be empty, but must not be null.
153: * @param requirePrefix
154: * if false, this method behaves just like {@link #_namespace(String)}.
155: * if true, this guarantees that the URI is bound to a non empty prefix.
156: */
157: void _namespace(String uri, boolean requirePrefix);
158:
159: /**
160: * Appends text data.
161: *
162: * @param value
163: * must not be null.
164: * See the documentation for the conversion rules.
165: */
166: void _pcdata(Object value);
167:
168: /**
169: * Appends CDATA section.
170: *
171: * @param value
172: * must not be null.
173: * See the documentation for the conversion rules.
174: */
175: void _cdata(Object value);
176:
177: /**
178: * Appends a comment.
179: *
180: * @param value
181: * must not be null.
182: * See the documentation for the conversion rules.
183: *
184: * @throws UnsupportedOperationException
185: * if the underlying {@link XmlSerializer} does not support
186: * writing comments, this exception can be thrown.
187: */
188: void _comment(Object value) throws UnsupportedOperationException;
189:
190: /**
191: * Appends a new child element.
192: *
193: * <p>
194: * Short for <pre>_element(<i>URI of this element</i>,localName,contentModel);</pre>
195: *
196: * <p>
197: * The namespace URI will be inherited from the parent element.
198: *
199: * @see #_element(String, String, Class)
200: */
201: <T extends TypedXmlWriter> T _element(String localName,
202: Class<T> contentModel);
203:
204: /**
205: * Appends a new child element.
206: *
207: * <p>
208: * The newly created child element is appended at the end of the children.
209: *
210: * @param nsUri
211: * The namespace URI of the newly created element.
212: * @param localName
213: * The local name of the newly created element.
214: * @param contentModel
215: * The typed XML writer interface used to write the children of
216: * the new child element.
217: *
218: * @return
219: * always return non-null {@link TypedXmlWriter} that can be used
220: * to write the contents of the newly created child element.
221: */
222: <T extends TypedXmlWriter> T _element(String nsUri,
223: String localName, Class<T> contentModel);
224:
225: /**
226: * Appends a new child element.
227: *
228: * <p>
229: * Short for <pre>_element(tagName.getNamespaceURI(),tagName.getLocalPart(),contentModel);</pre>
230: *
231: * @see #_element(String, String, Class)
232: */
233: <T extends TypedXmlWriter> T _element(QName tagName,
234: Class<T> contentModel);
235:
236: /**
237: * Appends a new child element.
238: *
239: * <p>
240: * This version of the _element method requires the <i>T</i> class to be
241: * annotated with {@link XmlElement} annotation. The element name will be
242: * taken from there.
243: *
244: * @see #_element(String, String, Class)
245: */
246: <T extends TypedXmlWriter> T _element(Class<T> contentModel);
247:
248: /**
249: * Returns a different interface for this typed XML Writer.
250: *
251: * <p>
252: * Semantically, this operation is a 'cast' --- it returns the same underlying
253: * writer in a different interface. The returned new writer and the current writer
254: * will write to the same element.
255: *
256: * <p>
257: * But this is different from Java's ordinary cast because the returned object
258: * is not always the same as the current object.
259: *
260: * @return
261: * always return non-null.
262: */
263: <T extends TypedXmlWriter> T _cast(Class<T> targetInterface);
264: }
|