An XML schema is an XML document that defines a set of rules that other XML documents must conform to in order to be valid. XML schema has several advantages over earlier XML schema languages, such as document type definition (DTD) or simple object XML (SOX) and provides a rich collection of features, which can be used in different ways. It is essential to have complete support for schemeas, especially when they were written by another user or aren't under the control of the user.
Download the author's files associated with this article
XMLBeans is a tool that allows you to access the full power of XML in a Java-friendly way. It is a 100% schema compliant XML-Java binding tool.
The XMLBean solution is unique because it provides a dual view of the XML data. XMLBean maintains the original XML document with no change in information and structure and also provides a Java-based view of the XML data.
In this article we will discuss these aspects of XMLBean:
- How XMLBean handles some schema types
- How XMLBean provides access to the entire XML infoset
- How XMLBean provides access to the schema object model
How XMLBeans Handles Some of the Complex Schema Types
Let's look at how XMLBeans handles some schema types. We will also briefly discuss how to use the generated Java classes to create XML documents.Choice
The choice group element allows only one of its children to appear in an instance. Consider the following schema. In can be inferred that complexType SizeTypes can contain only one of the following choices NormalSizeType, SmallSizeType or LargeSizetype.Choice.xsd
...
<xs:element name="sizechoice" type="tns:SizeTypes"/>
<xs:complexType name="SizeTypes">
<xs:choice maxOccurs="unbounded">
<xs:element name="normalsize" type="tns:NormalSizeType"/>
<xs:element name="smallsize" type="tns:SmallSizeType"/>
<xs:element name="largesize" type="tns:LargeSizeType"/>
</xs:choice>
</xs:complexType>
<xs:simpleType name="NormalSizeType">
<xs:restriction base="xs:token">
<xs:enumeration value="small"/>
<xs:enumeration value="medium"/>
<xs:enumeration value="large"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="SmallSizeType">
<xs:restriction base="xs:token">
<xs:enumeration value="XSmall"/>
<xs:enumeration value="XXSmall"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="LargeSizeType">
<xs:restriction base="xs:token">
<xs:enumeration value="XLarge"/>
<xs:enumeration value="XXLarge"/>
</xs:restriction>
</xs:simpleType>
...
|
An XML document that conforms to this schema can be created using the generated Java types as listed below.
SizechoiceDocument sDoc = SizechoiceDocument.Factory.newInstance();
|
XMLBeans also provides the fundamental validate() method which validates an instance document against the XML schema .
Union
The union group element defines a simple type as a collection (union) of values from specified simple data types. Consider the following schema. SimpleType SizeTypes can have any of the values from either NormalSizeType or a NumberSizes.Union.xsd
...
<xsd:element name="sizeunion" type="tns:SizeTypes"/>
<xsd:simpleType name="SizeTypes">
<xsd:union memberTypes="tns:NormalSizeType tns:NumberSizes"/>
<xsd:simpleType>
<xsd:simpleType name="NormalSizeType">
<xsd:restriction base="xsd:token">
<xsd:enumeration value="small"/>
<xsd:enumeration value="medium"/>
<xsd:enumeration value="large"/>
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType name="NumberSizes" >
<xsd:restriction base="xsd:int">
<xsd:minInclusive value="28"></xsd:minInclusive>
<xsd:maxInclusive value="48"></xsd:maxInclusive>
</xsd:restriction>
</xsd:simpleType>
...
|
An XML document that conforms to this schema can be created as follows:
SizeunionDocument sDoc = SizeunionDocument.Factory.newInstance(); sDoc.setSizeunion(new Integer(28)); |
The setSizeUnion() method accepts object if the union is of simpletypes which restrict or extent different base types. In our sample NormalSizeType is a token and NumberSize is an integer. Consider the following schema:
Union.xsd
<xsd:simpleType name="NumberSizeTypes">
<xsd:union memberTypes="tns:SmallNumberSizes tns:NumberSizes"/>
</xsd:simpleType>
<xsd:simpleType name="NumberSizes" >
<xsd:restriction base="xsd:int">
<xsd:minInclusive value="28"></xsd:minInclusive>
<xsd:maxInclusive value="48">
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType name="SmallNumberSizes" >
<xsd:restriction base="xsd:int">
<xsd:minInclusive value="20"></xsd:minInclusive>
<xsd:maxInclusive value="28"></xsd:maxInclusive>
</xsd:restriction>
</xsd:simpleType>
|
In this case the setSizeUnion() method will accept an int, because the only possible values is an int value.
In section three we will talk about the schema object model and show how programmatically to obtain the list of possible schema types, which are part of a given union type.
Import
The import element allows a user to add multiple schemas with different target namespace to a document. If the user has an XML schema that imports other schemas, XMLBeans provides a convenient mechanism to access the types declared. XMLBeans generates Java types for each imported schemas in a package structure, which is based on the namespace of the imported schemas. This ensures that even if multiple schemas define the same element, the user can manipulate it in Java without conflicts.Consider the following schema:
ImportingSchema.xsd
...
<xs:schema
targetNamespace="http://sample.openuri.info/importingSchema"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:tns="http://sample.openuri.info/importingSchema"
xmlns:first="http://sample.openuri.info/firstimport"
xmlns:second="http://sample.openuri.info/secondimport">
<xs:import namespace="http://sample.openuri.info/firstimport"schemaLocation="firstimport.xsd"/>
<xs:import namespace="http://sample.openuri.info/secondimport"schemaLocation="secondimport.xsd"/>
<xs:element name="order" type="tns:OrderType"/>
<xs:complexType name="OrderType">
<xs:sequence>
<xs:element name="name" type="xs:string"/>
<xs:element name="size" type="first:DressSize"/>
<xs:element name="color" type="second:DressSize"/>
</xs:sequence>
...
|
Firstimport.xsd
...
<xs:schema targetNamespace="http://sample.openuri.info/firstimport"xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:simpleType name="DressSize">
<xs:restriction base="xs:token">
<xs:enumeration value="small"/>
<xs:enumeration value="medium"/>
<xs:enumeration value="large"/>
</xs:restriction>
</xs:simpleType>
...
|
Secondimport.xsd
...
<xs:schema targetNamespace="http://sample.openuri.info/secondimport"xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:simpleType name="DressSize">
<xs:restriction base="xs:token">
<xs:enumeration value="black"/>
<xs:enumeration value="white"/>
<xs:enumeration value="red"/>
</xs:restriction>
</xs:simpleType>
...
|
When inspecting the Java classes generated by XMLBeans, notice that there are two DressSize classes in different packages and that the package name is generated based on the namespace value.
The XML document can be constructed as follows:
...
OrderDocument orderDoc = OrderDocument.Factory.newInstance();
OrderType ordertype = orderDoc.addNewOrder();
ordertype.setName("Shirt");
ordertype.setSize(info.openuri.sample.firstimport.DressSize.MEDIUM);
ordertype.setColor(info.openuri.sample.secondimport.DressSize.RED);
...
|
Include
The include element allows a user to add multiple schemas with the same target namespace to a document. If the included schema does not have a target namespace defined, the target namespace of the including schema will be used for elements declared in the included schema. The Java types generated will all be in the package structure, which is based on the including namespace value.Consider the following schema:
firstinclude.xsd
...
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:simpleType name="CommonSizeType">
<xs:restriction base="xs:token">
<xs:enumeration value="small"/>
<xs:enumeration value="medium"/>
<xs:enumeration value="large"/>
</xs:restriction>
</xs:simpleType>
</xs:schema>
...
|
includingSchema.xsd
...
<xs:schema xmlns:xs=http://www.w3.org/2001/XMLSchema
targetNamespace="http://sample.openuri.info/includingSchema"
xmlns:tns="http://sample.openuri.info/includingSchema">
<xs:include schemaLocation="firstinclude.xsd"/>
<xs:element name="order" type="tns:OrderType"/>
<xs:complexType name="OrderType">
<xs:sequence>
<xs:element name="name" type="xs:string"/>
<xs:element name="commonSize" type="tns:CommonSizeType"/>
</xs:sequence>
</xs:complexType>
...
|
If the including schema had a target namespace specified the Java classes generated for this schema would all be in the same package as shown below:
If the including schema does not have a target namespace specified then the Java classes generated would all be in the noNamespace package as shown below.
Any
The any element enables the author to extend the XML document with elements not specified by the schema. Let us see how XMLBeans handles a schema with an any type. For the following schema:
...
<xs:element name="product" type="tns:ProductType"/>
<xs:complexType name="ProductType">
<xs:sequence maxOccurs="unbounded">
<xs:element name="something" type="xs:anyType"/>
</xs:sequence>
</xs:complexType>
<xs:simpleType name="id" >
<xs:restriction base="xs:int">
<xs:minInclusive value="28"></xs:minInclusive>
<xs:maxInclusive value="48"></xs:maxInclusive>
</xs:restriction>
</xs:simpleType>
...
|
XMLBeans provides multiple ways to populate an any type. One of the options is to parse an XML fragment and use the XMLobject's set method to set the value. The other option is to use XML cursor API to obtain a cursor and navigate to the correct position with the document and insert the text.
Both the options are listed below:
...
ProductDocument pDoc = ProductDocument.Factory.newInstance();
ProductType ptype = pDoc.addNewProduct();
XmlObject xobj = ptype.addNewSomething();
xobj.set( XmlObject.Factory.parse("<xml-fragment>BEA Systems,
Inc</xml-fragment>") );
...
|
...
ProductDocument pDoc = ProductDocument.Factory.newInstance();
ProductType ptype = pDoc.addNewProduct();
XmlObject xobj = ptype.addNewSomething();
XmlCursor xcursor = xobj.newCursor();
xcursor.toFirstContentToken();
xcursor.insertChars("BEA Systems Inc");
...
|
Extension and Restriction
Let's now see how XMLBeans handles extension and restriction. The following is a part of a schema that has a complexType (ShirtType) that is an extension of ProductType.
...
<xs:complexType name="ProductType">
<xs:sequence>
<xs:element name="number" type="xs:int"/>
<xs:element name="name" type="xs:string"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="ShirtType">
<xs:complexContent>
<xs:extension base="tns:ProductType">
<xs:sequence>
<xs:element name="size" type="xs:int"/>
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:element name="product"type="tns:ProductType"/>
...
|
When this schema is compiled, XMLBeans generates Java classes for the ProductType and ShirtType.
ProductType.java
...
public interface ProductType extends com.bea.xml.XmlObject
{
...
}
|
ShirtType.java
...
public interface ShirtType extends ProductType
{
...
}
|
The relation between the schema-types is translated into an inheritance relation between the Java classes. Consequently, ShirtType can be used wherever ProductType is specified.
...
ProductDocument pDoc = ProductDocument.Factory.newInstance();
ShirtType shirt = ShirtType.Factory.newInstance();
shirt.setName("Shirt");
shirt.setNumber(25);
shirt.setSize(40);
pDoc.setProduct(shirt);
...
|
XMLBeans will add the xsi:type attribute to the XML to indicate that ShirtType was used for ProductType.
<ext:Product <xsi:type="ext:ShirtType"
xmlns:ext="http://sample.openuri.info/extension"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<ext:number>25</ext:number>
<ext:name>Shirt</ext:name>
<ext:size>40</ext:size>
</ext:Product>
|
If instead of extension, if we were to use restriction.
...
<xs:complexType name="ProductType">
<xs:sequence>
<xs:element name="number" type="xs:int"/>
<xs:element name="name" type="xs:string" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="ShirtType">
<xs:complexContent>
<xs:restriction base="tns:ProductType">
<xs:sequence>
<xs:element name="number" type="xs:int"/>
</xs:sequence>
</xs:restriction>
</xs:complexContent>
</xs:complexType>
<xs:element name="product" type="tns:ProductType"/>
...
|
Now ShirtType has only one child - number. The generated Java classes will look similar to the extension case. But the inheritance has a side effect that ShirtType has a setter for name, which it inherits from
ProductType.java.
...
ShirtType shirt = ShirtType.Factory.newInstance();
shirt.setName("Shirt");
shirt.setNumber(25);
shirt.validate();
...
|
The last line will return false. If shirt.setName() is removed then validate() will return true.
Accessing the XML Infoset
XMLBeans keeps the underlying XML's infoset intact. The API that can be used to access this infoset is the XML cursor API. (link to docs). Using XML cursors we can easily write a function like getComments(), which returns an array of all comments in the XMLdocument.
public String[] getComments(XmlObject xml) throws Exception
{
XmlCursor cur = xml.newCursor();
cur.toStartDoc(); // Move the cursor to the start of the document
Vector v = new Vector();
while (cur.hasNextToken())
{
cur.toNextToken();
XmlCursor.TokenType tokType = cur.currentTokenType();
if (tokType.isComment()) v.addElement(cur.xmlText());
}
// Always a good idea to dispose the cursor after we are done using it
cur.dispose();
String[] comments = new String[v.size()];
v.copyInto(comments);
return comments;
}
|
The isComment() function tells if the token at the current position of the cursor is a comment or not. Other useful token types that you can test for are attribute, processing instruction, and namespace declaration.
The XML cursor API also lets us add comments or processing instructions to the infoset .
...
XmlObject xml = XmlObject.Factory.parse("<root><text>Some text</text>");
XmlCursor cur = xml.newCursor();
cur.toStartDoc();
cur.toFirstChild(); // Moves to <root>
cur.toNextToken(); // Moves to <text>
// Add before <text>
cur.insertProcInst("pi", "Adding using XmlCursor");
...
|
This will add a processing instruction into the XML just before the <text> token. The XMLwill look like this:
<root>
<?pi Adding using XmlCursor?>
<text>Some text</text>
</root>
|
Accessing the Schema Object Model
XMLBeans also provides a very rich schema object model (SOM) that lets you access the underlying schema meta-data and understand the content model programmatically. This can be used to do among other things generate sample XML for a given schema.Here's some code that for example gets a list of all member types of the union type size types that we have seen earlier:
...
SchemaType schemaType = SizeTypes.type;
// We know this is a SchemaType.UNION
SchemaType[] members = schemaType.getUnionMemberTypes();
for (int i = 0; i < members.length; i++)
{
QName name = members[i].getName();
System.out.println(name);
}
...
|
We can also get the SchemaType using XmlObject.schemaType(). The above code snippet will give the following output in the format: {namespaceURI}member-QName
{http://sample.openuri.info/union}NormalSizeType
{http://sample.openuri.info/union}NumberSizes
|
Another useful example is to get a list of the enumeration values for a type like the NormalSizeType that's a member of SizeTypes.
...
schemaType = NormalSizeType.type;
XmlAnySimpleType[] tokens = schemaType.getEnumerationValues();
for (int i = 0; i < tokens.length; i++)
System.out.println( tokens[i].getStringValue() );
...
|
Conclusion
This article has discussed- XMLBeans handling of some of schema types
- Getting to the underlying xml infoset using XML cursor
- Accessing the underlying schema meta-date using XMLBeans' schema object model
This article's intent is to give a glimpse of what can be achieved with XMLBeans. To learn more about this technology, please visit http://dev2dev.bea.com/technologies/xmlbeans/index.jsp.
