Fuse ESB - Developing Applications Using JAX-WS [DRAFT]

Working with `Dispatch` Objects

Procedure

To use a Dispatch object to invoke a remote service the following sequence should be followed:

Create a Dispatch object.
Construct a request message.
Call the proper invoke() method.
Parse the response message.

Creating a `Dispatch` object

To create a Dispatch object do the following:

Create a Service object to represent the wsdl:service element that defines the service on which the Dispatch object will make invocations. See Creating a Service Object.

Create the Dispatch object using the Service object's createDispatch() method, shown in Example 19.1.

Example 19.1. The createDispatch() Method

public Dispatch<T> createDispatch(QName portName,
                                  java.lang.Class<T> type,
                                  Service.Mode mode)
    throws WebServiceException;

	Note
	If you are using JAXB objects the method signature for `createDispatch()` is: `public Dispatch<T> createDispatch(QName portName, javax.xml.bind.JAXBContext context, Service.Mode mode) throws WebServiceException;`

Table 19.1 describes the parameters for the createDispatch() method.

Table 19.1. Parameters for createDispatch()

Parameter Description

portName Specifies the QName of the wsdl:port element that represents the service provider where the Dispatch object will make invocations.

Parameter	Description
`portName`	Specifies the QName of the `wsdl:port` element that represents the service provider where the `Dispatch` object will make invocations.
`type`	Specifies the data type of the objects used by the `Dispatch` object. See Data Types. When working with JAXB objects, this parameter specifies the `JAXBContext` object used to marshal and unmarshal the JAXB objects.
`mode`	Specifies the usage mode for the `Dispatch` object. See Usage Modes.

type

Specifies the data type of the objects used by the Dispatch object. See Data Types.

When working with JAXB objects, this parameter specifies the JAXBContext object used to marshal and unmarshal the JAXB objects.

mode Specifies the usage mode for the Dispatch object. See Usage Modes.

Example 19.2 shows the code for creating a Dispatch object that works with DOMSource objects in payload mode.

Example 19.2. Creating a Dispatch Object

package com.fusesource.demo;

import javax.xml.namespace.QName;
import javax.xml.ws.Service;

public class Client
{
public static void main(String args[])
  {
    QName serviceName = new QName("http://org.apache.cxf", "stockQuoteReporter");
    Service s = Service.create(serviceName);

    QName portName = new QName("http://org.apache.cxf", "stockQuoteReporterPort");
    Dispatch<DOMSource> dispatch = s.createDispatch(portName,
                                                  DOMSource.class,
                                                  Service.Mode.PAYLOAD);
    ...

Constructing request messages

When working with Dispatch objects, requests must be built from scratch. The developer is responsible for ensuring that the messages passed to a Dispatch object match a request that the targeted service provider can process. This requires precise knowledge about the messages used by the service provider and what, if any, header information it requires.

This information can be provided by a WSDL document or an XML Schema document that defines the messages. While service providers vary greatly there are a few guidelines to be followed:

The root element of the request is based in the value of the name attribute of the wsdl:operation element corresponding to the operation being invoked.

	Warning
	If the service being invoked uses doc/literal bare messages, the root element of the request is based on the value of the `name` attribute of the `wsdl:part` element referred to by the `wsdl:operation` element.

The root element of the request is namespace qualified.
If the service being invoked uses rpc/literal messages, the top-level elements in the request will not be namespace qualified.
Important
The children of top-level elements may be namespace qualified. To be certain you must check their schema definitions.
If the service being invoked uses rpc/literal messages, none of the top-level elements can be null.
If the service being invoked uses doc/literal messages, the schema definition of the message determines if any of the elements are namespace qualified.

	Important
The children of top-level elements may be namespace qualified. To be certain you must check their schema definitions.

For more information about how services use XML messages see, the WS-I Basic Profile.

Synchronous invocation

For consumers that make synchronous invocations that generate a response, use the Dispatch object's invoke() method shown in Example 19.3.

Example 19.3. The Dispatch.invoke() Method

T invoke(T msg)
    throws WebServiceException;

The type of both the response and the request passed to the invoke() method are determined when the Dispatch object is created. For example if you create a Dispatch object using createDispatch(portName, SOAPMessage.class, Service.Mode.MESSAGE), both the response and the request are SOAPMessage objects.

	Note
	When using JAXB objects, both the response and the request can be of any type the provided `JAXBContext` object can marshal and unmarshal. Also, the response and the request can be different JAXB objects.

Example 19.4 shows code for making a synchronous invocation on a remote service using a DOMSource object.

Example 19.4. Making a Synchronous Invocation Using a Dispatch Object

// Creating a DOMSource Object for the request
DocumentBuilder db = DocumentBuilderFactory.newDocumentBuilder();
Document requestDoc = db.newDocument();
Element root = requestDoc.createElementNS("http://org.apache.cxf/stockExample",
                                          "getStockPrice");
root.setNodeValue("DOW");
DOMSource request = new DOMSource(requestDoc);

// Dispatch disp created previously
DOMSource response = disp.invoke(request);

Asynchronous invocation

Dispatch objects also support asynchronous invocations. As with the higher level asynchronous APIs discussed in Developing Asynchronous Applications, Dispatch objects can use both the polling approach and the callback approach.

When using the polling approach, the invokeAsync() method returns a Response<t> object that can be polled to see if the response has arrived. Example 19.5 shows the signature of the method used to make an asynchronous invocation using the polling approach.

Example 19.5. The Dispatch.invokeAsync() Method for Polling

Response <T> invokeAsync(T msg)
    throws WebServiceException;

For detailed information on using the polling approach for asynchronous invocations see Implementing an Asynchronous Client with the Polling Approach.

When using the callback approach, the invokeAsync() method takes an AsyncHandler implementation that processes the response when it is returned. Example 19.6 shows the signature of the method used to make an asynchronous invocation using the callback approach.

Example 19.6. The Dispatch.invokeAsync() Method Using a Callback

Future<?> invokeAsync(T msg,
                      AsyncHandler<T> handler)
    throws WebServiceException;

For detailed information on using the callback approach for asynchronous invocations see Implementing an Asynchronous Client with the Callback Approach.

	Note
	As with the synchronous `invoke()` method, the type of the response and the type of the request are determined when you create the `Dispatch` object.

Oneway invocation

When a request does not generate a response, make remote invocations using the Dispatch object's invokeOneWay(). Example 19.7 shows the signature for this method.

Example 19.7. The Dispatch.invokeOneWay() Method

void invokeOneWay(T msg)
    throws WebServiceException;

The type of object used to package the request is determined when the Dispatch object is created. For example if the Dispatch object is created using createDispatch(portName, DOMSource.class, Service.Mode.PAYLOAD), then the request is packaged into a DOMSource object.

	Note
	When using JAXB objects, the response and the request can be of any type the provided `JAXBContext` object can marshal and unmarshal.

Example 19.8 shows code for making a oneway invocation on a remote service using a JAXB object.

Example 19.8. Making a One Way Invocation Using a Dispatch Object

// Creating a JAXBContext and an Unmarshaller for the request
JAXBContext jbc = JAXBContext.newInstance("org.apache.cxf.StockExample");
Unmarshaller u = jbc.createUnmarshaller();

// Read the request from disk
File rf = new File("request.xml");
GetStockPrice request = (GetStockPrice)u.unmarshal(rf);

// Dispatch disp created previously
disp.invokeOneWay(request);