1 /* Copyright 2004 The Apache Software Foundation
2 *
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at\\
6 *
7 * http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15
16 package org.apache.xmlbeans;
17
18 import org.apache.xmlbeans.xml.stream.XMLInputStream;
19
20 import java.io.InputStream;
21 import java.io.OutputStream;
22 import java.io.Reader;
23 import java.io.Writer;
24 import java.io.File;
25 import java.io.IOException;
26
27 import javax.xml.stream.XMLStreamReader;
28
29 import org.w3c.dom.Node;
30
31 import org.xml.sax.ContentHandler;
32 import org.xml.sax.ext.LexicalHandler;
33 import org.xml.sax.SAXException;
34
35 /**
36 * Represents a holder of XML that can return an {@link XmlCursor}
37 * or copy itself to various media such as
38 * {@link Writer Writers} or {@link File Files}.
39 * Both {@link XmlObject}
40 * (and thus all XML Beans) and {@link XmlCursor} are
41 * XmlTokenSource implementations.
42 *
43 * @see XmlObject
44 * @see XmlCursor
45 */
46 public interface XmlTokenSource
47 {
48 /**
49 * Returns the synchronization object for the document. If concurrent
50 * multithreaded access to a document is required, the access should should
51 * be protected by synchronizing on this monitor() object. There is one
52 * monitor per XML document tree.
53 */
54 Object monitor();
55
56 /**
57 * Returns the XmlDocumentProperties object for the document this token
58 * source is associated with.
59 */
60 XmlDocumentProperties documentProperties();
61
62 /**
63 * Returns a new XML cursor.
64 *
65 * A cursor provides random access to all the tokens in the XML
66 * data, plus the ability to extract strongly-typed XmlObjects
67 * for the data. If the data is not read-only, the XML cursor
68 * also allows modifications to the data.
69 *
70 * Using a cursor for the first time typically forces the XML
71 * document into memory.
72 */
73 XmlCursor newCursor();
74
75 /**
76 * Returns a new XmlInputStream.
77 *
78 * The stream starts at the current begin-tag or begin-document
79 * position and ends at the matching end-tag or end-document.
80 *
81 * This is a fail-fast stream, so if the underlying data is changed
82 * while the stream is being read, the stream throws a
83 * ConcurrentModificationException.
84 *
85 * Throws an IllegalStateException if the XmlTokenSource is not
86 * positioned at begin-tag or begin-document (e.g., if it is at
87 * an attribute).
88 * @deprecated XMLInputStream was deprecated by XMLStreamReader from STaX - jsr173 API.
89 */
90 XMLInputStream newXMLInputStream();
91
92 /**
93 * Returns a new XMLStreamReader.
94 *
95 * The stream starts at the current begin-tag or begin-document
96 * position and ends at the matching end-tag or end-document.
97 *
98 * This is a fail-fast stream, so if the underlying data is changed
99 * while the stream is being read, the stream throws a
100 * ConcurrentModificationException.
101 */
102 XMLStreamReader newXMLStreamReader();
103
104 /**
105 * Returns standard XML text.
106 * <p>
107 * The text returned represents the document contents starting at
108 * the current begin-tag or begin-document and ending at the matching
109 * end-tag or end-document. This is same content as newReader, but
110 * it is returned as a single string.
111 * <p>
112 * Throws an IllegalStateException if the XmlTokenSource is not
113 * positioned at begin-tag or begin-document (e.g., if it is at
114 * an attribute).
115 * <p>
116 * Note that this method does not produce XML with the XML declaration,
117 * including the encoding information. To save the XML declaration with
118 * the XML, see {@link #save(OutputStream)} or {@link #save(OutputStream, XmlOptions)}.
119 */
120 String xmlText();
121
122 /**
123 * Returns a new stream containing standard XML text, encoded
124 * according to the given encoding.
125 *
126 * The byte stream contains contents starting at the current
127 * begin-tag or begin-document and ending at the matching
128 * end-tag or end-document. The specified encoding is used
129 * and also emitted in a PI at the beginning of the stream.
130 *
131 * This is a fail-fast stream, so if the underlying data is changed
132 * while the stream is being read, the stream throws a
133 * ConcurrentModificationException.
134 *
135 * Throws an IllegalStateException if the XmlTokenSource is not
136 * positioned at begin-tag or begin-document (e.g., if it is at
137 * an attribute).
138 */
139 InputStream newInputStream();
140
141 /**
142 * Returns a new character reader containing XML text.
143 *
144 * The contents of the reader represents the document contents
145 * starting at the current begin-tag or begin-document and ending at
146 * the matching end-tag or end-document. No encoding annotation
147 * will be made in the text itself.
148 *
149 * This is a fail-fast reader, so if the underlying data is changed
150 * while the reader is being read, the reader throws a
151 * ConcurrentModificationException.
152 *
153 * Throws an IllegalStateException if the XmlTokenSource is not
154 * positioned at begin-tag or begin-document (e.g., if it is at
155 * an attribute).
156 */
157 Reader newReader();
158
159 /**
160 * Returns a W3C DOM Node containing the XML
161 * represented by this source. This is a copy of the XML, it is
162 * not a live with the underlying store of this token source.
163 * If this is the document node, then a Document is returned, else
164 * a DocumentFragment is returned.
165 */
166 Node newDomNode();
167
168 /**
169 * Returns a W3C DOM Node containing the XML represented by this source.
170 * This is a live DOM node, not a copy. Any changes made through this node
171 * are immediately reflected in the document associated with this token
172 * source. Depending on the kind of token this XmlTokenSource represents,
173 * an appropriate node will be returned.
174 */
175 Node getDomNode();
176
177 /**
178 * Writes the XML represented by this source to the given SAX content and
179 * lexical handlers.
180 * Note that this method does not save the XML declaration, including the encoding information.
181 * To save the XML declaration with the XML, see {@link #save(OutputStream)},
182 * {@link #save(OutputStream, XmlOptions)}, {@link #save(File)} or {@link #save(File, XmlOptions)}.
183 */
184 void save ( ContentHandler ch, LexicalHandler lh ) throws SAXException;
185
186 /**
187 * Writes the XML represented by this source to the given File.
188 * This method will save the XML declaration, including encoding information,
189 * with the XML.
190 */
191 void save ( File file ) throws IOException;
192
193 /**
194 * Writes the XML represented by this source to the given output stream.
195 * This method will save the XML declaration, including encoding information,
196 * with the XML.
197 */
198 void save ( OutputStream os ) throws IOException;
199
200 /**
201 * Writes the XML represented by this source to the given output.
202 * Note that this method does not save the XML declaration, including the encoding information.
203 * To save the XML declaration with the XML, see {@link #save(OutputStream)},
204 * {@link #save(OutputStream, XmlOptions)}, {@link #save(File)} or {@link #save(File, XmlOptions)}.
205 */
206 void save ( Writer w ) throws IOException;
207
208 /**
209 * <p>Just like newXMLInputStream() but with any of a number of options. Use the
210 * <em>options</em> parameter to specify the following:</p>
211 *
212 * <table>
213 * <tr><th>To specify this</th><th>Use this method</th></tr>
214 * <tr>
215 * <td>The character encoding to use when converting the character
216 * data in the XML to bytess.</td>
217 * <td>{@link XmlOptions#setCharacterEncoding}</td>
218 * </tr>
219 * <tr>
220 * <td>Prefix-to-namespace mappings that should be assumed
221 * when saving this XML. This is useful when the resulting
222 * XML will be part of a larger XML document, ensuring that this
223 * inner document will take advantage of namespaces defined in
224 * the outer document.</td>
225 * <td>{@link XmlOptions#setSaveImplicitNamespaces}</td>
226 * </tr>
227 * <tr>
228 * <td>Suggested namespace prefixes to use when saving. Used only
229 * when a namespace attribute needs to be synthesized.</td>
230 * <td>{@link XmlOptions#setSaveSuggestedPrefixes}</td>
231 * </tr>
232 * <tr>
233 * <td>That namespace attributes should occur first in elements when
234 * the XML is saved. By default, they occur last.</td>
235 * <td>{@link XmlOptions#setSaveNamespacesFirst}</td>
236 * </tr>
237 * <tr>
238 * <td>The XML should be pretty printed when saved. Note that this
239 * should only be used for debugging.</td>
240 * <td>{@link XmlOptions#setSavePrettyPrint}</td>
241 * </tr>
242 * <tr>
243 * <td>The number of spaces to use when indenting for pretty printing.
244 * The default is 2.</td>
245 * <td>{@link XmlOptions#setSavePrettyPrintIndent}</td>
246 * </tr>
247 * <tr>
248 * <td>The additional number of spaces indented from the left
249 * for pretty printed XML.</td>
250 * <td>{@link XmlOptions#setSavePrettyPrintOffset}</td>
251 * </tr>
252 * <tr>
253 * <td>To minimize the number of namespace attributes generated for the
254 * saved XML. Note that this can reduce performance significantly.</td>
255 * <td>{@link XmlOptions#setSaveAggresiveNamespaces}</td>
256 * </tr>
257 * <tr>
258 * <td>To reduce the size of the saved document
259 * by allowing the use of the default namespace. Note that this can
260 * potentially change the semantic meaning of the XML if unprefixed QNames are
261 * present as the value of an attribute or element.</td>
262 * <td>{@link XmlOptions#setUseDefaultNamespace}</td>
263 * </tr>
264 * <tr>
265 * <td>To filter out processing instructions with the specified target name.</td>
266 * <td>{@link XmlOptions#setSaveFilterProcinst}</td>
267 * </tr>
268 * <tr>
269 * <td>Change the QName of the synthesized root element when saving. This
270 * replaces "xml-fragment" with "fragment" in the namespace
271 * http://www.openuri.org/fragment</td>
272 * <td>{@link XmlOptions#setSaveUseOpenFrag}</td>
273 * </tr>
274 * <tr>
275 * <td>Saving should begin on the element's contents.</td>
276 * <td>{@link XmlOptions#setSaveInner}</td>
277 * </tr>
278 * <tr>
279 * <td>Saving should begin on the element, rather than its contents.</td>
280 * <td>{@link XmlOptions#setSaveOuter}</td>
281 * </tr>
282 * <tr>
283 * <td>To rename the document element, or to specify the document element
284 * for this XML.</td>
285 * <td>{@link XmlOptions#setSaveSyntheticDocumentElement}</td>
286 * </tr>
287 * </table>
288 *
289 * @see XmlOptions
290 *
291 * @param options Any of the described options.
292 * @return A new validating XMLInputStream.
293 * @deprecated XMLInputStream was deprecated by XMLStreamReader from STaX - jsr173 API.
294 */
295 XMLInputStream newXMLInputStream(XmlOptions options);
296
297 /**
298 * Just like newXMLInputStream() but with options.
299 * Options map may be null.
300 * @see XmlOptions
301 */
302 XMLStreamReader newXMLStreamReader(XmlOptions options);
303
304 /**
305 * Just like xmlText() but with options.
306 * Options map may be null.
307 * <p>
308 * Note that this method does not produce XML with the XML declaration,
309 * including the encoding information. To save the XML declaration with
310 * the XML, see {@link #save(OutputStream)} or {@link #save(OutputStream, XmlOptions)}.
311 *
312 * @see XmlOptions
313 */
314 String xmlText(XmlOptions options);
315
316 /**
317 *
318 * Just like newInputStream(String encoding) but with options.
319 * Options map may be null.
320 * @see XmlOptions
321 */
322 InputStream newInputStream(XmlOptions options);
323
324 /**
325 * Just like newReader() but with options.
326 * Options map may be null.
327 * @see XmlOptions
328 */
329 Reader newReader(XmlOptions options);
330
331 /**
332 * Just like newDomNode() but with options.
333 * Options map may be null.
334 * @see XmlOptions
335 */
336
337 Node newDomNode(XmlOptions options);
338
339 /**
340 * Writes the XML represented by this source to the given SAX content and
341 * lexical handlers.
342 * Note that this method does not save the XML declaration, including the encoding information.
343 * To save the XML declaration with the XML, see {@link #save(OutputStream)},
344 * {@link #save(OutputStream, XmlOptions)}, {@link #save(File)} or {@link #save(File, XmlOptions)}.
345 */
346 void save ( ContentHandler ch, LexicalHandler lh, XmlOptions options ) throws SAXException;
347
348 /**
349 * Writes the XML represented by this source to the given File.
350 * This method will save the XML declaration, including encoding information,
351 * with the XML.
352 */
353 void save ( File file, XmlOptions options ) throws IOException;
354
355 /**
356 * Writes the XML represented by this source to the given output stream.
357 * This method will save the XML declaration, including encoding information,
358 * with the XML.
359 */
360 void save ( OutputStream os, XmlOptions options ) throws IOException;
361
362 /**
363 * Writes the XML represented by this source to the given output.
364 * Note that this method does not save the XML declaration, including the encoding information.
365 * To save the XML declaration with the XML, see {@link #save(OutputStream)},
366 * {@link #save(OutputStream, XmlOptions)}, {@link #save(File)} or {@link #save(File, XmlOptions)}.
367 */
368 void save ( Writer w, XmlOptions options ) throws IOException;
369
370 /**
371 * Prints to stdout the state of the document in which this token source is positioned.
372 * This is very implementation specific and may change at any time. Dump can be useful
373 * for debugging purposes. It is very different from the save methods which produce
374 * XML text which only approximates the actual state of the document.
375 */
376
377 void dump ( );
378 }