Home » xmlbeans-2.5.0-src » org.apache » xmlbeans » [javadoc | source]

    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/ &lt;my-order&gt;
   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 &lt;xml-fragment&gt; 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        *   &lt;schema targetNamespace="http://openuri.org/sample">
  212        *      &lt;element name="owner" type="person"/>
  213        *      &lt;complexType name="person">
  214        *         [...]
  215        *      &lt;/complexType>
  216        *   &lt;/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>&lt;xml-fragment&gt;</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   }

Home » xmlbeans-2.5.0-src » org.apache » xmlbeans » [javadoc | source]