Using JAX-WS and JAXB with WebLogic Server 10

by Mike Wooten
09/26/2007

Abstract

JAX-WS (Java Architecture for Web Services) is a standards-based API for coding, assembling, and deploying Java Web services, designed to replace JAX-RPC. JAXB (Java Architecture for XML Binding) is a Java/XML binding technology. JAX-WS uses JAXB to handle all the Java binding chores.

This article provides an overview of the JAX-WS 2.0 and JAXB 2.0 support in BEA WebLogic Server 10.1. I include sample code to get you started.

Very Busy Java Developer's Guide to JAXB 2.0

JAX-WS uses JAXB to handle all the Java binding chores, so I will primarily be discussing JAXB as it relates to JAX-WS. A skilled Java developer is typically also a very busy one. This being the case, I'll limit the discussion to:

• Stuff you can currently do with JAXB 2.0.
• Stuff you can't currently do with JAXB 2.0.

For those of you who are too busy to even read this article, feel free to just go ahead and download the article's Download sample code. There is a README file inside the zip, which walks you through all the steps to get things working.

What Kind of Stuff Can You Do with JAXB 2.0?

Here's a list of some of the more interesting stuff you can do with JAXB 2.0. This is not to say that you can't do the same things with other Java-to-XML/XML-to-Java binding technologies. It's merely stating what you can do with JAXB 2.0:

• Generate Java object graphs from a WSDL containing one or more <xs:schema> elements. These <xs:schema> elements can use <xs:import> and <xs:include> elements to reference other <xs:schema> elements.
• Generate XML Schema documents from Java object graphs.
• Leverage Fast Infoset parsers (SAX and StAX) and serializers.
• Get random access to the XML infoset of an XML document.
• Embed binding declarations directly in XML Schema files, or in an external binding customization file.
• Use the event-based streaming model when unmarshalling.
• Marshal binary data (for example, handle MTOM and MIME attachments).
• Develop your own plug-ins to extend the JAXB code generation capabilities. These plug-ins (which are packaged as classes in a .jar file) can then access the code that JAXB generates, plus generate additional classes/methods/fields/annotations/comments.
• Write custom code to transform existing classes into the classes generated by the JAXB schema compiler.

What Kind of Stuff Can't You Do with JAXB 2.0?

Here's a list of some of the stuff you can't (or I didn't see a way how to) do with JAXB 2.0:

• Generate an XML schema from an XML document. This is really not such a big deal, because other tools (like Stylus Studio, XMLSpy, XMLBuddy Pro) can do this.
• Match the performance numbers of using StAX or SAX for parsing. When parsing the same XML document, SAX came in at 10ms, StAX at 46ms, and JAXB 2.0 at 59ms.

Sample POJO JAX-WS Web Service that Uses JAXB for Java Binding

JAX-WS is a standards-based API for coding, assembling, and deploying Java Web services. It uses JAXB to handle all the Java binding chores associated with this. JAX-WS 2.0/2.1 doesn't support the use of JAX-RPC or Apache Beehive XMLBean types—just JAXB ones.

JAX-WS provides two programming models for developing a Web service endpoint:

1. Start from Java—This programming model provides you with a lot of control over the Java data types used in the method signatures of your Web service endpoint. Here, you hand-code (or use a tool to generate) the Java objects that will be used as the input arguments and return value of Web service operations, along with JWS annotations.

   BEA provides the jwsc Ant task for the "Start from Java" programming model. It wraps (that is, invokes) the Glassfish wsimport Ant task internally, so I don't directly use that Ant task in the build.xml.

   The Ant Task Reference for jwsc BEA documentation describes how to use the <jws> element's type="JAXWS" attribute to generate JAXB artifacts. The jwsc Ant task has a <binding> child element for specifying the JAXB binding customization file to use.

2. Start from WSDL   This programming model generates the skeleton code for your Web service endpoint, from the contents of a WSDL. The <xs:schema> sections in the WSDL are used to generate the Java data types used as the input arguments and return value, of Web service operations.

   BEA provides the wsdlc Ant task for the "Start from WSDL" programming model. It wraps the Glassfish wsimport Ant task internally, so I don't directly use that Ant task in the build.xml.

   The Ant Task Reference for wsdlc BEA documentation describes how to use the <wsdlc> element's type="JAXWS" attribute to generate JAXB artifacts. The wsdlc Ant task has a <binding> child element for specifying the JAXB binding customization file to use.

The remainder of the article walks through the process of creating, deploying, and testing a sample POJO-based (Plain-Old Java Object) JAX-WS Web service endpoint, named DataStagingService.

Creating the Customization File

The first step involves creating a JAX-WS customization file. This doubles as a JAXB binding customization file, and allows you to control the JAX-WS and JAXB build-time processes, as well as the artifacts produced by them.

The customization file is an XML document that conforms to the XML schemas for the http://java.sun.com/xml/ns/jaxws and http://java.sun.com/xml/ns/jaxb namespaces. You can find details on how to create this customization file at JAX-WS 2.0 Beta Customizations.

The JAX-WS customization file for this DataStagingService Web service is pretty small, so I've included it here:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<bindings
 xmlns:jxb="http://java.sun.com/xml/ns/jaxb"
 xmlns="http://java.sun.com/xml/ns/jaxws"
 wsdlLocation="DataStagingService2.wsdl"
>
  <bindings
    xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    node="wsdl:definitions"
  >
    <package name="services.datastaging">
      <jxb:javadoc>
        <![CDATA[<body>Package level documentation for generated 
                       package services.datastaging.</body>]]>
      </jxb:javadoc>
    </package>
    <jxb:schemaBindings>
      <jxb:package name="com.acmeworld.irad.services.datastaging"/>
    </jxb:schemaBindings>
  </bindings>
</bindings>

I basically just use the customization file to control the Java package name of classes that are generated. You can do a lot more than this in one of these files, so be sure to check out JAX-WS 2.0 Beta Customizations.

The next listing contains the XML Schema used in the WSDL, for the DataStagingService Web service:

<xs:schema
 targetNamespace="http://services.irad.acmeworld.com/datastaging"
 xmlns:tns="http://services.irad.acmeworld.com/datastaging"
 xmlns:xs="http://www.w3.org/2001/XMLSchema"
 elementFormDefault="qualified"
>
  <xs:complexType name="DataStaging">
    <xs:sequence>
      <xs:element name="inputURIs">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="inputURI" maxOccurs="unbounded">
              <xs:complexType>
                <xs:sequence>
                  <xs:element name="uri" type="xs:anyURI"/>
                </xs:sequence>
              </xs:complexType>
            </xs:element>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="DataStagingResponse">
    <xs:sequence>
      <xs:element name="outputURIs">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="outputURI" maxOccurs="unbounded">
              <xs:complexType>
                <xs:sequence>
                  <xs:element name="uri" type="xs:anyURI"/>
                </xs:sequence>
              </xs:complexType>
            </xs:element>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
    </xs:sequence>
  </xs:complexType>

  <xs:element name="dataStaging" type="tns:DataStaging"/>
  <xs:element name="dataStagingResponse" type="tns:DataStagingResponse"/>
</xs:schema>

The XML Schema section from this WSDL is pretty normal-looking. It's your basic garden variety, global complexType elements (with anonymous and explicit content models) combined to create request and response messages. DataStagingService is a doc/literal style Web service, so global elements have been included for use with the WSDL's <part> element.