Generating a Java Client Binding

CAA Web Services Home		Generating a Java Client Binding How to use WSDL and XSD definitions to generate Java client bindings for CAA Web services
Technical Article

Abstract

This article introduces Axis and explains how to use the WSDL2Java emitter in order to generate Java client bindings for CAA Web services. These bindings can then later be used to create client applications that consume CAA Web services.

Axis Overview
Officially Certified Releases
Step-by-step Using the WSDL2Java Emitter From Command Line
In Short
References

Axis Overview

Apache Axis is an implementation of the SOAP submission to the W3C. It can be used to build and deploy Web services as well as to consume them. In the context of CAA Web services, only the client side part of Axis (Java) is required:

Buildtime: the WSDL2Java emitter is used to produce a Java client binding (also often referred to as the proxy) based on the WSDL definition of a CAA Web service,
Runtime: the Axis SOAP engine (later referred to as the Axis SOAP runtime) is invoked using the generated code in order to consume the CAA Web service.

Please refer to the Axis documentation for further details. It is recommended that you read the documentation that is shipped with the officially certified releases (as listed below) instead of accessing it online. The online documentation always matches the most recent release and therefore may not be in sync with the downloaded one.

[Top]

Officially Certified Releases

The term "certified" is intended to describe the fact that a given Axis release has been successfully tested and validated in order to consume CAA Web services. As of now, the certified release is:

Axis Final Version 1.3 - October 5, 2005

It is recommended that you use Axis (Java) 1.3 as it is the most advanced release officially certified for now. The information given in the rest of this article are based on that specific release.

[Top]

Step-by-step Using the WSDL2Java Emitter From Command Line

Before using the WSDL2Java emitter, it is important to get an understanding of some of the concepts that are related to the WSDL documents describing the available CAA Web services. See [1] for an overview of these concepts.

In order to use the WSDL2Java emitter from a command line prompt, you first need to configure your environment by setting up the Axis prerequisites, and then you need to invoke the WSDL2Java class using a WSDL document as input. These steps are described in the following sections:

Prerequisites
Configuring the WSDL2Java Emitter Environment
Generating a Java Client Binding
Overview of the Generated Code

[Top]

Prerequisites

In order to use the WSDL2Java emitter, you need to download the Axis binary release [2]. The following demonstrates the use of the Axis 1.3 release. This release is available from the following archives: axis-bin-1_3.zip or axis-bin-1_3.tar.gz. It is not required to download one of the source code releases.

The Axis WSDL2Java emitter and the Axis SOAP runtime have the following dependencies:

<Axis-unzipped-folder>\axis-1_3\lib\axis.jar
<Axis-unzipped-folder>\axis-1_3\lib\axis-schema.jar
<Axis-unzipped-folder>\axis-1_3\lib\jaxrpc.jar
<Axis-unzipped-folder>\axis-1_3\lib\saaj.jar
<Axis-unzipped-folder>\axis-1_3\lib\commons-discovery-0.2.jar
<Axis-unzipped-folder>\axis-1_3\lib\commons-logging-1.0.4.jar
<Axis-unzipped-folder>\axis-1_3\lib\wsdl4j-1.5.1.jar
A JAXP-1.1 compliant XML parser such as Xerces [3] or Crimson (downloading one is not required when using Java 1.4 or higher as it natively includes its own XML parser)

Please note that Axis requires Java 1.3 or later.

[Top]

Configuring the WSDL2Java Emitter Environment

In order to launch the WSDL2Java emitter from the command line, you need to make sure that your CLASSPATH includes the required dependencies. A sample way to set your CLASSPATH with the appropriate values is given below. It is based on the Windows operating system but can be easily modified in order to match any other operating system environment. You can open a command line prompt and copy/paste the following commands (you can also create a batch file for convenience purpose). Please update the values in italic below (AXIS_HOME, JDK_HOME and optionally XERCES_HOME variables) with the appropriate ones matching your environment:

Using Java 1.3

set AXIS_HOME=C:\bin\axis-1_3

        set XERCES_HOME=C:\bin\xerces-2_6_2

        set JDK_HOME=C:\jdk1.3.1_08

        set CLASSPATH=%CLASSPATH%;%AXIS_HOME%\lib\axis.jar

        set CLASSPATH=%CLASSPATH%;%AXIS_HOME%\lib\axis-schema.jar

        set CLASSPATH=%CLASSPATH%;%AXIS_HOME%\lib\jaxrpc.jar

        set CLASSPATH=%CLASSPATH%;%AXIS_HOME%\lib\saaj.jar

        set
        CLASSPATH=%CLASSPATH%;%AXIS_HOME%\lib\commons-discovery-0.2.jar

        set
        CLASSPATH=%CLASSPATH%;%AXIS_HOME%\lib\commons-logging-1.0.4.jar

        set CLASSPATH=%CLASSPATH%;%AXIS_HOME%\lib\wsdl4j-1.5.1.jar

        set CLASSPATH=%CLASSPATH%;%XERCES_HOME%\xml-apis.jar

        set CLASSPATH=%CLASSPATH%;%XERCES_HOME%\xmlParserAPIs.jar

        set CLASSPATH=%CLASSPATH%;%XERCES_HOME%\xercesImpl.jar

        %JDK_HOME%\bin\java org.apache.axis.wsdl.WSDL2Java -h

Note: this sample assumes the use of Xerces2 Java Parser 2.6.2. It can be easily updated in order to match the Xerces release you wish to use, or if you decide to choose another compliant XML parser.

Using Java 1.4 or Java 5.0

set AXIS_HOME=C:\bin\axis-1_3

        set JDK_HOME=C:\jdk1.5.0_05

        set CLASSPATH=%CLASSPATH%;%AXIS_HOME%\lib\axis.jar

        set CLASSPATH=%CLASSPATH%;%AXIS_HOME%\lib\axis-schema.jar

        set CLASSPATH=%CLASSPATH%;%AXIS_HOME%\lib\jaxrpc.jar

        set CLASSPATH=%CLASSPATH%;%AXIS_HOME%\lib\saaj.jar

        set
        CLASSPATH=%CLASSPATH%;%AXIS_HOME%\lib\commons-discovery-0.2.jar

        set
        CLASSPATH=%CLASSPATH%;%AXIS_HOME%\lib\commons-logging-1.0.4.jar

        set CLASSPATH=%CLASSPATH%;%AXIS_HOME%\lib\wsdl4j-1.5.1.jar

        %JDK_HOME%\bin\java org.apache.axis.wsdl.WSDL2Java -h

Upon successful invocation, the last command displays the WSDL2Java emitter options. You are then ready for the next steps of this article. Please keep the command prompt open as it will be used to launch the WSDL2Java emitter again.

[Top]

Generating a Java Client Binding

The Axis WSDL2Java emitter can be used to generate the Java client bindings required to consume CAA Web services. Such generation is a simple and straight-forward process; you only need to provide as input a WSDL document describing the CAA Web service you wish to consume. It can either be a WSDL interface document or a WSDL implementation document. The WSDL2Java emitter generates extra classes when using the latter, but the core generated resources remain the same in both cases.

It is strongly recommended that you use the WSDL implementation document as input whenever available. In some cases, it may not be available when generating the Java client binding, for example if the CAA Web service has not yet been deployed to a target application server. In such context, the WSDL interface document could be used instead since it is accessible from the file system. Nevertheless, the use of the WSDL implementation document remains the recommended approach, as the file system may not always be accessible from a remote machine based on the applied security settings.

From the command prompt configured in the above section, you can invoke the WSDL2Java emitter using the following syntax:

%JDK_HOME%\bin\java org.apache.axis.wsdl.WSDL2Java -o
        <Output-folder> -p <Package-name>
        <WSDL-URI>

<Output-folder>: output folder for the emitted Java resources,
<Package-name>: name of the Java package used for the generated Java resources,
<WSDL-URI>: URI of the input WSDL document:
- When using a WSDL interface document as input, you can either provide a local path value (access from the file system) or a URI value (remote access). See [4] for details,
- When using a WSDL implementation document as input, you need to provide a URI value. See [5] for details.

When the WSDL document is accessed from a remote location using the HTTP protocol, it may be required to set security settings for the WSDL2Java emitter. This is especially the case when the remote server is secured using Basic Authentication. Please note the capital "U" and a capital "P" required for these options:

%JDK_HOME%\bin\java org.apache.axis.wsdl.WSDL2Java -o
        <Output-folder> -p <Package-name> -U
        <Username> -P <Password>
        <WSDL-URI>

<Username>, <Password>: valid set of credentials for Basic Authentication.

[Top]

Overview of the Generated Code

For any given CAA Web service, the WSDL2Java emitter produces the following output:

XXX.java (Java interface) and XXXBindingStub.java (Java class) where XXX is the name of the CAA Web service interface:
- The former describes all the methods and parameters available on the remote CAA Web service,
- The latter acts as the proxy that is instantiated in order to remotely invoke methods through SOAP requests,
- At generation, the XXX and XXXBinding values are computed from the WSDL interface document content: XXX matches the name attribute value of the <wsdl:portType> element and XXXBinding matches the name attribute value of the <wsdl:binding> element.
YYY.java (Java interface) and YYYLocator.java (Java class) where YYY is the name of the CAA Web service implementation:
- These resources are only emitted when using a WSDL implementation document as input,
- The YYYLocator class defines getYYYPort() methods that can be used to retrieve an instance of the XXXBindingStub class,
- The YYYLocator class contains the hard-coded value of the SOAP endpoint URI. It can be used to retrieve an instance of the XXXBindingStub class that automatically bounds to a deployed implementation of the target CAA Web service,
- At generation, the YYY and YYYPort values are computed from the WSDL implementation document content: YYY matches the name attribute value of the <wsdl:service> element and YYYPort matches the name attribute value of the <wsdl:port> element.
Several ZZZ.java (Java class) and ZZZHolder.java (Java class) where ZZZ is the name of a type defined in the <wsdl:types> section of the WSDL interface document:
- Holder classes are only generated whenever it is required to emulate out or in/out parameters, based on the operation signatures defined in the input WSDL document. WSDL interface documents for CAA Web services only declare in or in/out parameters,
- A ZZZHolder class contains a reference to an instance of the ZZZ type, this reference will be set to the appropriate value when returning from the method call.

If using a WSDL interface document as input, you need to directly instantiate the XXXBindingStub class (that stands for the proxy to the remote CAA Web service). It is not considered as the appropriate approach in the Axis User's Guide (yet not forbidden). You should rather instantiate the YYYLocator class instead. You can then use one of the getYYYPort method signatures to retrieve a reference to an instance of the XXXBindingStub class through its XXX interface.

It is strongly recommended that you use the getYYYPort method signature that has the SOAP endpoint URI value as parameter. When using the getYYYPort method signature that takes no parameter, the SOAP endpoint URI value is retrieved from an hard-coded string that is generated inside the YYYLocator class. It may create issues to rely on such behavior in your client application. For instance, you may use a testing application server at development stage, but then deploy the CAA Web service to another application server in a production environment. In this scenario, the hard-coded SOAP endpoint URI will no longer bound to the right application server.

The recommended approaches are demonstrated in the related use cases describing how to consume CAA Web services using the Axis SOAP runtime.

The following UML class diagram depicts the relationships between the generated interfaces and classes mentioned above:

Fig.1: Java Client Binding UML Diagram

Please refer to the Axis User's Guide for a detailed description of how the content of the WSDL and XSD definitions are mapped to Java resources. The Axis 1.3 User's Guide can be accessed at the following location: <Axis-unzipped-folder>\axis-1_3\docs\index.html.

It contains the following sections that may be useful to the reader:

"WSDL2Java: Building stubs, skeletons, and data types from WSDL": describes the generated Java client binding based on each element found in the input WSDL document,
"XML <-> Java Data Mapping in Axis": describes how XML types are mapped to Java types.

[Top]

In Short

A Java client binding can be generated for CAA Web services using the Axis WSDL2Java emitter. You can provide as input either a WSDL interface document or a WSDL implementation document. The use of the WSDL implementation document is recommended as it provides extra generated resources and better complies with the Axis User's Guide recommendations. Using the WSDL interface document may only be required when the CAA Web services have not yet been deployed to a target application server by the time the Java client binding must be generated.

The generated Java client bindings can then later be used to consume the related CAA Web service implementations that have been deployed on a target application server. For more details, please refer to the use cases describing how to consume the CAA Web services you wish to use.

[Top]

References

[1]	CAA Web Services and WSDL Definitions
[2]	Axis Java
[3]	Xerces2 Java Parser
[4]	WSDL Interface Documents
[5]	WSDL Implementation Documents
[Top]

History

Version: 1 [Apr 2005]	Document created
Version: 2 [Jan 2006]	Document updated
[Top]

CAA Web Services Home