1 /*
2 * Copyright (c) 2009, 2017, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
33 *
34 * This is the top level interface for writing XML documents.
35 *
36 * Instances of this interface are not required to validate the
37 * form of the XML.
38 *
39 * @version 1.0
40 * @author Copyright (c) 2009 by Oracle Corporation. All Rights Reserved.
41 * @see XMLEventReader
42 * @see javax.xml.stream.events.XMLEvent
43 * @see javax.xml.stream.events.Characters
44 * @see javax.xml.stream.events.ProcessingInstruction
45 * @see javax.xml.stream.events.StartElement
46 * @see javax.xml.stream.events.EndElement
47 * @since 1.6
48 */
49 public interface XMLEventWriter extends XMLEventConsumer {
50
51 /**
52 * Writes any cached events to the underlying output mechanism
53 * @throws XMLStreamException
54 */
55 public void flush() throws XMLStreamException;
56
57 /**
58 * Frees any resources associated with this stream
59 * @throws XMLStreamException
60 */
61 public void close() throws XMLStreamException;
62
63 /**
64 * Add an event to the output stream
65 * Adding a START_ELEMENT will open a new namespace scope that
66 * will be closed when the corresponding END_ELEMENT is written.
67 * <table class="striped">
68 * <caption>Required and optional fields for events added to the writer</caption>
69 * <thead>
70 * <tr>
71 * <th scope="col">Event Type</th>
72 * <th scope="col">Required Fields</th>
73 * <th scope="col">Optional Fields</th>
74 * <th scope="col">Required Behavior</th>
75 * </tr>
76 * </thead>
77 * <tbody>
78 * <tr>
79 * <th scope="row"> START_ELEMENT </th>
163 * <td> A START_DOCUMENT event is not required to be written to the
164 * stream. If present the attributes are written inside
165 * the appropriate XML declaration syntax
166 * </td>
167 * </tr>
168 * <tr>
169 * <th scope="row"> END_DOCUMENT </th>
170 * <td> None </td>
171 * <td> None </td>
172 * <td> Nothing is written to the output </td>
173 * </tr>
174 * <tr>
175 * <th scope="row"> DTD </th>
176 * <td> String DocumentTypeDefinition </td>
177 * <td> None </td>
178 * <td> The DocumentTypeDefinition is written to the output </td>
179 * </tr>
180 * </tbody>
181 * </table>
182 * @param event the event to be added
183 * @throws XMLStreamException
184 */
185 public void add(XMLEvent event) throws XMLStreamException;
186
187 /**
188 * Adds an entire stream to an output stream,
189 * calls next() on the inputStream argument until hasNext() returns false
190 * This should be treated as a convenience method that will
191 * perform the following loop over all the events in an
192 * event reader and call add on each event.
193 *
194 * @param reader the event stream to add to the output
195 * @throws XMLStreamException
196 */
197
198 public void add(XMLEventReader reader) throws XMLStreamException;
199
200 /**
201 * Gets the prefix the uri is bound to
202 * @param uri the uri to look up
203 * @throws XMLStreamException
204 */
205 public String getPrefix(String uri) throws XMLStreamException;
206
207 /**
208 * Sets the prefix the uri is bound to. This prefix is bound
209 * in the scope of the current START_ELEMENT / END_ELEMENT pair.
210 * If this method is called before a START_ELEMENT has been written
211 * the prefix is bound in the root scope.
212 * @param prefix the prefix to bind to the uri
213 * @param uri the uri to bind to the prefix
214 * @throws XMLStreamException
215 */
216 public void setPrefix(String prefix, String uri) throws XMLStreamException;
217
218 /**
219 * Binds a URI to the default namespace
220 * This URI is bound
221 * in the scope of the current START_ELEMENT / END_ELEMENT pair.
222 * If this method is called before a START_ELEMENT has been written
223 * the uri is bound in the root scope.
224 * @param uri the uri to bind to the default namespace
225 * @throws XMLStreamException
226 */
227 public void setDefaultNamespace(String uri) throws XMLStreamException;
228
229 /**
230 * Sets the current namespace context for prefix and uri bindings.
231 * This context becomes the root namespace context for writing and
232 * will replace the current root namespace context. Subsequent calls
233 * to setPrefix and setDefaultNamespace will bind namespaces using
234 * the context passed to the method as the root context for resolving
235 * namespaces.
236 * @param context the namespace context to use for this writer
237 * @throws XMLStreamException
238 */
239 public void setNamespaceContext(NamespaceContext context)
240 throws XMLStreamException;
241
242 /**
243 * Returns the current namespace context.
244 * @return the current namespace context
245 */
246 public NamespaceContext getNamespaceContext();
247
248
249 }
|
1 /*
2 * Copyright (c) 2009, 2020, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
33 *
34 * This is the top level interface for writing XML documents.
35 *
36 * Instances of this interface are not required to validate the
37 * form of the XML.
38 *
39 * @version 1.0
40 * @author Copyright (c) 2009 by Oracle Corporation. All Rights Reserved.
41 * @see XMLEventReader
42 * @see javax.xml.stream.events.XMLEvent
43 * @see javax.xml.stream.events.Characters
44 * @see javax.xml.stream.events.ProcessingInstruction
45 * @see javax.xml.stream.events.StartElement
46 * @see javax.xml.stream.events.EndElement
47 * @since 1.6
48 */
49 public interface XMLEventWriter extends XMLEventConsumer {
50
51 /**
52 * Writes any cached events to the underlying output mechanism
53 * @throws XMLStreamException if an error occurs
54 */
55 public void flush() throws XMLStreamException;
56
57 /**
58 * Frees any resources associated with this stream
59 * @throws XMLStreamException if an error occurs
60 */
61 public void close() throws XMLStreamException;
62
63 /**
64 * Add an event to the output stream
65 * Adding a START_ELEMENT will open a new namespace scope that
66 * will be closed when the corresponding END_ELEMENT is written.
67 * <table class="striped">
68 * <caption>Required and optional fields for events added to the writer</caption>
69 * <thead>
70 * <tr>
71 * <th scope="col">Event Type</th>
72 * <th scope="col">Required Fields</th>
73 * <th scope="col">Optional Fields</th>
74 * <th scope="col">Required Behavior</th>
75 * </tr>
76 * </thead>
77 * <tbody>
78 * <tr>
79 * <th scope="row"> START_ELEMENT </th>
163 * <td> A START_DOCUMENT event is not required to be written to the
164 * stream. If present the attributes are written inside
165 * the appropriate XML declaration syntax
166 * </td>
167 * </tr>
168 * <tr>
169 * <th scope="row"> END_DOCUMENT </th>
170 * <td> None </td>
171 * <td> None </td>
172 * <td> Nothing is written to the output </td>
173 * </tr>
174 * <tr>
175 * <th scope="row"> DTD </th>
176 * <td> String DocumentTypeDefinition </td>
177 * <td> None </td>
178 * <td> The DocumentTypeDefinition is written to the output </td>
179 * </tr>
180 * </tbody>
181 * </table>
182 * @param event the event to be added
183 * @throws XMLStreamException if an error occurs
184 */
185 public void add(XMLEvent event) throws XMLStreamException;
186
187 /**
188 * Adds an entire stream to an output stream,
189 * calls next() on the inputStream argument until hasNext() returns false
190 * This should be treated as a convenience method that will
191 * perform the following loop over all the events in an
192 * event reader and call add on each event.
193 *
194 * @param reader the event stream to add to the output
195 * @throws XMLStreamException if an error occurs
196 */
197
198 public void add(XMLEventReader reader) throws XMLStreamException;
199
200 /**
201 * Gets the prefix the uri is bound to
202 * @param uri the uri to look up
203 * @return the prefix
204 * @throws XMLStreamException if an error occurs
205 */
206 public String getPrefix(String uri) throws XMLStreamException;
207
208 /**
209 * Sets the prefix the uri is bound to. This prefix is bound
210 * in the scope of the current START_ELEMENT / END_ELEMENT pair.
211 * If this method is called before a START_ELEMENT has been written
212 * the prefix is bound in the root scope.
213 * @param prefix the prefix to bind to the uri
214 * @param uri the uri to bind to the prefix
215 * @throws XMLStreamException if an error occurs
216 */
217 public void setPrefix(String prefix, String uri) throws XMLStreamException;
218
219 /**
220 * Binds a URI to the default namespace
221 * This URI is bound
222 * in the scope of the current START_ELEMENT / END_ELEMENT pair.
223 * If this method is called before a START_ELEMENT has been written
224 * the uri is bound in the root scope.
225 * @param uri the uri to bind to the default namespace
226 * @throws XMLStreamException if an error occurs
227 */
228 public void setDefaultNamespace(String uri) throws XMLStreamException;
229
230 /**
231 * Sets the current namespace context for prefix and uri bindings.
232 * This context becomes the root namespace context for writing and
233 * will replace the current root namespace context. Subsequent calls
234 * to setPrefix and setDefaultNamespace will bind namespaces using
235 * the context passed to the method as the root context for resolving
236 * namespaces.
237 * @param context the namespace context to use for this writer
238 * @throws XMLStreamException if an error occurs
239 */
240 public void setNamespaceContext(NamespaceContext context)
241 throws XMLStreamException;
242
243 /**
244 * Returns the current namespace context.
245 * @return the current namespace context
246 */
247 public NamespaceContext getNamespaceContext();
248
249
250 }
|