Java Types Generated from Schema

When you compile XML schema, the resulting API is made up of two categories of types: built-in types that mirror those in the schema specification and others that are generated from user-derived schema types. This topic provides an overview of the Java types generated for user-derived types, describing the methods the Java types provide. For more information about built-in types, see XMLBeans Support for Built-In Schema Types. For specific information about the methods exposed by generated types, see Methods for Generated Java Types.

In general, an API generated from schema is an intuitive means to access XML instances based on the schema. You'll probably find that for most uses it's unnecessary to know the rules for generating it in order to use it. However, for those cases when it's unclear what's going on behind the scenes (or if you're just curious), this topic describes the rules.

Note: The XMLBeans API also provides a way for you to get information aboutthe type system itself — in other words, about the API and the underlying schema. For more information, see Introduction to Schema Type Signatures.

Each of the types generated when you compile a schema is designed specifically for access to XML instances conforming to that part of the schema. Start by taking a look at a simple XML and schema example. The following schema describes an XML document to contain a stock price quote.

The following is an example of XML that conforms to this schema.

When you compile this schema, you get two generated XMLBeans interfaces: PriceQuoteDocument and PriceQuoteDocument.PriceQuote.

From the schema point of view, the generated PriceQuote interface represents the complex type you see inside the schema's price-quote element declaration. Looking at the XML instance, you can see that this complex type translates into a sequence of two elements, stock-symbol and stock-price. So it's not surprising that the PriceQuote interface exposes methods such as getStockPrice and setStockPrice to set the value stock-price element.

The PriceQuoteDocument interface, on the other hand, represents the price-quote document that contains the root price-quote element. XMLBeans creates a special "document" type for global element types. A document type provides a way for you to get and set the value of the underlying type, here represented by PriceQuote. The price-quote element is considered a global element because it can be referenced from anywhere else in the schema. For global elements, the XMLBeans schema compiler generates an interface whose name ends with "Document." This is because an XML schema has no way of defining a "root" element; any global element can be the root.

The following bit of Java code illustrates how you might use these interfaces to get the stock price contained in the XML.

This code loads the XML from a File object, converting the parse method's return value to a PriceQuoteDocument instance. It then uses this instance to get an instance of PriceQuote. With PriceQuote, the code extracts the stock price.

The XML schema specification provides a rich set of rules through which you can derive new types. When you generate interfaces from your schema, XMLBeans uses the schema's rules to determine how to generate interfaces. The following describes some of the guidelines by which this is done.

Interfaces are generated for schema types (both simple and complex). Anonymous schema types result in inner interfaces inside the type interface in which they are defined. Their name comes from the element or attribute in which they is defined.

Names for schema types become Java-friendly names when the schema is compiled. In other words, names such as "price-quote" become "PriceQuote." In addition, a schema's XML namespace URIs become package names for XMLBean types generated from the schema. The way this name translation is done is described by section C of the Java API for XML Binding (JAXB) specification at http://java.sun.com/xml/jaxb.html.

Here are a few examples:

When there are name collisions, the generated types will have names with numerals appended for example, "TestType2".

In schema, global element and attribute definitions are those that are declared at the top level of the schema (that is, immediately within the schema root element). Because they are global, they may be referenced from inside the schema by name. The creditReport (not the creditReportType complex type) element defined in the following schema is an example.

XMLBeans generates a separate interface for each of these. Also, global element and attribute types are somewhat unique in that the schema compiler will create special types to hold the globally defined element or attribute. The names of these types will be appended with "Document" (for elements) or "Attribute" (for attributes). You can retrieve the element or attribute itself (or create a new one) by calling the accessor methods that the special types provide. The following example would create a new instance of the creditReport element.

A user-derived type is one defined with a complexType or simpleType element in schema. User-derived types at the top level of a schema are global. XMLBeans generates an interface for each of these, as it does with global elements and attributes. These interfaces include methods through which you can get and set the type's values, including any nested derived types it may contain. The following schema snippet defines a user-derived complex type called itemType, along with a priceType that uses it as the type for an item child element.

By default, the generated Java type for itemType would be an interface called ItemType. With this type, you would be able to get and set the values of its name, amount, and price child elements. However, a user-derived type (as opposed to an element or attribute) is always intended for use as the type to which an element or attribute is bound. In other words, it's contained by an element or attribute. While you can create a new instance of a user-derived type, the new instance's underlying XML is a fragment. As the generated API would make clear, the itemType becomes the return type of a get method, or the parameter of a set method.

When your schema includes named types that are declared locally�within the declaration of another element or type�the schema type's generated Java interface will be an inner interface within the type it's nested in.

For example, the following schema snippet defines name and gender elements nested within a person complex type. In particular, note that the gender element is defined as deriving from the xs:NMTOKEN built-in type.

The generated interfaces for person and gender would be organized in source something like the following. Of course, you wouldn't see the source, but you can see here that the Gender interface is nested with Person. Also, notice that it extends XmlNMTOKEN, mirroring the schema.

You could create a new instance of the Gender type in this way (there are also various alternatives to this):

In addition to the 46 built-in simple types in XML schema, a schema can include its own custom simple types using xs:simpleType declarations. These user-derived simple types are always based on the built-in XML schema types. The built-in types can be modified by restricting them, taking unions of them, or making space-separated lists of them. Each XML simple type is translated into a Java type that provides access to the underlying data.

Unions

In schema, you can use xs:union to specify a simple type that is allowed to contain values of a number of other simple types. XMLBeans generates a type for a union, just as it generates a type for any other schema type. At run time, you can discover the underlying type of an instance of a union type by calling the XmlObject interface's instanceType method. Once you have determined the type, you can cast an instance of a union type to the actual underlying instance type.

Given the preceding schema snippet, you could set the intOrString value to, say, 6 or "six". The union of xs:int and xs:string makes both allowable.

Restrictions

XML schema restrictions on simple XMLBeans types are enforced. So, for example, it is illegal to set a number outside its restricted range.

Numeric Type Restrictions

In schema, you can restrict numeric types to allow, for example, only a particular range of values. For such a restriction, XMLBeans tailors the resulting natural Java alternative. For example, suppose you have the following element defined in schema:

The type is restricted from xs:integer, but because the number's range is limited to between 1 and 1000000, it will fit into a Java int. A long or java.math.BigInteger would be too big for the need. In other words, the getNumber method generated for this type will return an int, rather than a BigInteger or a long.

By the same token, an long can be compiled to an int if the totalDigits attribute is<=9, or the min and max attribute values are within 32-bit 2s complement range.

The single primitive XML type xs:decimal can be restricted in several ways that influence the resulting natural Java type. For example, it can be:

• Compiled to a BigInteger if itsfractionDigitattribute is set to 0.
• Compiled to a long if its totalDigits attribute is<=18, or the min and max are within 64-bit 2s complement range.

In schema, you can derive a new type by restricting a built-in type so that only a finite set of values are allowable. Where schema does this by restricting xs:string, XMLBeans generates a special Enum type. With an Enum, you can select the enumerated value either by its String value or by a numeric index. The index's value is determined based on the String value's order in the schema. Having an index can be useful in Java switch statements.

For example, suppose you had a document containing price elements whose type was the priceType defined in the following schema snippet:

Using types generated from the schema, you would be able to write the following Java code to "switch" on the threshold attribute's enumeration:

XMLBeans Support for Built-In Schema Types