XMLObject may contain any data and may include optional MIME type, ID, and encoding attributes. The XML Schema Definition is defined as: <element name="Object" type="ds:ObjectType"/> <complexType name="ObjectType" mixed="true"> <sequence minOccurs="0" maxOccurs="unbounded"> <any namespace="##any" processContents="lax"/> </sequence> <attribute name="Id" type="ID" use="optional"/> <attribute name="MimeType" type="string" use="optional"/> <attribute name="Encoding" type="anyURI" use="optional"/> </complexType> XMLObject instance may be created by invoking the {@link XMLSignatureFactory#newXMLObject newXMLObject} method of the{@link XMLSignatureFactory} class; for example: XMLSignatureFactory fac = XMLSignatureFactory.getInstance("DOM"); List content = Collections.singletonList(fac.newManifest(references))); XMLObject object = factory.newXMLObject(content, "object-1", null, null); Note that this class is named XMLObject rather than Object to avoid naming clashes with the existing {@link java.lang.Object java.lang.Object} class.
@author Sean Mullan
@author JSR 105 Expert Group
@author Joyce L. Leung
@see XMLSignatureFactory#newXMLObject(List,String,String,String)
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:
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.
| |