KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > xml > stream > XMLEventWriter


1 package javax.xml.stream;
2
3 import javax.xml.stream.events.*;
4 import javax.xml.stream.util.XMLEventConsumer;
5 import javax.xml.namespace.NamespaceContext JavaDoc;
6
7 /**
8  *
9  * This is the top level interface for writing XML documents.
10  *
11  * Instances of this interface are not required to validate the
12  * form of the XML.
13  *
14  * @version 1.0
15  * @author Copyright (c) 2003 by BEA Systems. All Rights Reserved.
16  * @see XMLEventReader
17  * @see javax.xml.stream.events.XMLEvent
18  * @see javax.xml.stream.events.Characters
19  * @see javax.xml.stream.events.ProcessingInstruction
20  * @see javax.xml.stream.events.StartElement
21  * @see javax.xml.stream.events.EndElement
22  * @since 1.6
23  */
24 public interface XMLEventWriter extends XMLEventConsumer {
25
26   /**
27    * Writes any cached events to the underlying output mechanism
28    * @throws XMLStreamException
29    */
30   public void flush() throws XMLStreamException;
31
32   /**
33    * Frees any resources associated with this stream
34    * @throws XMLStreamException
35    */
36   public void close() throws XMLStreamException;
37
38   /**
39    * Add an event to the output stream
40    * Adding a START_ELEMENT will open a new namespace scope that
41    * will be closed when the corresponding END_ELEMENT is written.
42    * <table border="2" rules="all" cellpadding="4">
43    * <thead>
44    * <tr>
45    * <th align="center" colspan="2">
46    * Required and optional fields for events added to the writer
47    * </th>
48    * </tr>
49    * </thead>
50    * <tbody>
51    * <tr>
52    * <th>Event Type</th>
53    * <th>Required Fields</th>
54    * <th>Optional Fields</th>
55    * <th>Required Behavior</th>
56    * </tr>
57    * <tr>
58    * <td> START_ELEMENT </td>
59    * <td> QName name </td>
60    * <td> namespaces , attributes </td>
61    * <td> A START_ELEMENT will be written by writing the name,
62    * namespaces, and attributes of the event in XML 1.0 valid
63    * syntax for START_ELEMENTs.
64    * The name is written by looking up the prefix for
65    * the namespace uri. The writer can be configured to
66    * respect prefixes of QNames. If the writer is respecting
67    * prefixes it must use the prefix set on the QName. The
68    * default behavior is to lookup the value for the prefix
69    * on the EventWriter's internal namespace context.
70    * Each attribute (if any)
71    * is written using the behavior specified in the attribute
72    * section of this table. Each namespace (if any) is written
73    * using the behavior specified in the namespace section of this
74    * table.
75    * </td>
76    * </tr>
77    * <tr>
78    * <td> END_ELEMENT </td>
79    * <td> Qname name </td>
80    * <td> None </td>
81    * <td> A well formed END_ELEMENT tag is written.
82    * The name is written by looking up the prefix for
83    * the namespace uri. The writer can be configured to
84    * respect prefixes of QNames. If the writer is respecting
85    * prefixes it must use the prefix set on the QName. The
86    * default behavior is to lookup the value for the prefix
87    * on the EventWriter's internal namespace context.
88    * If the END_ELEMENT name does not match the START_ELEMENT
89    * name an XMLStreamException is thrown.
90    * </td>
91    * </tr>
92    * <tr>
93    * <td> ATTRIBUTE </td>
94    * <td> QName name , String value </td>
95    * <td> QName type </td>
96    * <td> An attribute is written using the same algorithm
97    * to find the lexical form as used in START_ELEMENT.
98    * The default is to use double quotes to wrap attribute
99    * values and to escape any double quotes found in the
100    * value. The type value is ignored.
101    * </td>
102    * </tr>
103    * <tr>
104    * <td> NAMESPACE </td>
105    * <td> String prefix, String namespaceURI,
106    * boolean isDefaultNamespaceDeclaration
107    * </td>
108    * <td> None </td>
109    * <td> A namespace declaration is written. If the
110    * namespace is a default namespace declaration
111    * (isDefault is true) then xmlns="$namespaceURI"
112    * is written and the prefix is optional. If
113    * isDefault is false, the prefix must be declared
114    * and the writer must prepend xmlns to the prefix
115    * and write out a standard prefix declaration.
116    * </td>
117    * </tr>
118    * <tr>
119    * <td> PROCESSING_INSTRUCTION </td>
120    * <td> None</td>
121    * <td> String target, String data</td>
122    * <td> The data does not need to be present and may be
123    * null. Target is required and many not be null.
124    * The writer
125    * will write data section
126    * directly after the target,
127    * enclosed in appropriate XML 1.0 syntax
128    * </td>
129    * </tr>
130    * <tr>
131    * <td> COMMENT </td>
132    * <td> None </td>
133    * <td> String comment </td>
134    * <td> If the comment is present (not null) it is written, otherwise an
135    * an empty comment is written
136    * </td>
137    * </tr>
138    * <tr>
139    * <td> START_DOCUMENT </td>
140    * <td> None </td>
141    * <td> String encoding , boolean standalone, String version </td>
142    * <td> A START_DOCUMENT event is not required to be written to the
143    * stream. If present the attributes are written inside
144    * the appropriate XML declaration syntax
145    * </td>
146    * </tr>
147    * <tr>
148    * <td> END_DOCUMENT </td>
149    * <td> None </td>
150    * <td> None </td>
151    * <td> Nothing is written to the output </td>
152    * </tr>
153    * <tr>
154    * <td> DTD </td>
155    * <td> String DocumentTypeDefinition </td>
156    * <td> None </td>
157    * <td> The DocumentTypeDefinition is written to the output </td>
158    * </tr>
159    * </tbody>
160    * </table>
161    * @param event the event to be added
162    * @throws XMLStreamException
163    */
164   public void add(XMLEvent event) throws XMLStreamException;
165
166   /**
167    * Adds an entire stream to an output stream,
168    * calls next() on the inputStream argument until hasNext() returns false
169    * This should be treated as a convenience method that will
170    * perform the following loop over all the events in an
171    * event reader and call add on each event.
172    *
173    * @param reader the event stream to add to the output
174    * @throws XMLStreamException
175    */
176
177   public void add(XMLEventReader reader) throws XMLStreamException;
178
179   /**
180    * Gets the prefix the uri is bound to
181    * @param uri the uri to look up
182    * @throws XMLStreamException
183    */
184   public String JavaDoc getPrefix(String JavaDoc uri) throws XMLStreamException;
185
186   /**
187    * Sets the prefix the uri is bound to. This prefix is bound
188    * in the scope of the current START_ELEMENT / END_ELEMENT pair.
189    * If this method is called before a START_ELEMENT has been written
190    * the prefix is bound in the root scope.
191    * @param prefix the prefix to bind to the uri
192    * @param uri the uri to bind to the prefix
193    * @throws XMLStreamException
194    */
195   public void setPrefix(String JavaDoc prefix, String JavaDoc uri) throws XMLStreamException;
196
197   /**
198    * Binds a URI to the default namespace
199    * This URI is bound
200    * in the scope of the current START_ELEMENT / END_ELEMENT pair.
201    * If this method is called before a START_ELEMENT has been written
202    * the uri is bound in the root scope.
203    * @param uri the uri to bind to the default namespace
204    * @throws XMLStreamException
205    */
206   public void setDefaultNamespace(String JavaDoc uri) throws XMLStreamException;
207
208   /**
209    * Sets the current namespace context for prefix and uri bindings.
210    * This context becomes the root namespace context for writing and
211    * will replace the current root namespace context. Subsequent calls
212    * to setPrefix and setDefaultNamespace will bind namespaces using
213    * the context passed to the method as the root context for resolving
214    * namespaces.
215    * @param context the namespace context to use for this writer
216    * @throws XMLStreamException
217    */
218   public void setNamespaceContext(NamespaceContext JavaDoc context)
219     throws XMLStreamException;
220
221   /**
222    * Returns the current namespace context.
223    * @return the current namespace context
224    */
225   public NamespaceContext JavaDoc getNamespaceContext();
226
227   
228 }
229
230
Popular Tags