com.bea.xml
XmlObject Interface

public interface XmlObject

    extends XmlTokenSource

Corresponds to the XML Schema 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 XmlObject.Factory itself to 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 XmlObject.save(ContentHandler, LexicalHandler) methods, or XmlObject.newInputStream() or XmlObject.newReader(). Use XmlObject.toString() to produce a pretty-printed representation of the XML 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 XmlObject.Factory.parse(Node), for example, to load from DOM; use XmlObject.Factory.newXmlSaxHandler() to load from SAX; use XmlObject.newDomNode() to save to DOM; and use XmlObject.save(ContentHandler, LexicalHandler) to save to SAX.
• Use XmlObject.validate() to validate the subtree of XML under this XML Object. If you wish to get information about the location and reason for validation errors, see XmlOptions.setErrorListener(Collection), and use XmlObject.validate(XmlOptions).
• Use XmlObject.newCursor() to access the full XML infoset, for example, if you need to determine interleaved element order or manipulate annotations, comments, or mixed content. See XmlCursor.
• Use XmlObject.selectPath(String) to find other XmlObjects in the subtree underneath this XmlObject using relative XPaths. (In selectPath, "." indicates the current element or attribute.)

Type inference. When using XmlObject.Factory to parse XML documents, the actual document type is not XmlObject.type itself, but a subtype based 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");
 }
 

 MyOrderDocument mydoc = MyOrderDocument.Factory.parse(myDocument);
 

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 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.

All Known Implementing Classes

FilterXmlObject

All Superinterfaces

XmlTokenSource

All Known Subinterfaces

SimpleValue, XmlAnySimpleType, XmlAnyURI, XmlBase64Binary, XmlBoolean, XmlByte, XmlDate, XmlDateTime, XmlDecimal, XmlDouble, XmlDuration, XmlENTITIES, XmlENTITY, XmlFloat, XmlGDay, XmlGMonth, XmlGMonthDay, XmlGYear, XmlGYearMonth, XmlHexBinary, XmlID, XmlIDREF, XmlIDREFS, XmlInt, XmlInteger, XmlLanguage, XmlLong, XmlName, XmlNCName, XmlNegativeInteger, XmlNMTOKEN, XmlNMTOKENS, XmlNonNegativeInteger, XmlNonPositiveInteger, XmlNormalizedString, XmlNOTATION, XmlPositiveInteger, XmlQName, XmlShort, XmlString, XmlTime, XmlToken, XmlUnsignedByte, XmlUnsignedInt, XmlUnsignedLong, XmlUnsignedShort

EQUAL

public static final int EQUAL

EQUAL is 0. See XmlObject.compareValue(XmlObject).

GREATER_THAN

public static final int GREATER_THAN

GREATER_THAN is 1. See XmlObject.compareValue(XmlObject).

LESS_THAN

public static final int LESS_THAN

LESS_THAN is -1. See XmlObject.compareValue(XmlObject).

NOT_EQUAL

public static final int NOT_EQUAL

NOT_EQUAL is 2. See XmlObject.compareValue(XmlObject).

type

public static final SchemaType type

The constant SchemaType object representing this schema type.

changeType(SchemaType) Method

public XmlObject changeType(SchemaType newType)

Returns null if the type change is not allowed. Certain type changes may be prohibited on the interior of an xml tree due to schema type system constraints (that is, due to a parent container within which the newly specified type is not permissible), but there are no constraints at the roottype changes are never prohibited at the root of an xml tree.

If the type change is allowed, then the new XmlObject should be used rather than the old one. The old XmlObject instance and any other XmlObject instances in the subtree are permanently invalidated and should not be used. (They will return InvalidStateException if you try to use them.) If a type change is done on the interior of an Xml tree, then xsi:type attributes are updated as needed.

compareTo(Object) Method

public int compareTo(Object obj)

compareValue(XmlObject) Method

public int compareValue(XmlObject obj)

copy() Method

public XmlObject copy()

execQuery(String) Method

public XmlObject[] execQuery(String query)

An XQuery is very similar to an XPath, except that it also permits construction of new XML. As a result, the XmlObjects that are returned from execQuery are in newly created documents, separate from the XmlObject on which the query is executed.

Syntax and usage is otherwise similar to selectPath.

Related Topics

XmlObject.selectPath(String)

execQuery(String, XmlOptions) Method

public XmlObject[] execQuery(String query, 
                           XmlOptions options)

Parameters

query

The XQuery expression.

options

Options as described.

Related Topics

XmlObject.execQuery(String)

isImmutable() Method

public boolean isImmutable()

isNil() Method

public boolean isNil()

schemaType() Method

public SchemaType schemaType()

selectPath(String) Method

public XmlObject[] selectPath(String path)

The path must be a relative path, where "." represents the element or attribute containg this XmlObject, and it must select only other elements or attributes. If a non-element or non-attribute is selected, an unchecked exception is thrown.

The array that is returned contains all the selected XmlObjects, within the same document, listed in document order. The actual array type of the result is inferred from the closest common base type of selected results.

Here is an example of usage. Suppose we have a global element definition for "owner" whose type is "person":

   <schema targetNamespace="http://openuri.org/sample">
      <element name="owner" type="person"/>
      <complexType name="person">
         [...]
      </complexType>
   </schema>
 

 import org.openuri.sample.Person;
 import com.bea.xml.*;
 [...]
   XmlObject xobj = XmlObject.Factory.parse(myFile);
   Person[] results;
   results = (Person[])xobj.selectPath(
      "declare namespace s='http://www.openuri.org/sample' " +
      ".//s:owner");
 

selectPath(String, XmlOptions) Method

public XmlObject[] selectPath(String path, 
                            XmlOptions options)

Related Topics

XmlObject.selectPath(String)

set(XmlObject) Method

public XmlObject set(XmlObject srcObj)

setNil() Method

public void setNil()

toString() Method

public String toString()

The string is pretty-printed. If you want a non-pretty-printed string, or if you want to control options precisely, use the xmlText() methods.

Note that when producing XML any object other than very root of the document, then you are guaranteed to be looking at only a fragment of XML, i.e., just the contents of an element or attribute, and and we will produce a string that starts with an <xml-fragment> tag. The XmlOptions.setSaveOuter() option on xmlText can be used to produce the actual element name above the object if you wish.

Overrides

Object.toString()

validate() Method

public boolean validate()

Does a deep validation of the entire subtree under the object, but does not validate the parents or siblings of the object if the object is in the interior of an xml tree.

validate(XmlOptions) Method

public boolean validate(XmlOptions options)

Just like validate(), but with options.

If you wish to collect error messages and locations while validating, use the XmlOptions.setErrorListener(Collection) method. With that method, you can specify an object in which to store messages related to validation. The following is a simple example.

 // Create an XmlOptions instance and set the error listener.
 XmlOptions validateOptions = new XmlOptions();
 ArrayList errorList = new ArrayList();
 validateOptions.setErrorListener(errorList);
 
 // Validate the XML.
 boolean isValid = newEmp.validate(validateOptions);
 
 // If the XML isn't valid, loop through the listener's contents,
 // printing contained messages.
 if (!isValid)
 {
      for (int i = 0; i < errorList.size(); i++)
      {
          XmlError error = (XmlError)errorList.get(i);
          
          System.out.println("\n");
          System.out.println("Message: " + error.getMessage() + "\n");
          System.out.println("Location of invalid XML: " + 
              error.getCursorLocation().xmlText() + "\n");
      }
 }
 

Parameters

options

An object that implements the Collection interface.

valueEquals(XmlObject) Method

public boolean valueEquals(XmlObject obj)

Usually this method can be treated as an ordinary equvalence relation, but actually it is not is not transitive. Here is a precise specification:

There are two categories of XML object: objects with a known instance type, and objects whose only known type is one of the ur-types (either AnyType or AnySimpleType). The first category is compared in terms of logical value spaces, and the second category is compared lexically.

Within each of these two categories, valueEquals is a well-behaved equivalence relation. However, when comparing an object of known type with an object with ur-type, the comparison is done by attempting to convert the lexical form of the ur-typed object into the other type, and then comparing the results. Ur-typed objects are therefore treated as lexical wildcards and may be equal to objects in different value spaces, even though the objects in different value spaces are not equal to each other.

For example, the anySimpleType value "1" will compare as an equalValue to the string "1", the float value "1.0", the double value "1.0", the decimal "1", and the GYear "1", even though all these objects will compare unequal to each other since they lie in different value spaces.

valueHashCode() Method

public int valueHashCode()