3.org/TR/xmlschema-1/#key-urType">xs:anyType, the base type for all XML Beans.
Since all XML Schema types are translated into corresponding XML Bean classes, and all Schema type derivation corresponds to Java class inheritance, the fact that all Schema types derive from xs:anyType means that all XML Bean classes derive from XmlObject.
On this base class you will find a number of common facilities that all XML Bean classes provide:
- Every XML Bean class has an inner Factory class for creating and parsing instances, including XmlObject. Use {@link XmlObject.Factory} itselfto produce untyped XML trees or XML trees that implement specific subtypes of XmlObject depending on a recognized root document element. If you depend on the automatic type inference, you will want to understand the type inference issues described below.
- To write out an accurate XML file for the XML tree under this XmlObject, use one of the {@link #save} methods,or {@link #newInputStream} or {@link #newReader}. Use {@link #toString} to produce a pretty-printed representation of theXML subtree under this XML Object. If you save interior portions of an XML document, you will want to understand the inner contents versus outer container issues described below.
- It is also simple to copy an XmlObject instance to or from a standard DOM tree or SAX stream. Use {@link XmlObject.Factory#parse(Node)}, for example, to load from DOM; use {@link XmlObject.Factory#newXmlSaxHandler}to load from SAX; use {@link #newDomNode()} to save to DOM; and use {@link #save(org.xml.sax.ContentHandler,org.xml.sax.ext.LexicalHandler)}to save to SAX.
- Use {@link #validate} to validate the subtree of XML under thisXML Object. If you wish to get information about the location and reason for validation errors, see {@link XmlOptions#setErrorListener}, and use {@link #validate(XmlOptions)}.
- Use {@link #newCursor} to access the full XML infoset, for example,if you need to determine interleaved element order or manipulate annotations, comments, or mixed content. You can get an element name with a cursor by calling {@link XmlCursor#getName() cursor.getName()} when the cursor is positioned at an element's START token. See {@link XmlCursor}.
- Use {@link #selectPath} to find other XmlObjects in the subtree underneaththis XmlObject using relative XPaths. (In selectPath, "." indicates the current element or attribute.)
Type inference. When using {@link XmlObject.Factory} to parse XML documents,the actual document type is not {@link XmlObject#type} itself, but a subtypebased on the contents of the parsed document. If the parsed document contains a recognized root document element, then the actual type of the loaded instance will be the matching Document type. For example:
XmlObject xobj = XmlObject.Factory.parse(myDocument); if (xobj instanceof MyOrderDocument) // starts w/ <my-order> { MyOrderDocument mydoc = (MyOrderDocument)xobj; if (!xobj.validate()) System.out.println("Not a valid my-order document"); } else { System.out.println("Not a my-order document"); } Every XML Bean class has its own inner Factory class, so if you actually know exactly which XML Bean document type you want to load as in the example above, you should use the the specific XML Bean Factory class instead. For example:
MyOrderDocument mydoc = MyOrderDocument.Factory.parse(myDocument);
The code above will throw an exception if the parsed document does not begin with the proper (my-order) element.
Inner versus outer. An XmlObject represents the contents of an element or attribute, not the element or attribute itself. So when you validate or save an XmlObject, you are validating or saving its contents, not its container. For example, if the XmlObject represents the contents of an element which happens to itself be in the wrong order relative to its siblings, validate will not complain about the misplacement of the element itself. On the other hand, if elements within the XmlObject are in the wrong order, validate will complain. Similarly, when saving the contents of an interior XmlObject, it is the contents of an element, not the element itself, which is saved by default.
Reading and writing fragments. When reading or writing the contents of a whole XML document, the standard XML reprentation for a document is used. However, there is no standard concrete XML representation for "just the contents" of an interior element or attribute. So when one is needed, the tag <xml-fragment> is used to wrap the contents. This tag is used can also be used to load just the contents for an XmlObject document fragment of arbitrary type. If you wish to save out the XmlObject's container element along with its contents, use {@link XmlOptions#setSaveOuter}.
Implementing XmlObject. The XMLBeans library does not support arbitrary implementations of XmlObject - in almost all cases, you should only use the implementations of XmlObject provided by the XMLBeans compiler itself. If you need to implement XmlObject yourself, you should subclass FilterXmlObject in order to delegate to another underlying XmlObject implementation. This technique will allow you to use your code unchanged with future versions of XMLBeans that add additional methods on XmlObject.