RSS Feed
Download our iPhone app
Browse DevX
Sign up for e-mail newsletters from DevX


Using Java to Handle Custom WSDL Data Types : Page 3

What happens when neither the default WSDL type system nor the default encoding meet your application's needs? Don't worry, you can use custom data types and encoding formats in conjunction with Java to solve the problem.

Declaring New Data Types in a WSDL Document
The XML Schema specification provides a feature for defining custom data types. Whenever a service requires data that can be represented more conveniently with abstractions beyond the scope of the simple XML Schema data types, these abstractions can be declared as new data types within the WSDL <types> element. The example in Listing 1 defined the custom data type shown below:

   <complexType name="HelloWorld">
         <element name="message"
The definition represents the message data type as a simple string, and the new type definition adds a constraint to the data type—the element is required to appear because the value of the minOccurs attribute is greater than zero.

A more sophisticated use of a custom data type might include contact information for a user such as the following:

   <complexType name="AddressType">
         <element name="streetName"
         <element name="city"
         <element name="state"
         <element name="zip"
         <element name="phoneNumber"
In the preceding example, <AddressType> defines a custom data type that encapsulates user contact information. Notice that the <state> element is defined as a simple string, allowing virtually any text content of any length to occur in the element. A more robust method would constrain the state element to a two-letter abbreviation by defining a custom "two-letter-state" data type and then referencing that in the <AddressType> data type. Here's a custom string data type restricted to a length of two:

   <simpleType name="two-letter-state">
      <restriction base="string">
         <length value="2"/>
It's relatively easy to see the relationship between data type definitions in XSD schema and object definitions in Java (or other languages) expressed in code. You can make these relationships explicit using mapping software.

XSD Data Types and Java Data Types
The Java programming language provides data types that can be mapped to represent most of the standard XSD data types. Table 2 contains a list of mappings from XSD data types to Java data types:

Table 2. XSD-to-Java Mappings: The table shows how you can map a list of XSD data types to their equivalents in Java.
XSD Type Java Type
base64Binary byte[]
hexBinary byte[]
boolean Boolean
byte Byte
dateTime java.util.Calendar
date java.util.Calendar
time java.util.Calendar
decimal java.math.BigDecimal
double Double
float Float
hexBinary byte[]
int Int
unsignedShort Int
integer java.math.BigInteger
long Long
unsignedInt Long
QName javax.xml.namespace.QName
short Short
unsignedByte Short
string java.lang.String
anySimpleType java.lang.String

The mappings in Table 2 illustrate a comprehensive list of simple data type mappings; however, as you need more complex abstractions and need to extend XSD types with custom type declarations, it also becomes more complex to map such types to Java. Mapping custom type declarations is the focus of this article. First, though, here's a brief overview of the XML tools you'll need to implement the mapping operation.

Streaming API for XML (StAX)
XSD and WSDL are XML-based grammars that you can process using standard XML-processing techniques. XML processing in Java has evolved into two main approaches:

  1. The Simple API for XML processing (SAX)
  2. The Document Object Model (DOM)
SAX exposes a callback-style parsing API while DOM provides a randomly-accessible tree-like structure.

The Streaming API for XML (StAX) specification defines a new and highly-efficient API for parsing and streaming XML. The StAX specification defines a bi-directional API for reading and writing XML. StAX allows developers to maintain parsing control by exposing a simple iterator-based API, with intuitive methods such as next() and hasNext(), as well as an underlying stream of events. This iterator-based API lets you "pull" the next event rather than handling the event in a callback. The cursor API facilitates processing-control even further by letting you stop processing, skip ahead to sections of a document, and retrieve subsections of a document.

Introducing XMLBeans
Apache XMLBeans is an open source, XML-Java binding tool based on the StAX specification. You can use XMLBeans to generate Java classes and interfaces from an XML schema, subsequently using those generated Java classes to parse or generate XML documents that conform to the schema.

BEA originated XMLBeans and then donated it to the Apache Software Foundation. XMLBeans provides three major APIs for access to XML and schema:

  • Strongly-typed access—XMLBeans can compile an XML schema to generate Java classes and interfaces. The generated classes and interfaces all extend a common base class and provide strongly-typed getters and setters for each of the elements found in the schema.
  • Cursor-style access—From any generated class you can get instance of a positional cursor object that allows low-level access to the XML information.
  • Schema-style access—XMLBeans provides a schema object model that you can use to reflect on the XML schema.
Installing XMLBeans
To install XMLBeans, download the binary distribution of XMLBeans, and extract the archive into the directory of your choice. Next, define an XMLBEANS_HOME environment variable with a value set to the directory where you extracted the binary distribution files. Finally, add the .jar and .zip files contained in the XMLBeans distribution to your project.

The remainder of this article demonstrates how to implement a simple WSDL-to-Java interpreter using the XMLBeans framework and APIs. It's important to understand that as Web service providers increasingly adopt WSDL as the doctrine of exchange for integrating with their systems via publicly-accessible services, service clients must have the ability to process WSDL dynamically to leverage those services. That's because the WSDL document may often be the only point of access to service information. Fortunately, when properly prepared, the WSDL document is also all that clients need.

The XMLBeans framework facilitates the ability to compile a WSDL file into Java objects. With this facility, developers can dynamically generate Web service clients from WSDL documents, using the resulting Java classes and interfaces associated with the data types and methods of the Web service. Interpreting WSDL dynamically offers a degree of power greater than standard static XML-parsing and processing techniques.

Close Icon
Thanks for your registration, follow us on our social networks to keep up-to-date