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