|
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 |
|
23 * questions. |
|
24 */ |
|
25 |
|
26 package javax.xml.stream; |
|
27 |
|
28 import javax.xml.stream.events.*; |
|
29 import javax.xml.stream.util.XMLEventConsumer; |
|
30 import javax.xml.namespace.NamespaceContext; |
|
31 |
|
32 /** |
|
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> |
|
80 * <td> QName name </td> |
|
81 * <td> namespaces , attributes </td> |
|
82 * <td> A START_ELEMENT will be written by writing the name, |
|
83 * namespaces, and attributes of the event in XML 1.0 valid |
|
84 * syntax for START_ELEMENTs. |
|
85 * The name is written by looking up the prefix for |
|
86 * the namespace uri. The writer can be configured to |
|
87 * respect prefixes of QNames. If the writer is respecting |
|
88 * prefixes it must use the prefix set on the QName. The |
|
89 * default behavior is to lookup the value for the prefix |
|
90 * on the EventWriter's internal namespace context. |
|
91 * Each attribute (if any) |
|
92 * is written using the behavior specified in the attribute |
|
93 * section of this table. Each namespace (if any) is written |
|
94 * using the behavior specified in the namespace section of this |
|
95 * table. |
|
96 * </td> |
|
97 * </tr> |
|
98 * <tr> |
|
99 * <th scope="row"> END_ELEMENT </th> |
|
100 * <td> Qname name </td> |
|
101 * <td> None </td> |
|
102 * <td> A well formed END_ELEMENT tag is written. |
|
103 * The name is written by looking up the prefix for |
|
104 * the namespace uri. The writer can be configured to |
|
105 * respect prefixes of QNames. If the writer is respecting |
|
106 * prefixes it must use the prefix set on the QName. The |
|
107 * default behavior is to lookup the value for the prefix |
|
108 * on the EventWriter's internal namespace context. |
|
109 * If the END_ELEMENT name does not match the START_ELEMENT |
|
110 * name an XMLStreamException is thrown. |
|
111 * </td> |
|
112 * </tr> |
|
113 * <tr> |
|
114 * <th scope="row"> ATTRIBUTE </th> |
|
115 * <td> QName name , String value </td> |
|
116 * <td> QName type </td> |
|
117 * <td> An attribute is written using the same algorithm |
|
118 * to find the lexical form as used in START_ELEMENT. |
|
119 * The default is to use double quotes to wrap attribute |
|
120 * values and to escape any double quotes found in the |
|
121 * value. The type value is ignored. |
|
122 * </td> |
|
123 * </tr> |
|
124 * <tr> |
|
125 * <th scope="row"> NAMESPACE </th> |
|
126 * <td> String prefix, String namespaceURI, |
|
127 * boolean isDefaultNamespaceDeclaration |
|
128 * </td> |
|
129 * <td> None </td> |
|
130 * <td> A namespace declaration is written. If the |
|
131 * namespace is a default namespace declaration |
|
132 * (isDefault is true) then xmlns="$namespaceURI" |
|
133 * is written and the prefix is optional. If |
|
134 * isDefault is false, the prefix must be declared |
|
135 * and the writer must prepend xmlns to the prefix |
|
136 * and write out a standard prefix declaration. |
|
137 * </td> |
|
138 * </tr> |
|
139 * <tr> |
|
140 * <th scope="row"> PROCESSING_INSTRUCTION </th> |
|
141 * <td> None</td> |
|
142 * <td> String target, String data</td> |
|
143 * <td> The data does not need to be present and may be |
|
144 * null. Target is required and many not be null. |
|
145 * The writer |
|
146 * will write data section |
|
147 * directly after the target, |
|
148 * enclosed in appropriate XML 1.0 syntax |
|
149 * </td> |
|
150 * </tr> |
|
151 * <tr> |
|
152 * <th scope="row"> COMMENT </th> |
|
153 * <td> None </td> |
|
154 * <td> String comment </td> |
|
155 * <td> If the comment is present (not null) it is written, otherwise an |
|
156 * an empty comment is written |
|
157 * </td> |
|
158 * </tr> |
|
159 * <tr> |
|
160 * <th scope="row"> START_DOCUMENT </th> |
|
161 * <td> None </td> |
|
162 * <td> String encoding , boolean standalone, String version </td> |
|
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 } |