CHAPTER 1: Developing a Consumer with Celtix

Generating the Stub Code

The starting point for developing a service consumer (or client) in Celtix is a WSDL contract, complete with port type, binding, and service definitions. You can then use the wsdl2java utility to generate the Java stub code from the WSDL contract. The stub code provides the supporting code that is required to invoke operations on the remote service.

For Celtix clients, the wsdl2java utility can generate the following kinds of code:

• Stub code — supporting files for implementing a Celtix client.

• Client starting point code — sample client code that connects to the remote service and invokes every operation on the remote service.

• Ant build file — a build.xml file intended for use with the ant build utility. It has targets for building and for running the sample client application.

Basic HelloWorld WSDL contract

Listing 1 shows the HelloWorld WSDL contract. This contract defines a single port type, Greeter, with a SOAP binding, Greeter_SOAPBinding, and a service, SOAPService, which has a single port, SoapPort.

Listing 1: HelloWorld WSDL Contract

The Greeter port type from Listing 1 defines the following WSDL operations:

• sayHi — has a single output parameter, of xsd:string type.

• greetMe — has an input parameter, of xsd:string type, and an output parameter, of xsd:string type.

• greetMeOneWay — has a single input parameter, of xsd:string type. Because this operation has no output parameters, Celtix can optimize this call to be a oneway invocation (that is, the client does not wait for a response from the server).

• pingMe — has no input parameters and no output parameters, but it can raise a fault exception.

Listing 1 also defines a binding, Greeter_SOAPBinding, for the SOAP protocol. In practice, the binding is normally generated automatically — for example, by running either of the Celtix wsdl2soap or wsdl2xml utilities. Likewise, the SOAPService service can be generated automatically by running the Celtix wsdl2service utility.

Generating the Stub Code

After defining the WSDL contract, you can generate client code using the Celtix wsdl2java utility. Enter the following command at a command-line prompt:

wsdl2java -ant -client -d ClientDir hello_world.wsdl

Where ClientDir is the location of a directory where you would like to put the generated files and hello_world.wsdl is a file containing the contract shown in Listing 1. The -ant option generates an ant build.xml file, for use with the ant build utility. The -client option generates starting point code for a client main() function.

The preceding wsdl2java command generates the following Java packages:

• org.objectweb.hello_world_soap_http

This package name is generated from the http://objectweb.org/hello_world_soap_http target namespace. All of the WSDL entities defined in this target namespace (for example, the Greeter port type and the SOAPService service) map to Java classes in the corresponding Java package.

• org.objectweb.hello_world_soap_http.types

This package name is generated from the http://objectweb.org/hello_world_soap_http/types target namespace. All of the XML types defined in this target namespace (that is, everything defined in the wsdl:types element of the HelloWorld contract) map to Java classes in the corresponding Java package.

The stub files generated by the wsdl2java command fall into the following categories:

• Classes representing WSDL entities (in the org.objectweb.hello_world_soap_http package) — the following classes are generated to represent WSDL entities:

• Greeter is a Java interface that represents the Greeter WSDL port type. In JAX-WS terminology, this Java interface is a service endpoint interface.

• SOAPService is a Java class that represents the SOAPService WSDL service element.

• PingMeFault is a Java exception class (extending java.lang.Exception) that represents the pingMeFault WSDL fault element.

• Classes representing XML types (in the org.objectweb.hello_world_soap_http.types package) — in the HelloWorld example, the only generated types are the various wrappers for the request and reply messages. Some of these data types are useful for the asynchronous invocation model.

Implementing a Celtix Client

This section describes how to write the code for a simple Java client, based on the WSDL contract from Listing 1. To implement the client, you need to use the following stub classes:

• Service class (that is, SOAPService).

• Service endpoint interface (that is, Greeter).

Generated Service Class

Listing 2 shows the typical outline a generated service class, ServiceName, which extends the javax.xml.ws.Service base class.

Listing 2: Outline of a Generated Service Class

The ServiceName class in Listing 2 defines the following methods:

• Constructor methods — the following forms of constructor are defined:

• ServiceName(URL wsdlLocation, QName serviceName) constructs a service object based on the data in the serviceName service in the WSDL contract that is obtainable from wsdlLocation.

• ServiceName() is the default constructor, which constructs a service object based on the service name and WSDL contract that were provided at the time the stub code was generated (for example, when running the Celtix wsdl2java command). Using this constructor presupposes that the WSDL contract remains available at its original location.

• getPortName() methods — for every PortName port defined on the ServiceName service, Celtix generates a corresponding getPortName() method in Java. Therefore, a wsdl:service element that defines multiple ports will generate a service class with multiple getPortName() methods.

Service Endpoint Interface

For every port type defined in the original WSDL contract, you can generate a corresponding service endpoint interface in Java. A service endpoint interface is the Java mapping of a WSDL port type. Each operation defined in the original WSDL port type maps to a corresponding method in the service endpoint interface. The operation's parameters are mapped as follows:

• The input parameters are mapped to method arguments.

• The first output parameter is mapped to a return value.

• If there is more than one output parameter, the second and subsequent output parameters map to method arguments (moreover, the values of these arguments must be passed using Holder types).

For example, Listing 3 shows the Greeter service endpoint interface, which is generated from the Greeter port type defined in Listing 1. For simplicity, Listing 3 omits the standard JAXB and JAX-WS annotations.

Listing 3: The Greeter Service Endpoint Interface

Client Main Function

Listing 4 shows the Java code that implements the HelloWorld client. In summary, the client connects to the SoapPort port on the SOAPService service and then proceeds to invoke each of the operations supported by the Greeter port type.

Listing 4: Client Implementation Code

The Client.main() function from Listing 4 proceeds as follows:

• The Celtix runtime is implicitly initialized — that is, provided the Celtix runtime classes are loaded. Hence, there is no need to call a special function in order to initialize Celtix.

• The client expects a single string argument that gives the location of the WSDL contract for HelloWorld. The WSDL location is stored in the variable, wsdlURL.

• A new port object (which enables you to access the remote server endpoint) is created in two steps, as shown in the following code fragment:

To create a new port object, you first create a service object (passing in the WSDL location and service name) and then call the appropriate getPortName() method to obtain an instance of the particular port you need. In this case, the SOAPService service supports only the SoapPort port, which is of Greeter type.

• The client proceeds to call each of the methods supported by the Greeter service endpoint interface.

• In the case of the pingMe() operation, the example code shows how to catch the PingMeFault fault exception.

Setting Connection Properties with Contexts

You can use JAX-WS contexts to customize the properties of a client proxy. In particular, contexts can be used to modify connection properties and to send data in protocol headers. For example, you could use contexts to add a SOAP header, either to a request message or to a response message. The following types of context are supported on the client side:

• Request context — on the client side, the request context enables you to set properties that affect outbound messages. Request context properties are applied to a specific port instance and, once set, the properties affect every subsequent operation invocation made on the port, until such time as a property is explicitly cleared. For example, you might use a request context property to set a connection timeout or to initialize data for sending in a header.

• Response context — on the client side, you can access the response context to read the property values set by the inbound message from the last operation invocation. Response context properties are reset after every operation invocation. For example, you might access a response context property to read header information received from the last inbound message.

Setting a Request Context

To set a particular request context property, ContextPropertyName, to the value, PropertyValue, use the code shown in Listing 5.

Listing 5: Setting a Request Context Property on the Client Side

You have to cast the port object to javax.xml.ws.BindingProvider type in order to access the request context. The request context itself is of type, java.util.Map<String, Object>, which is a hash map that has keys of String type and values of arbitrary type. Use the java.util.Map.put() method to create a new entry in the hash map.

Reading a Response Context

To retrieve a particular response context property, ContextPropertyName, use the code shown in Listing 6.

Listing 6: Reading a Response Context Property on the Client Side

The response context is of type, java.util.Map<String, Object>, which is a hash map that has keys of String type and values of arbitrary type. Use the java.util.Map.get() method to access an entry in the hash map of response context properties.

Contexts Supported by Celtix

Celtix supports the following context properties:

Table 1: Celtix Context Properties

Asynchronous Invocation Model

In addition to the usual synchronous mode of invocation, Celtix also supports two forms of asynchronous invocation, as follows:

• Polling approach — in this case, to invoke the remote operation, you call a special method that has no output parameters, but returns a javax.xml.ws.Response instance. The Response object (which inherits from the javax.util.concurrency.Future interface) can be polled to check whether or not a response message has arrived.

• Callback approach — in this case, to invoke the remote operation, you call another special method that takes a reference to a callback object (of javax.xml.ws.AsyncHandler type) as one of its parameters. Whenever the response message arrives at the client, the Celtix runtime calls back on the AsyncHandler object to give it the contents of the response message.

Both of these asynchronous invocation approaches are described here and illustrated by code examples.

WSDL Contract for Asynchronous Example

Listing 7 shows the WSDL contract that is used for the asynchronous example. The contract defines a single port type, GreeterAsync, which contains a single operation, greetMeSometime.