001: package javax.xml.stream;
002:
003: import javax.xml.namespace.NamespaceContext;
004:
005: /**
006: * The XMLStreamWriter interface specifies how to write XML. The XMLStreamWriter does
007: * not perform well formedness checking on its input. However
008: * the writeCharacters method is required to escape & , < and >
009: * For attribute values the writeAttribute method will escape the
010: * above characters plus " to ensure that all character content
011: * and attribute values are well formed.
012: *
013: * Each NAMESPACE
014: * and ATTRIBUTE must be individually written.
015: *
016: * If javax.xml.stream.isPrefixDefaulting is set to false it is a fatal error if an element
017: * is written with namespace URI that has not been bound to a prefix.
018: *
019: * If javax.xml.stream.isPrefixDefaulting is set to true the XMLStreamWriter implementation
020: * must write a prefix for each unbound URI that it encounters in the
021: * current scope.
022: *
023: * @version 1.0
024: * @author Copyright (c) 2003 by BEA Systems. All Rights Reserved.
025: * @see XMLOutputFactory
026: * @see XMLStreamReader
027: */
028: public interface XMLStreamWriter {
029:
030: /**
031: * Writes a start tag to the output. All writeStartElement methods
032: * open a new scope in the internal namespace context. Writing the
033: * corresponding EndElement causes the scope to be closed.
034: * @param localName local name of the tag, may not be null
035: * @throws XMLStreamException
036: */
037: public void writeStartElement(String localName)
038: throws XMLStreamException;
039:
040: /**
041: * Writes a start tag to the output
042: * @param namespaceURI the namespaceURI of the prefix to use, may not be null
043: * @param localName local name of the tag, may not be null
044: * @throws XMLStreamException if the namespace URI has not been bound to a prefix and
045: * javax.xml.stream.isPrefixDefaulting has not been set to true
046: */
047: public void writeStartElement(String namespaceURI, String localName)
048: throws XMLStreamException;
049:
050: /**
051: * Writes a start tag to the output
052: * @param localName local name of the tag, may not be null
053: * @param prefix the prefix of the tag, may not be null
054: * @param namespaceURI the uri to bind the prefix to, may not be null
055: * @throws XMLStreamException
056: */
057: public void writeStartElement(String prefix, String localName,
058: String namespaceURI) throws XMLStreamException;
059:
060: /**
061: * Writes an empty element tag to the output
062: * @param namespaceURI the uri to bind the tag to, may not be null
063: * @param localName local name of the tag, may not be null
064: * @throws XMLStreamException if the namespace URI has not been bound to a prefix and
065: * javax.xml.stream.isPrefixDefaulting has not been set to true
066: */
067: public void writeEmptyElement(String namespaceURI, String localName)
068: throws XMLStreamException;
069:
070: /**
071: * Writes an empty element tag to the output
072: * @param prefix the prefix of the tag, may not be null
073: * @param localName local name of the tag, may not be null
074: * @param namespaceURI the uri to bind the tag to, may not be null
075: * @throws XMLStreamException
076: */
077: public void writeEmptyElement(String prefix, String localName,
078: String namespaceURI) throws XMLStreamException;
079:
080: /**
081: * Writes an empty element tag to the output
082: * @param localName local name of the tag, may not be null
083: * @throws XMLStreamException
084: */
085: public void writeEmptyElement(String localName)
086: throws XMLStreamException;
087:
088: /**
089: * Writes string data to the output without checking for well formedness.
090: * The data is opaque to the XMLStreamWriter, i.e. the characters are written
091: * blindly to the underlying output. If the method cannot be supported
092: * in the currrent writing context the implementation may throw a
093: * UnsupportedOperationException. For example note that any
094: * namespace declarations, end tags, etc. will be ignored and could
095: * interfere with proper maintanence of the writers internal state.
096: *
097: * @param data the data to write
098: */
099: // public void writeRaw(String data) throws XMLStreamException;
100: /**
101: * Writes an end tag to the output relying on the internal
102: * state of the writer to determine the prefix and local name
103: * of the event.
104: * @throws XMLStreamException
105: */
106: public void writeEndElement() throws XMLStreamException;
107:
108: /**
109: * Closes any start tags and writes corresponding end tags.
110: * @throws XMLStreamException
111: */
112: public void writeEndDocument() throws XMLStreamException;
113:
114: /**
115: * Close this writer and free any resources associated with the
116: * writer. This must not close the underlying output stream.
117: * @throws XMLStreamException
118: */
119: public void close() throws XMLStreamException;
120:
121: /**
122: * Write any cached data to the underlying output mechanism.
123: * @throws XMLStreamException
124: */
125: public void flush() throws XMLStreamException;
126:
127: /**
128: * Writes an attribute to the output stream without
129: * a prefix.
130: * @param localName the local name of the attribute
131: * @param value the value of the attribute
132: * @throws IllegalStateException if the current state does not allow Attribute writing
133: * @throws XMLStreamException
134: */
135: public void writeAttribute(String localName, String value)
136: throws XMLStreamException;
137:
138: /**
139: * Writes an attribute to the output stream
140: * @param prefix the prefix for this attribute
141: * @param namespaceURI the uri of the prefix for this attribute
142: * @param localName the local name of the attribute
143: * @param value the value of the attribute
144: * @throws IllegalStateException if the current state does not allow Attribute writing
145: * @throws XMLStreamException if the namespace URI has not been bound to a prefix and
146: * javax.xml.stream.isPrefixDefaulting has not been set to true
147: */
148:
149: public void writeAttribute(String prefix, String namespaceURI,
150: String localName, String value) throws XMLStreamException;
151:
152: /**
153: * Writes an attribute to the output stream
154: * @param namespaceURI the uri of the prefix for this attribute
155: * @param localName the local name of the attribute
156: * @param value the value of the attribute
157: * @throws IllegalStateException if the current state does not allow Attribute writing
158: * @throws XMLStreamException if the namespace URI has not been bound to a prefix and
159: * javax.xml.stream.isPrefixDefaulting has not been set to true
160: */
161: public void writeAttribute(String namespaceURI, String localName,
162: String value) throws XMLStreamException;
163:
164: /**
165: * Writes a namespace to the output stream
166: * If the prefix argument to this method is the empty string,
167: * "xmlns", or null this method will delegate to writeDefaultNamespace
168: *
169: * @param prefix the prefix to bind this namespace to
170: * @param namespaceURI the uri to bind the prefix to
171: * @throws IllegalStateException if the current state does not allow Namespace writing
172: * @throws XMLStreamException
173: */
174: public void writeNamespace(String prefix, String namespaceURI)
175: throws XMLStreamException;
176:
177: /**
178: * Writes the default namespace to the stream
179: * @param namespaceURI the uri to bind the default namespace to
180: * @throws IllegalStateException if the current state does not allow Namespace writing
181: * @throws XMLStreamException
182: */
183: public void writeDefaultNamespace(String namespaceURI)
184: throws XMLStreamException;
185:
186: /**
187: * Writes an xml comment with the data enclosed
188: * @param data the data contained in the comment, may be null
189: * @throws XMLStreamException
190: */
191: public void writeComment(String data) throws XMLStreamException;
192:
193: /**
194: * Writes a processing instruction
195: * @param target the target of the processing instruction, may not be null
196: * @throws XMLStreamException
197: */
198: public void writeProcessingInstruction(String target)
199: throws XMLStreamException;
200:
201: /**
202: * Writes a processing instruction
203: * @param target the target of the processing instruction, may not be null
204: * @param data the data contained in the processing instruction, may not be null
205: * @throws XMLStreamException
206: */
207: public void writeProcessingInstruction(String target, String data)
208: throws XMLStreamException;
209:
210: /**
211: * Writes a CData section
212: * @param data the data contained in the CData Section, may not be null
213: * @throws XMLStreamException
214: */
215: public void writeCData(String data) throws XMLStreamException;
216:
217: /**
218: * Write a DTD section. This string represents the entire doctypedecl production
219: * from the XML 1.0 specification.
220: *
221: * @param dtd the DTD to be written
222: * @throws XMLStreamException
223: */
224: public void writeDTD(String dtd) throws XMLStreamException;
225:
226: /**
227: * Writes an entity reference
228: * @param name the name of the entity
229: * @throws XMLStreamException
230: */
231: public void writeEntityRef(String name) throws XMLStreamException;
232:
233: /**
234: * Write the XML Declaration. Defaults the XML version to 1.0, and the encoding to utf-8
235: * @throws XMLStreamException
236: */
237: public void writeStartDocument() throws XMLStreamException;
238:
239: /**
240: * Write the XML Declaration. Defaults the XML version to 1.0
241: * @param version version of the xml document
242: * @throws XMLStreamException
243: */
244: public void writeStartDocument(String version)
245: throws XMLStreamException;
246:
247: /**
248: * Write the XML Declaration. Note that the encoding parameter does
249: * not set the actual encoding of the underlying output. That must
250: * be set when the instance of the XMLStreamWriter is created using the
251: * XMLOutputFactory
252: * @param encoding encoding of the xml declaration
253: * @param version version of the xml document
254: * @throws XMLStreamException
255: */
256: public void writeStartDocument(String encoding, String version)
257: throws XMLStreamException;
258:
259: /**
260: * Write text to the output
261: * @param text the value to write
262: * @throws XMLStreamException
263: */
264: public void writeCharacters(String text) throws XMLStreamException;
265:
266: /**
267: * Write text to the output
268: * @param text the value to write
269: * @param start the starting position in the array
270: * @param len the number of characters to write
271: * @throws XMLStreamException
272: */
273: public void writeCharacters(char[] text, int start, int len)
274: throws XMLStreamException;
275:
276: /**
277: * Gets the prefix the uri is bound to
278: * @return the prefix or null
279: * @throws XMLStreamException
280: */
281: public String getPrefix(String uri) throws XMLStreamException;
282:
283: /**
284: * Sets the prefix the uri is bound to. This prefix is bound
285: * in the scope of the current START_ELEMENT / END_ELEMENT pair.
286: * If this method is called before a START_ELEMENT has been written
287: * the prefix is bound in the root scope.
288: * @param prefix the prefix to bind to the uri, may not be null
289: * @param uri the uri to bind to the prefix, may be null
290: * @throws XMLStreamException
291: */
292: public void setPrefix(String prefix, String uri)
293: throws XMLStreamException;
294:
295: /**
296: * Binds a URI to the default namespace
297: * This URI is bound
298: * in the scope of the current START_ELEMENT / END_ELEMENT pair.
299: * If this method is called before a START_ELEMENT has been written
300: * the uri is bound in the root scope.
301: * @param uri the uri to bind to the default namespace, may be null
302: * @throws XMLStreamException
303: */
304: public void setDefaultNamespace(String uri)
305: throws XMLStreamException;
306:
307: /**
308: * Sets the current namespace context for prefix and uri bindings.
309: * This context becomes the root namespace context for writing and
310: * will replace the current root namespace context. Subsequent calls
311: * to setPrefix and setDefaultNamespace will bind namespaces using
312: * the context passed to the method as the root context for resolving
313: * namespaces. This method may only be called once at the start of
314: * the document. It does not cause the namespaces to be declared.
315: * If a namespace URI to prefix mapping is found in the namespace
316: * context it is treated as declared and the prefix may be used
317: * by the StreamWriter.
318: * @param context the namespace context to use for this writer, may not be null
319: * @throws XMLStreamException
320: */
321: public void setNamespaceContext(NamespaceContext context)
322: throws XMLStreamException;
323:
324: /**
325: * Returns the current namespace context.
326: * @return the current NamespaceContext
327: */
328: public NamespaceContext getNamespaceContext();
329:
330: /**
331: * Get the value of a feature/property from the underlying implementation
332: * @param name The name of the property, may not be null
333: * @return The value of the property
334: * @throws IllegalArgumentException if the property is not supported
335: * @throws NullPointerException if the name is null
336: */
337: public Object getProperty(java.lang.String name)
338: throws IllegalArgumentException;
339:
340: }
|