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 import org.apache.xmlbeans.xml.stream.XMLStreamException;
20
21 import javax.xml.stream.XMLStreamReader;
22 import javax.xml.namespace.QName;
23
24 import org.w3c.dom.Node;
25 import org.w3c.dom.DOMImplementation;
26
27 import java.io.InputStream;
28 import java.io.File;
29 import java.io.Reader;
30 import java.io.IOException;
31
32 /**
33 * Corresponds to the XML Schema
34 * <a target="_blank" href="http://www.w3.org/TR/xmlschema-1/#key-urType">xs:anyType</a>,
35 * the base type for all XML Beans.
36 * <p>
37 * Since all XML Schema types are translated into corresponding XML Bean
38 * classes, and all Schema type derivation corresponds to Java class
39 * inheritance, the fact that all Schema types derive from xs:anyType means
40 * that all XML Bean classes derive from XmlObject.
41 * <p>
42 * On this base class you will find a number of common facilities that
43 * all XML Bean classes provide:
44 * <p>
45 * <ul>
46 * <li>Every XML Bean class has an inner Factory class for creating and parsing
47 * instances, including XmlObject. Use {@link XmlObject.Factory} itself
48 * to produce untyped XML trees or XML trees that implement specific
49 * subtypes of XmlObject depending on a recognized root document element.
50 * If you depend on the automatic type inference, you will want to understand
51 * the type inference issues described below.
52 * <li>To write out an accurate XML file for the XML tree under this
53 * XmlObject, use one of the {@link #save} methods,
54 * or {@link #newInputStream} or {@link #newReader}.
55 * Use {@link #toString} to produce a pretty-printed representation of the
56 * XML subtree under this XML Object. If you save interior portions of
57 * an XML document, you will want to understand the inner contents
58 * versus outer container issues described below.
59 * <li>It is also simple to copy an XmlObject instance to or from a standard
60 * DOM tree or SAX stream. Use {@link XmlObject.Factory#parse(Node)},
61 * for example, to load from DOM; use {@link XmlObject.Factory#newXmlSaxHandler}
62 * to load from SAX; use {@link #newDomNode()} to save to DOM; and use
63 * {@link #save(org.xml.sax.ContentHandler, org.xml.sax.ext.LexicalHandler)}
64 * to save to SAX.
65 * <li>Use {@link #validate} to validate the subtree of XML under this
66 * XML Object. If you wish to get information about the location
67 * and reason for validation errors, see {@link XmlOptions#setErrorListener},
68 * and use {@link #validate(XmlOptions)}.
69 * <li>Use {@link #newCursor} to access the full XML infoset, for example,
70 * if you need to determine interleaved element order or manipulate
71 * annotations, comments, or mixed content. You can get an element name with
72 * a cursor by calling {@link XmlCursor#getName() cursor.getName()} when the
73 * cursor is positioned at an element's START token. See {@link XmlCursor}.
74 * <li>Use {@link #selectPath} to find other XmlObjects in the subtree underneath
75 * this XmlObject using relative XPaths. (In selectPath, "." indicates
76 * the current element or attribute.)
77 * </ul>
78 * <p>
79 * Type inference. When using {@link XmlObject.Factory} to parse XML documents,
80 * the actual document type is not {@link XmlObject#type} itself, but a subtype
81 * based on the contents of the parsed document. If the parsed document
82 * contains a recognized root document element, then the actual type of the
83 * loaded instance will be the matching Document type. For example:
84 * <pre>
85 * XmlObject xobj = XmlObject.Factory.parse(myDocument);
86 * if (xobj instanceof MyOrderDocument) // starts w/ <my-order>
87 * {
88 * MyOrderDocument mydoc = (MyOrderDocument)xobj;
89 * if (!xobj.validate())
90 * System.out.println("Not a valid my-order document");
91 * }
92 * else
93 * {
94 * System.out.println("Not a my-order document");
95 * }
96 * </pre>
97 * Every XML Bean class has its own inner Factory class,
98 * so if you actually know exactly which XML Bean document type
99 * you want to load as in the example above, you should use the
100 * the specific XML Bean Factory class instead. For example:
101 * <pre>
102 * MyOrderDocument mydoc = MyOrderDocument.Factory.parse(myDocument);
103 * </pre>
104 * The code above will throw an exception if the parsed document
105 * does not begin with the proper (my-order) element.
106 * <p>
107 * Inner versus outer. An XmlObject represents the
108 * <em>contents</em> of an element or attribute, <em>not</em> the element
109 * or attribute itself. So when you validate or save an XmlObject, you
110 * are validating or saving its contents, not its container. For example,
111 * if the XmlObject represents the contents of an element which happens
112 * to itself be in the wrong order relative to its siblings, validate will
113 * not complain about the misplacement of the element itself. On the other hand, if
114 * elements <em>within</em> the XmlObject are in the wrong order, validate
115 * will complain. Similarly, when saving the contents of an interior
116 * XmlObject, it is the contents of an element, not the element itself,
117 * which is saved by default.
118 * <p>
119 * Reading and writing fragments. When reading or writing the contents of a
120 * whole XML document, the standard XML reprentation for a document is used.
121 * However, there is no standard concrete XML representation for "just the
122 * contents" of an interior element or attribute. So when one is needed,
123 * the tag <xml-fragment> is used to wrap the contents. This tag is used
124 * can also be used to load just the contents for an XmlObject document fragment
125 * of arbitrary type. If you wish to save out the XmlObject's container element
126 * along with its contents, use {@link XmlOptions#setSaveOuter}.
127 * <p>
128 * Implementing XmlObject. The XMLBeans library does not support arbitrary
129 * implementations of XmlObject - in almost all cases, you should only use
130 * the implementations of XmlObject provided by the XMLBeans compiler itself.
131 * If you need to implement XmlObject yourself, you should subclass
132 * FilterXmlObject in order to delegate to another underlying XmlObject
133 * implementation. This technique will allow you to use your code unchanged
134 * with future versions of XMLBeans that add additional methods on XmlObject.
135 */
136 public interface XmlObject extends XmlTokenSource
137 {
138 /** The constant {@link SchemaType} object representing this schema type. */
139 public static final SchemaType type = XmlBeans.getBuiltinTypeSystem().typeForHandle("_BI_anyType");
140
141 /**
142 * The schema type for this instance. This is a permanent,
143 * unchanging property of the instance.
144 */
145 SchemaType schemaType();
146
147 /**
148 * Returns true if the contents of this object are valid
149 * accoring to schemaType().
150 * <p>
151 * Does a deep validation of the entire subtree under the
152 * object, but does not validate the parents or siblings
153 * of the object if the object is in the interior of an xml
154 * tree.
155 */
156 boolean validate();
157
158 /**
159 * <p>Just like validate(), but with options.</p>
160 * <p>If you wish to collect error messages and locations while validating,
161 * use the {@link XmlOptions#setErrorListener} method. With that method,
162 * you can specify an object in which to store messages related to validation.
163 * The following is a simple example.</p>
164 *
165 * <pre>
166 * // Create an XmlOptions instance and set the error listener.
167 * XmlOptions validateOptions = new XmlOptions();
168 * ArrayList errorList = new ArrayList();
169 * validateOptions.setErrorListener(errorList);
170 *
171 * // Validate the XML.
172 * boolean isValid = newEmp.validate(validateOptions);
173 *
174 * // If the XML isn't valid, loop through the listener's contents,
175 * // printing contained messages.
176 * if (!isValid)
177 * {
178 * for (int i = 0; i < errorList.size(); i++)
179 * {
180 * XmlError error = (XmlError)errorList.get(i);
181 *
182 * System.out.println("\n");
183 * System.out.println("Message: " + error.getMessage() + "\n");
184 * System.out.println("Location of invalid XML: " +
185 * error.getCursorLocation().xmlText() + "\n");
186 * }
187 * }
188 * </pre>
189 *
190 * @param options An object that implements the {@link java.util.Collection
191 * Collection} interface.
192 */
193 boolean validate(XmlOptions options);
194
195 /**
196 * Selects a path. Path can be a string or precompiled path String.
197 * <p>
198 * The path must be a relative path, where "." represents the
199 * element or attribute containg this XmlObject, and it must select
200 * only other elements or attributes. If a non-element or non-attribute
201 * is selected, an unchecked exception is thrown.
202 * <p>
203 * The array that is returned contains all the selected
204 * XmlObjects, within the same document, listed in document
205 * order. The actual array type of the result is inferred
206 * from the closest common base type of selected results.
207 * <p>
208 * Here is an example of usage. Suppose we have a global
209 * element definition for "owner" whose type is "person":
210 * <pre>
211 * <schema targetNamespace="http://openuri.org/sample">
212 * <element name="owner" type="person"/>
213 * <complexType name="person">
214 * [...]
215 * </complexType>
216 * </schema>
217 * </pre>
218 * and suppose "owner" tags can be scattered throughout the
219 * document. Then we can write the following code to find
220 * them all:
221 * <pre>
222 * import org.openuri.sample.Person;
223 * import org.apache.xmlbeans.*;
224 * [...]
225 * XmlObject xobj = XmlObject.Factory.parse(myFile);
226 * Person[] results;
227 * results = (Person[])xobj.selectPath(
228 * "declare namespace s='http://www.openuri.org/sample' " +
229 * ".//s:owner");
230 * </pre>
231 * Notice the way in which namespace declarations are done in XPath 2.0.
232 * Since XPath can only navigate within an XML document - it cannot
233 * construct new XML - the resulting XmlObjects all reside in
234 * the same XML document as this XmlObject itself.
235 */
236 XmlObject[] selectPath ( String path );
237
238 /**
239 * Selects a path, applying options.
240 *
241 * @see #selectPath(String)
242 */
243 XmlObject[] selectPath ( String path, XmlOptions options );
244
245
246 /**
247 * Executes a query. Query can be a string or precompiled query String.
248 * <p>
249 * An XQuery is very similar to an XPath, except that it also permits
250 * construction of new XML. As a result, the XmlObjects that are
251 * returned from execQuery are in newly created documents, separate
252 * from the XmlObject on which the query is executed.
253 * <p>
254 * Syntax and usage is otherwise similar to selectPath.
255 * <p>
256 * @see #selectPath(String)
257 */
258 XmlObject[] execQuery ( String query );
259
260 /**
261 * Executes a query with options.
262 *
263 * Use the <em>options</em> parameter to specify the following:</p>
264 *
265 * <table>
266 * <tr><th>To specify this</th><th>Use this method</th></tr>
267 * <tr>
268 * <td>The document type for the root element.</td>
269 * <td>{@link XmlOptions#setDocumentType}</td>
270 * </tr>
271 * <tr>
272 * <td>To replace the document element with the specified QName when constructing the
273 * resulting document.</td>
274 * <td>{@link XmlOptions#setLoadReplaceDocumentElement}</td>
275 * </tr>
276 * <tr>
277 * <td>To strip all insignificant whitespace when constructing a document.</td>
278 * <td>{@link XmlOptions#setLoadStripWhitespace}</td>
279 * </tr>
280 * <tr>
281 * <td>To strip all comments when constructing a document.</td>
282 * <td>{@link XmlOptions#setLoadStripComments}</td>
283 * </tr>
284 * <tr>
285 * <td>To strip all processing instructions when constructing a document.</td>
286 * <td>{@link XmlOptions#setLoadStripProcinsts}</td>
287 * </tr>
288 * <tr>
289 * <td>A map of namespace URI substitutions to use when constructing a document.</td>
290 * <td>{@link XmlOptions#setLoadSubstituteNamespaces}</td>
291 * </tr>
292 * <tr>
293 * <td>Additional namespace mappings to be added when constructing a document.</td>
294 * <td>{@link XmlOptions#setLoadAdditionalNamespaces}</td>
295 * </tr>
296 * <tr>
297 * <td>To trim the underlying XML text buffer immediately after constructing
298 * a document, resulting in a smaller memory footprint.</td>
299 * <td>{@link XmlOptions#setLoadTrimTextBuffer}</td>
300 * </tr>
301 * <tr>
302 * <td>Whether value facets should be checked as they are set.</td>
303 * <td>{@link XmlOptions#setValidateOnSet}</td>
304 * </tr>
305 * </table>
306 *
307 * @param query The XQuery expression.
308 * @param options Options as described.
309 *
310 * @see #execQuery(String)
311 */
312 XmlObject[] execQuery ( String query, XmlOptions options );
313
314
315 /**
316 * Changes the schema type associated with this data and
317 * returns a new XmlObject instance whose schemaType is the
318 * new type.
319 * <p>
320 * Returns the new XmlObject if the type change was successful,
321 * the old XmlObject if no changes could be made. <p/>
322 * Certain type changes may be prohibited in the interior of an xml
323 * tree due to schema type system constraints (that is, due
324 * to a parent container within which the newly specified
325 * type is not permissible), but there are no constraints
326 * at the roottype changes are never
327 * prohibited at the root of an xml tree.
328 * <p>
329 * If the type change is allowed, then the new XmlObject should
330 * be used rather than the old one. The old XmlObject instance and
331 * any other XmlObject instances in the subtree are permanently
332 * invalidated and should not be used. (They will return
333 * XmlValueDisconnectedException if you try to use them.)
334 *
335 * If a type change is done on the interior of an Xml
336 * tree, then xsi:type attributes are updated as needed.
337 */
338 XmlObject changeType(SchemaType newType);
339
340 /**
341 * Changes the schema type associated with this data using substitution
342 * groups and returns an XmlObject instance whose schemaType is the
343 * new type and container name is the new name.
344 * <p>
345 * Returns the new XmlObject if the substitution was successful,
346 * the old XmlObject if no changes could be made. <p/>
347 * In order for the operation to succeed, several conditions must hold:
348 * <ul><li> the container of this type must be an element </li>
349 * <li> a global element with the name <code>newName</code> must exist
350 * and must be in the substition group of the containing element </li>
351 * <li> the <code>newType</code> type must be consistent with the declared
352 * type of the new element </li></ul>
353 * <p>
354 * If the type change is allowed, then the new XmlObject should
355 * be used rather than the old one. The old XmlObject instance and
356 * any other XmlObject instances in the subtree are permanently
357 * invalidated and should not be used. (They will return
358 * XmlValueDisconnectedException if you try to use them.)
359 * If necessary, xsi:type attributes are updated.
360 */
361 XmlObject substitute(QName newName, SchemaType newType);
362
363 /**
364 * True if the value is nil. Note that in order to be nil,
365 * the value must be in an element, and the element containing
366 * the value must be marked as nillable in the schema.
367 */
368 boolean isNil();
369
370 /**
371 * Sets the value to nil. The element containing the value must
372 * be marked as nillable in the schema.
373 */
374 void setNil();
375
376
377 /**
378 * Returns an XML string for this XML object.
379 * <p>
380 * The string is pretty-printed. If you want a non-pretty-printed
381 * string, or if you want to control options precisely, use the
382 * xmlText() methods.
383 * <p>
384 * Note that when producing XML any object other than very root of the
385 * document, then you are guaranteed to be looking at only a fragment
386 * of XML, i.e., just the contents of an element or attribute, and
387 * and we will produce a string that starts with an <code><xml-fragment></code> tag.
388 * The XmlOptions.setSaveOuter() option on xmlText can be used to produce
389 * the actual element name above the object if you wish.
390 */
391 String toString();
392
393 /**
394 * True if the value is an immutable value. Immutable values do not
395 * have a position in a tree; rather, they are stand-alone simple type
396 * values. If the object is immutable, the equals() methods tests for
397 * value equality, and the object can be used as the key for a hash.
398 */
399 boolean isImmutable();
400
401 /**
402 * Set the value/type of this XmlObject to be a copy of the source
403 * XmlObject. Because the type of the source may be different than this
404 * target, this XmlObject may become defunct. In this case the new
405 * XmlObject is returned. If no type change happens, the same this will be
406 * returned.
407 */
408 XmlObject set(XmlObject srcObj);
409
410 /**
411 * Returns a deep copy of this XmlObject. The returned object has the
412 * same type as the current object, and has all the content of
413 * the XML document underneath the current object. Note that
414 * any parts of the XML document above or outside this XmlObject are
415 * not copied.
416 */
417 XmlObject copy();
418
419 /**
420 * True if the xml values are equal. Two different objects
421 * (which are distinguished by equals(obj) == false) may of
422 * course have equal values (valueEquals(obj) == true).
423 * <p>
424 * Usually this method can be treated as an ordinary equvalence
425 * relation, but actually it is not is not transitive.
426 * Here is a precise specification:
427 * <p>
428 * There are two categories of XML object: objects with a known
429 * instance type, and objects whose only known type is one of the
430 * ur-types (either AnyType or AnySimpleType). The first category
431 * is compared in terms of logical value spaces, and the second
432 * category is compared lexically.
433 * <p>
434 * Within each of these two categories, valueEquals is a well-behaved
435 * equivalence relation. However, when comparing an object of known
436 * type with an object with ur-type, the comparison is done by attempting
437 * to convert the lexical form of the ur-typed object into the other
438 * type, and then comparing the results. Ur-typed objects are therefore
439 * treated as lexical wildcards and may be equal to objects in different
440 * value spaces, even though the objects in different value spaces are
441 * not equal to each other.
442 * <p>
443 * For example, the anySimpleType value "1" will compare as an
444 * equalValue to the string "1", the float value "1.0", the double
445 * value "1.0", the decimal "1", and the GYear "1", even though
446 * all these objects will compare unequal to each other since they
447 * lie in different value spaces.
448 * Note: as of XMLBeans 2.2.1 only implemented for simple type values.
449 */
450 boolean valueEquals(XmlObject obj);
451
452 int valueHashCode();
453
454 /**
455 * Impelements the Comparable interface by comparing two simple
456 * xml values based on their standard XML schema ordering.
457 * Throws a ClassCastException if no standard ordering applies,
458 * or if the two values are incomparable within a partial order.
459 */
460 int compareTo(Object obj);
461
462 /**
463 * This comparison method is similar to compareTo, but rather
464 * than throwing a ClassCastException when two values are incomparable,
465 * it returns the number 2. The result codes are -1 if this object
466 * is less than obj, 1 if this object is greater than obj, zero if
467 * the objects are equal, and 2 if the objects are incomparable.
468 */
469 int compareValue(XmlObject obj);
470
471 /** LESS_THAN is -1. See {@link #compareValue}. */
472 static final int LESS_THAN = -1;
473 /** EQUAL is 0. See {@link #compareValue}. */
474 static final int EQUAL = 0;
475 /** GREATER_THAN is 1. See {@link #compareValue}. */
476 static final int GREATER_THAN = 1;
477 /** NOT_EQUAL is 2. See {@link #compareValue}. */
478 static final int NOT_EQUAL = 2;
479
480 /**
481 * Selects the contents of the children elements with the given name.
482 * @param elementName The name of the elements to be selected.
483 * @return Returns the contents of the selected elements.
484 */
485 XmlObject[] selectChildren(QName elementName);
486
487 /**
488 * Selects the contents of the children elements with the given name.
489 * @param elementUri The URI of the elements to be selected.
490 * @param elementLocalName The local name of the elements to be selected.
491 * @return Returns the contents of the selected elements.
492 */
493 XmlObject[] selectChildren(String elementUri, String elementLocalName);
494
495 /**
496 * Selects the contents of the children elements that are contained in the elementNameSet.
497 * @param elementNameSet Set of element names to be selected.
498 * @return Returns the contents of the selected elements.
499 * @see SchemaType#qnameSetForWildcardElements()
500 * @see QNameSetBuilder for creating sets of qnames
501 */
502 XmlObject[] selectChildren(QNameSet elementNameSet);
503
504 /**
505 * Selects the content of the attribute with the given name.
506 * @param attributeName The name of the attribute to be selected.
507 * @return Returns the contents of the selected attribute.
508 */
509 XmlObject selectAttribute(QName attributeName);
510
511 /**
512 * Selects the content of the attribute with the given name.
513 * @param attributeUri The URI of the attribute to be selected.
514 * @param attributeLocalName The local name of the attribute to be selected.
515 * @return Returns the content of the selected attribute.
516 */
517 XmlObject selectAttribute(String attributeUri, String attributeLocalName);
518
519 /**
520 * Selects the contents of the attributes that are contained in the elementNameSet.
521 * @param attributeNameSet Set of attribute names to be selected.
522 * @return Returns the contents of the selected attributes.
523 * @see SchemaType#qnameSetForWildcardAttributes()
524 * @see QNameSetBuilder for creating sets of qnames
525 */
526 XmlObject[] selectAttributes(QNameSet attributeNameSet);
527
528 /**
529 * Static factory class for creating new instances. Note that if
530 * a type can be inferred from the XML being loaded (for example,
531 * by recognizing the document element QName), then the instance
532 * returned by a factory will have the inferred type. Otherwise
533 * the Factory will returned an untyped document.
534 */
535 public static final class Factory
536 {
537 /**
538 * Creates a new, completely empty instance.
539 */
540 public static XmlObject newInstance ( ) {
541 return XmlBeans.getContextTypeLoader().newInstance( null, null ); }
542
543 /**
544 * <p>Creates a new, completely empty instance, specifying options
545 * for the root element's document type and/or whether to validate
546 * value facets as they are set.</p>
547 *
548 * Use the <em>options</em> parameter to specify the following:</p>
549 *
550 * <table>
551 * <tr><th>To specify this</th><th>Use this method</th></tr>
552 * <tr>
553 * <td>The document type for the root element.</td>
554 * <td>{@link XmlOptions#setDocumentType}</td>
555 * </tr>
556 * <tr>
557 * <td>Whether value facets should be checked as they are set.</td>
558 * <td>{@link XmlOptions#setValidateOnSet}</td>
559 * </tr>
560 * </table>
561 *
562 * @param options Options specifying root document type and/or value facet
563 * checking.
564 * @return A new, empty instance of XmlObject.</li>
565 */
566 public static XmlObject newInstance ( XmlOptions options ) {
567 return XmlBeans.getContextTypeLoader().newInstance( null, options ); }
568
569 /**
570 * Creates a new immutable value.
571 */
572 /** Creates an immutable {@link XmlObject} value */
573 public static XmlObject newValue ( Object obj ) {
574 return type.newValue( obj ); }
575
576 /**
577 * Parses the given {@link String} as XML.
578 */
579 public static XmlObject parse ( String xmlAsString ) throws XmlException {
580 return XmlBeans.getContextTypeLoader().parse( xmlAsString, null, null ); }
581
582 /**
583 * Parses the given {@link String} as XML.
584 *
585 * Use the <em>options</em> parameter to specify the following:</p>
586 *
587 * <table>
588 * <tr><th>To specify this</th><th>Use this method</th></tr>
589 * <tr>
590 * <td>The document type for the root element.</td>
591 * <td>{@link XmlOptions#setDocumentType}</td>
592 * </tr>
593 * <tr>
594 * <td>To place line number annotations in the store when parsing a document.</td>
595 * <td>{@link XmlOptions#setLoadLineNumbers}</td>
596 * </tr>
597 * <tr>
598 * <td>To replace the document element with the specified QName when parsing.</td>
599 * <td>{@link XmlOptions#setLoadReplaceDocumentElement}</td>
600 * </tr>
601 * <tr>
602 * <td>To strip all insignificant whitespace when parsing a document.</td>
603 * <td>{@link XmlOptions#setLoadStripWhitespace}</td>
604 * </tr>
605 * <tr>
606 * <td>To strip all comments when parsing a document.</td>
607 * <td>{@link XmlOptions#setLoadStripComments}</td>
608 * </tr>
609 * <tr>
610 * <td>To strip all processing instructions when parsing a document.</td>
611 * <td>{@link XmlOptions#setLoadStripProcinsts}</td>
612 * </tr>
613 * <tr>
614 * <td>A map of namespace URI substitutions to use when parsing a document.</td>
615 * <td>{@link XmlOptions#setLoadSubstituteNamespaces}</td>
616 * </tr>
617 * <tr>
618 * <td>Additional namespace mappings to be added when parsing a document.</td>
619 * <td>{@link XmlOptions#setLoadAdditionalNamespaces}</td>
620 * </tr>
621 * <tr>
622 * <td>To trim the underlying XML text buffer immediately after parsing
623 * a document, resulting in a smaller memory footprint.</td>
624 * <td>{@link XmlOptions#setLoadTrimTextBuffer}</td>
625 * </tr>
626 * </table>
627 *
628 * @param xmlAsString The string to parse.
629 * @param options Options as specified.
630 * @return A new instance containing the specified XML.
631 */
632 public static XmlObject parse ( String xmlAsString, XmlOptions options ) throws XmlException {
633 return XmlBeans.getContextTypeLoader().parse( xmlAsString, null, options ); }
634
635 /**
636 * Parses the given {@link File} as XML.
637 */
638 public static XmlObject parse ( File file ) throws XmlException, IOException {
639 return XmlBeans.getContextTypeLoader().parse( file, null, null ); }
640
641 /**
642 * Parses the given {@link File} as XML.
643 */
644 public static XmlObject parse ( File file, XmlOptions options ) throws XmlException, IOException {
645 return XmlBeans.getContextTypeLoader().parse( file, null, options ); }
646
647 /**
648 * Downloads the given {@link java.net.URL} as XML.
649 */
650 public static XmlObject parse(java.net.URL u) throws org.apache.xmlbeans.XmlException, java.io.IOException {
651 return XmlBeans.getContextTypeLoader().parse( u, null, null ); }
652
653 /**
654 * Downloads the given {@link java.net.URL} as XML.
655 */
656 public static XmlObject parse(java.net.URL u, org.apache.xmlbeans.XmlOptions options) throws org.apache.xmlbeans.XmlException, java.io.IOException {
657 return XmlBeans.getContextTypeLoader().parse( u, null, options ); }
658
659 /**
660 * Decodes and parses the given {@link InputStream} as XML.
661 */
662 public static XmlObject parse ( InputStream is ) throws XmlException, IOException {
663 return XmlBeans.getContextTypeLoader().parse( is, null, null ); }
664
665 /**
666 * Decodes and parses the given {@link XMLStreamReader} as XML.
667 */
668 public static XmlObject parse ( XMLStreamReader xsr ) throws XmlException {
669 return XmlBeans.getContextTypeLoader().parse( xsr, null, null ); }
670
671 /**
672 * Decodes and parses the given {@link InputStream} as XML.
673 *
674 * Use the <em>options</em> parameter to specify the following:</p>
675 *
676 * <table>
677 * <tr><th>To specify this</th><th>Use this method</th></tr>
678 * <tr>
679 * <td>The character encoding to use when parsing or writing a document.</td>
680 * <td>{@link XmlOptions#setCharacterEncoding}</td>
681 * </tr>
682 * <tr>
683 * <td>The document type for the root element.</td>
684 * <td>{@link XmlOptions#setDocumentType}</td>
685 * </tr>
686 * <tr>
687 * <td>Place line number annotations in the store when parsing a document.</td>
688 * <td>{@link XmlOptions#setLoadLineNumbers}</td>
689 * </tr>
690 * <tr>
691 * <td>Replace the document element with the specified QName when parsing.</td>
692 * <td>{@link XmlOptions#setLoadReplaceDocumentElement}</td>
693 * </tr>
694 * <tr>
695 * <td>Strip all insignificant whitespace when parsing a document.</td>
696 * <td>{@link XmlOptions#setLoadStripWhitespace}</td>
697 * </tr>
698 * <tr>
699 * <td>Strip all comments when parsing a document.</td>
700 * <td>{@link XmlOptions#setLoadStripComments}</td>
701 * </tr>
702 * <tr>
703 * <td>Strip all processing instructions when parsing a document.</td>
704 * <td>{@link XmlOptions#setLoadStripProcinsts}</td>
705 * </tr>
706 * <tr>
707 * <td>Set a map of namespace URI substitutions to use when parsing a document.</td>
708 * <td>{@link XmlOptions#setLoadSubstituteNamespaces}</td>
709 * </tr>
710 * <tr>
711 * <td>Set additional namespace mappings to be added when parsing a document.</td>
712 * <td>{@link XmlOptions#setLoadAdditionalNamespaces}</td>
713 * </tr>
714 * <tr>
715 * <td>Trim the underlying XML text buffer immediately after parsing
716 * a document, resulting in a smaller memory footprint.</td>
717 * <td>{@link XmlOptions#setLoadTrimTextBuffer}</td>
718 * </tr>
719 * </table>
720 */
721 public static XmlObject parse ( InputStream is, XmlOptions options ) throws XmlException, IOException {
722 return XmlBeans.getContextTypeLoader().parse( is, null, options ); }
723
724 /**
725 * Parses the given {@link XMLStreamReader} as XML.
726 */
727 public static XmlObject parse ( XMLStreamReader xsr, XmlOptions options ) throws XmlException {
728 return XmlBeans.getContextTypeLoader().parse( xsr, null, options ); }
729
730 /**
731 * Parses the given {@link Reader} as XML.
732 */
733 public static XmlObject parse ( Reader r ) throws XmlException, IOException {
734 return XmlBeans.getContextTypeLoader().parse( r, null, null ); }
735
736 /**
737 * Parses the given {@link Reader} as XML.
738 */
739 public static XmlObject parse ( Reader r, XmlOptions options ) throws XmlException, IOException {
740 return XmlBeans.getContextTypeLoader().parse( r, null, options ); }
741
742 /**
743 * Converts the given DOM {@link Node} into an XmlObject.
744 */
745 public static XmlObject parse ( Node node ) throws XmlException {
746 return XmlBeans.getContextTypeLoader().parse( node, null, null ); }
747
748 /**
749 * Converts the given DOM {@link Node} into an XmlObject.
750 */
751 public static XmlObject parse ( Node node, XmlOptions options ) throws XmlException {
752 return XmlBeans.getContextTypeLoader().parse( node, null, options ); }
753
754 /**
755 * Loads the given {@link XMLInputStream} into an XmlObject.
756 * @deprecated XMLInputStream was deprecated by XMLStreamReader from STaX - jsr173 API.
757 */
758 public static XmlObject parse ( XMLInputStream xis ) throws XmlException, XMLStreamException {
759 return XmlBeans.getContextTypeLoader().parse( xis, null, null ); }
760
761 /**
762 * Loads the given {@link XMLInputStream} into an XmlObject.
763 * @deprecated XMLInputStream was deprecated by XMLStreamReader from STaX - jsr173 API.
764 */
765 public static XmlObject parse ( XMLInputStream xis, XmlOptions options ) throws XmlException, XMLStreamException {
766 return XmlBeans.getContextTypeLoader().parse( xis, null, options ); }
767
768 /**
769 * Returns an {@link XmlSaxHandler} that can load an XmlObject from SAX events.
770 */
771 public static XmlSaxHandler newXmlSaxHandler ( ) {
772 return XmlBeans.getContextTypeLoader().newXmlSaxHandler( null, null ); }
773
774 /**
775 * Returns an {@link XmlSaxHandler} that can load an XmlObject from SAX events.
776 */
777 public static XmlSaxHandler newXmlSaxHandler ( XmlOptions options ) {
778 return XmlBeans.getContextTypeLoader().newXmlSaxHandler( null, options ); }
779
780 /**
781 * Creates a new DOMImplementation object
782 */
783 public static DOMImplementation newDomImplementation ( ) {
784 return XmlBeans.getContextTypeLoader().newDomImplementation( null ); }
785
786 /**
787 * Creates a new DOMImplementation object, taking options
788 */
789 public static DOMImplementation newDomImplementation ( XmlOptions options ) {
790 return XmlBeans.getContextTypeLoader().newDomImplementation( options ); }
791
792 /**
793 * Returns a new validating {@link XMLInputStream} that throws exceptions when the input is not valid.
794 * @deprecated XMLInputStream was deprecated by XMLStreamReader from STaX - jsr173 API.
795 */
796 public static XMLInputStream newValidatingXMLInputStream ( XMLInputStream xis ) throws XmlException, XMLStreamException {
797 return XmlBeans.getContextTypeLoader().newValidatingXMLInputStream( xis, null, null ); }
798
799 /**
800 * Returns a new validating {@link XMLInputStream} that throws exceptions
801 * when the input is not valid, specifying options
802 * for the root element's document type and/or the collection object to use
803 * as an error listener while validating.</p>
804 *
805 * <p>Use the <em>options</em> parameter to specify the following:</p>
806 *
807 * <ul>
808 * <li>A collection instance that should be used as an error listener during
809 * compilation, as described in {@link XmlOptions#setErrorListener}.</li>
810 * <li>The document type for the root element, as described in
811 * {@link XmlOptions#setDocumentType(SchemaType)}.</li>
812 * </ul>
813 *
814 * @param xis The basis for the new XMLInputStream.
815 * @param options Options specifying root document type and/or an error listener.
816 * @return A new validating XMLInputStream.
817 * @deprecated XMLInputStream was deprecated by XMLStreamReader from STaX - jsr173 API.
818 */
819 public static XMLInputStream newValidatingXMLInputStream ( XMLInputStream xis, XmlOptions options ) throws XmlException, XMLStreamException {
820 return XmlBeans.getContextTypeLoader().newValidatingXMLInputStream( xis, null, options ); }
821
822 /**
823 * Instances cannot be created.
824 */
825 private Factory() { }
826 }
827 }