Accessing and Manipulating XML Data with XML Beans

XML Beans is a WebLogic Workshop tool that provides a simple, intuitive means of accessing and editing XML documents. XML Beans evolves the state of XML parsing beyond that of JAXB by

• Generating Java classes based on the full XML Schema specification

• Storing the XML document in memory rather than using the overhead- intensive marshaling and unmarshaling of external data

As a result, XML Beans offers both more flexibility in representing XML data and, in most cases, comparableif not fasterprocessing of data than previously developed XML parser APIs.

SHOP TALK : XML BEANS VERSUS XML PARSER TECHNOLOGIES

How much better is XML Beans than other XML parser technologies? During development of the Workshop product, the BEA team did some benchmarking and shared its results, for informational purposes only, on the BEA dev2dev Web site (http://workshop.bea.com/xmlbeans/schemaandperf.jsp).

The tests compared the operation of XML Beans, Xerces DOM, and JAXB parsers. Xerces is an extremely popular, open -source, Java-based XML parser developed as part of the Apache XML Project. (For more information, visit http://xml.apache.org .)

To be as realistic as possible, the tests were conducted using sample documents conforming to the Purchase Order sample Schema provided as part of the W3C XML Schema primer and ranging in size from 1kb to 1MB. The Schema presented in Listing 10.2 is also available at http://www.w3.org/TR/xmlschema-0/#POSchema.

Listing 10.2. The po.xsd Schema File Used for BEA's XML Beans Performance Tests

 <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">  <xsd:annotation>   <xsd:documentation xml:lang="en">    Purchase order schema for Example.com.    Copyright 2000 Example.com. All rights reserved.   </xsd:documentation>  </xsd:annotation>  <xsd:element name="purchaseOrder" type="PurchaseOrderType"/>  <xsd:element name="comment" type="xsd:string"/>  <xsd:complexType name="PurchaseOrderType">   <xsd:sequence>    <xsd:element name="shipTo" type="USAddress"/>    <xsd:element name="billTo" type="USAddress"/>    <xsd:element ref="comment" minOccurs="0"/>    <xsd:element name="items"  type="Items"/>   </xsd:sequence>   <xsd:attribute name="orderDate" type="xsd:date"/>  </xsd:complexType>  <xsd:complexType name="USAddress">   <xsd:sequence>    <xsd:element name="name"   type="xsd:string"/>    <xsd:element name="street" type="xsd:string"/>    <xsd:element name="city"   type="xsd:string"/>    <xsd:element name="state"  type="xsd:string"/>    <xsd:element name="zip"    type="xsd:decimal"/>   </xsd:sequence>   <xsd:attribute name="country" type="xsd:NMTOKEN"      fixed="US"/>  </xsd:complexType>  <xsd:complexType name="Items">   <xsd:sequence>    <xsd:element name="item" minOccurs="0" maxOccurs="unbounded">     <xsd:complexType>      <xsd:sequence>       <xsd:element name="productName" type="xsd:string"/>       <xsd:element name="quantity">        <xsd:simpleType>         <xsd:restriction base="xsd:positiveInteger">          <xsd:maxExclusive value="100"/>         </xsd:restriction>        </xsd:simpleType>       </xsd:element>       <xsd:element name="USPrice"  type="xsd:decimal"/>       <xsd:element ref="comment"   minOccurs="0"/>       <xsd:element name="shipDate" type="xsd:date" minOccurs="0"/>      </xsd:sequence>      <xsd:attribute name="partNum" type="SKU" use="required"/>     </xsd:complexType>    </xsd:element>   </xsd:sequence>  </xsd:complexType>  <!-- Stock Keeping Unit, a code for identifying products -->  <xsd:simpleType name="SKU">   <xsd:restriction base="xsd:string">    <xsd:pattern value="\d{3}-[A-Z]{2}"/>   </xsd:restriction>  </xsd:simpleType> </xsd:schema> 

Table 10.1 summarizes the results of the suite of eight tests on 100KB purchase order documents. All tests measured the time in milliseconds to complete the operation except for Test 5, which measured the amount of consumed memory.

Table 10.1. Results of XML Beans Performance Tests Conducted on 100KB Purchase Order Test Documents During Product Development

TEST #	TITLE	SCORES
1	Loading a Document	13.4 - XML Beans 16.1 - Xerces 2.3 DOM
2	Load and Save a Document	24.5 - Xerces 2.3 DOM 28.4 - XML Beans
3	Load, Modify, and Save a Document	32.1 - XML Beans
4	Load and Read a Document (time)	16.2 - XML Beans Cursor 17.9 - Xerces 2.3 DOM 26.4 - XML Beans 86.0 - JAXB 1.0 Beta
5	Load and Read a Document (memory)	247 - JAXB 1.0 Beta 328 - XML Beans Cursor 575 - XML Beans 663 - Xerces 2.3 DOM
6	Construct a Document in Memory	12.1 - Xerces 2.3 DOM 32.4 - XML Beans
7	Construct a Document in Memory and Save	26.1 - Xerces 2.3 DOM 75.7 - XML Beans
8	Validation	42.7 - Xerces 2.3 DOM 48.7 - XML Beans 136 - JAXB 1.0 Beta

After analyzing the results, I'd like to share my observations, which mesh well with the comparison of XML parser technologies discussed in the chapter:

Except for in-memory construction of documents, the performance of the XML Beans and Xerces parsers are comparable.

The XML Beans and Xerces parsers came within about 20% of each other. This is a big win when comparing a new parsing technology against a DOM parser that's been around for more than four years . Remember that the downside of DOM parsers isn't their performance but the tedious programming required when mapping data to workable objects in the application.

As for creating new documents in memory, it's expected that Xerces will DOMinate (sorry, couldn't resist the pun) because XML Beans is working with strongly typed Java classes rather than Strings .

Performance-wise, XML Beans blows JAXB away.

Sure, JAXB marshaling and unmarshaling of XML data can make for efficient memory usage, but as I said before, it's a killer as far as overhead is concerned . In the tests involving both JAXB and XML Beans parsers, XML Beans offered 300% better performance than JAXB.

If you need DOM performance, XML Beans offers an alternative.

As mentioned in "Using XPath Expressions with XML Beans" later in this chapter, the XML Beans API offers a DOM-like means of navigating through documents via the XmlCursor object. Tests 4 and 5 show that this alternative is more time and memory efficient than DOM.

Setting Up XML Beans in WebLogic Workshop

To use XML Beans in your Workshop application, you must first select the XML document types to be handledvia their Schemaand then generate the affiliated Java data handling classes. This configuration is handled visually, without any code-level development.

Creating a Schema Project

If your application doesn't already contain a Schema project, you must add one at this time. As described in Chapter 2, "Getting to Know the WebLogic Workshop IDE," you add a project by following these steps:

1. Right-click on the root folder in the Application pane and select New, Project from the pop-up menu.

2. In the resulting New Project dialog box, click on Schema Project in the right-hand pane.

3. In the Project Name text field, type in a name for the project.

4. Click the Create button.

The New Project dialog box with appropriate Schema project settings is shown in Figure 10.1. If the default application type you're developing already includes a Schema project, note that creating a new Schema project might not be necessary.

Figure 10.1. The New Project dialog provides an easy way to add a Schema project to an existing application.

Creating XML Beans Interfaces

To create the Java-based XML Beans interfaces for a certain class of XML documents, you must then import the XML Schema on which the documents are based. This is accomplished by following these steps:

1. Right-click on the Schema project folder, and choose Import.

2. Use the file browser capabilities of the Import Files dialog box to locate the Schema ( .xsd ) file. For this application, you'll be adding the CasinoLayout.xsd file from the Chap10 folder. This Schema file is shown in Listing 10.3.

3. Click the Import button.

4. At this point, WebLogic Workshop adds the .xsd file to the Schema project folder and begins compiling the Schema file into Java interfaces. You can see the progress of the compilation in the Build pane, which is located at the bottom center of the Workshop window by default.

Listing 10.3. The CasinoLayout.xsd Schema File

 <?xml version="1.0" encoding="UTF-8"?> <xs:schema targetNamespace="http://openuri.org/bea/samples/workshop/chap10/casinoLayout" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:cl="http://openuri.org/bea/samples/workshop/chap10/casinoLayout" elementFormDefault="qualified" attributeFormDefault="unqualified">     <xs:element name="casino" type="cl:casinoType"/>     <xs:complexType name="casinoType">         <xs:sequence>             <xs:element name="table" type="cl:tableType" maxOccurs="unbounded"/>         </xs:sequence>     </xs:complexType>     <xs:complexType name="tableType">         <xs:sequence>             <xs:element name="game">                 <xs:simpleType>                     <xs:restriction base="xs:NMTOKEN">                         <xs:enumeration value="blackjack"/>                         <xs:enumeration value="poker"/>                         <xs:enumeration value="slots"/>                         <xs:enumeration value="roulette"/>                     </xs:restriction>                 </xs:simpleType>             </xs:element>             <xs:element name="minimumBet">                 <xs:simpleType>                     <xs:restriction base="xs:decimal">                         <xs:totalDigits value='6'/>                         <xs:fractionDigits value='2'/>                         <xs:minInclusive value='0.25'/>                         <xs:maxInclusive value='1000.00'/>                     </xs:restriction>                 </xs:simpleType>             </xs:element>         </xs:sequence>         <xs:attribute name="number" type="xs:int" use="required"/>    </xs:complexType> </xs:schema> 

If the Schema file is not well formed (that is, is not syntactically correct), the Build pane shows the location and specifics of each error in red. Clicking on any error line immediately opens the Schema file in the Source View pane and highlights the code (see Figure 10.2).

Figure 10.2. Workshop supplies clear indications of errors in Schema files when they are added to the project.

If the Schema file is well formed, the Build pane shows that the build was successful. In addition, the XML Bean classes are added to the Libraries folder as a JAR file with the same name as the Schema project. The classes are grouped in a package with a name corresponding to the namespace of the XML Schema document. For this example, as shown in Figure 10.3, this namespace

http://openuri.org/bea/samples/workshop/chap10/casinoLayout

Figure 10.3. Compiled XMLBean classes are added to the Libraries folder.

produces this package

 org.openuri.bea.samples.workshop.chap10.casinoLayout 

All classes in the Libraries folder are automatically added to the application's classpath, so they are available for immediate use in your application. The generated classes are also added to the XML Bean Classes folder under the Schema project.

By default, every time a Schema file is edited and saved, the corresponding XML Bean classes are recompiled. To toggle this option off, follow these steps:

1. Right-click on the Schema project folder, and choose Properties.

2. In the Project Properties dialog box that opens, select the Build folder.

3. Clear the Auto-Build When File Changes Occur check box in the Schema Project section (see Figure 10.4).

   Figure 10.4. The Project Properties dialog box provides a means of toggling on and off the recompilation of XML Bean classes when Schema files are modified.

   

To rebuild the Schema project when this option is turned off, right-click on the Schema project folder and choose the Build < Name of Project > option.

What If I Don't Have a Schema for My XML Document?

If you don't have a Schema for the type of XML documents you want to handle, have no fear. A number of third-party products can be used to generate XML Schema from DTD files. BEA WebLogic Platform 8.1 includes the option to install an evaluation copy of one such package, Altova's XML Spy Enterprise Edition. If you installed this tool, follow these steps to create a Schema file from an XML document:

1. Launch XML Spy by selecting Tools, External Tools, XML Spy from the Workshop menu or by locating the program shortcut on your computer.

2. Load the XML file into XML Spy.

3. Choose DTD/Schema, Generate DTD/Schema from the XML Spy menu.

4. In the Generate DTD/Schema dialog box that opens, select the options that suit your needs. Table 10.2 lists suggested settings.

5. Click OK and then Yes to immediately apply the Schema to the document.

NOTE ON XML SPY LICENSE INCLUDED WITH WEBLOGIC WORKSHOP

When the trial period for XML Spy Enterprise Edition ends, you're prompted to either purchase the product or do nothing. If you choose the latter option, the license is converted to a nonexpiring version of XML Spy WebLogic Edition, which is basically equivalent to the XML Spy Home Edition. This edition, however, does not include the functionality to convert DTDs to XML Schema.

Table 10.2. Suggested Settings for XML Spy's Generate DTD/Schema Dialog Box

PARAMETER	SUGGESTED VALUE
DTD/Schema File Format	W3C Schema
List of Values	Only if not more than 20
Attribute/Element Type Detection	Best Possible
Represent Complex Elements As	Complex Types
Elements Which Were Used Once	Make Local Definition

Invoking XML Beans

XML Beans are created and handled by adding Java code to the appropriate application component in the Source View pane. To begin, you must add an import statement for the package in which the XML Beans interfaces reside. Don't be concerned if you forget the exact package name; as mentioned in Chapter 2, Workshop provides import statement code completion.

Individual XML Bean calls are then added as needed to the application component's code. In addition to the document-specific interfaces, each with get and set methods that are similar to JavaBeans, the API offers a number of general interfaces, classes, and exceptions, all contained in the com.bea.xml package. Many of these components correspond to the built-in element types in the Schema specification. (For example, the XmlInt interface is linked to the xs:int type.) Others, such as the XmlOptions class, are linked to the operation of the XML parser.

Complete API documentation on the com.bea.xml package is supplied in the WebLogic Workshop Reference, Workshop API Javadoc Reference, XML Beans API Reference section of the Reference Guide. You can open the Reference Guide by selecting Help, Reference Guide from the Workshop menu. Workshop's code completion mechanism gives you a guide to the syntax of available method calls.

Creating XML Beans

To represent a complete XML document, Workshop creates a document interface; its name corresponds to the name of the root element with the word "Document" added to the end. New instances of this document are then created through the widely used Factory pattern: calling the newInstance() method on a Factory subclass of this document classin this case, CasinoDocument .

Although the no-argument version of this method serves in many cases, Workshop also provides a variation that takes an XmlOptions argument. The XmlOptions object enables developers to configure a set of XML parser features for loading, saving, compiling, and validating XML documents. Settings include selecting the appropriate character encoding and allowing or stripping off whitespace and comments in the produced XML document.

From this point, you build up the document, element by element, according to the hierarchy defined in the Schema. To do this, you call the appropriate add< object type > methods to create elements and call the corresponding set< object type > methods to set values for these elements. The complete code for creating the casinoLayout XML document is provided in Listing 10.4, and the resulting XML document is shown in Listing 10.5.

Listing 10.4. Code to Create a casinoLayout XML Document

 import java.math.BigDecimal; import org.openuri.bea.samples.workshop.chap10.casinoLayout.CasinoDocument; import org.openuri.bea.samples.workshop.chap10.casinoLayout.CasinoType; import org.openuri.bea.samples.workshop.chap10.casinoLayout.TableType;     public CasinoDocument getSampleCasino()     {         CasinoDocument casinoDoc = CasinoDocument.Factory.newInstance();         CasinoType casinoType = casinoDoc.addNewCasino();         TableType tableType = null;         TableType.Game.Enum[] tableArray = {             TableType.Game.BLACKJACK, TableType.Game.POKER,             TableType.Game.ROULETTE, TableType.Game.SLOTS} ;         double[] betArray = {10.00, 50.00, 5.00, 0.25};         for (int i = 0; i < 4; i++)         {             tableType = casinoType.addNewTable();             tableType.setGame(tableArray[i]);             tableType.setMinimumBet(new BigDecimal(betArray[i]));             tableType.setNumber(i+1);         }         return casinoDoc;     } 

Listing 10.5. The Resulting casinoLayout XML Document

 <casino xmlns="http://openuri.org/bea/samples/workshop/chap10/casinoLayout">     <table number="1">         <game>blackjack</game>         <minimumBet>10</minimumBet>     </table>     <table number="2">         <game>poker</game>         <minimumBet>50</minimumBet>     </table>     <table number="3">         <game>roulette</game>         <minimumBet>5</minimumBet>     </table>     <table number="4">         <game>slots</game>         <minimumBet>0.25</minimumBet>     </table>     <table number="5">         <game>slots</game>         <minimumBet>0.50</minimumBet>     </table> </casino> 

After the XML document is created, you can store it or transfer it, just like any other Java object. For example, you can write the XMLBean to a file or pass it as a parameter to another Java method.

Retrieving and Modifying Data from XML Beans

The XML Beans API offers multiple ways to gain access to an existing XML document through the overloaded parse() method. There are versions of this method that can take any of the following arguments:

• File

• java.io.InputStream

• java.net.URL

• org.w3c.dom.Node

• Reader

• String

• weblogic.xml.stream.XMLInputStream

All methods have corresponding versions with a second XmlOptions argument; for the sake of space, they are not listed here.

After the document is retrieved, the appropriate get< object type > methods can be used to read element values from the document, and the add< object type > and set< object type > methods can be used for edits.

When an element can occur more than once, as defined by a maxOccurs attribute set to greater than one or unbounded in the Schema, you need a means for programmatic iteration. In this case, the Workshop compiler is intelligent enough to generate special array-based get/set methods in the compiled XML Beans interface. For this example, a CasinoLayout document can have multiple Table elements. Therefore, the XML Beans interface includes getTableArray() and setTableArray() methods.

Listing 10.6 supplies the code to process an instance of the casinoLayout XML document from the file and print a summary to standard output.

Listing 10.6. Code for Processing a casinoLayout XML Document

 public void printCasino(String casinoString) {     try     {         CasinoDocument      casinoDoc = CasinoDocument.Factory.         parse(casinoString);         CasinoType          casino = casinoDoc.getCasino();         TableType[]         tableArray = casino.getTableArray();         TableType           currTable;         TableType.Game.Enum gameType;         double              minBet;         int                 tableNum;         for (int i=0; i < tableArray.length; i++)         {             currTable   = tableArray[i];             tableNum    = currTable.getNumber();             gameType    = currTable.getGame();             minBet      = currTable.getMinimumBet().doubleValue();             System.out.println(                 "Table #" + tableNum + " - " +                 gameType.toString() + " - " +                    "$" + minBet);         }     }     catch (com.bea.xml.XmlException xmle)     {         System.out.println("Invalid casino document");     } }