Usage Modes

Overview

Dispatch objects have two usage modes:

• Message mode
• Message Payload mode (Payload mode)

The usage mode you specify for a Dispatch object determines the amount of detail is passed to the user level code.

Message mode

In message mode, a Dispatch object works with complete messages. A complete message includes any binding specific headers and wrappers. For example, a consumer interacting with a service that requires SOAP messages would need to provide the Dispatch object's invoke() method a fully specified SOAP message. The invoke() method will also return a fully specified SOAP message. The consumer code is responsible for completing and reading the SOAP message's headers and the SOAP message's envelope information.

Message mode is not ideal when you wish to work with JAXB objects.

You specify that a Dispatch object uses message mode by providing the value java.xml.ws.Service.Mode.MESSAGE when creating the Dispatch object.

Payload mode

In payload mode, also called message payload mode, a Dispatch object works with only the payload of a message. For example, a Dispatch object working in payload mode works only with the body of a SOAP message. The binding layer processes any binding level wrappers and headers. When a result is returned from invoke() the binding level wrappers and headers are already striped away and only the body of the message is left.

When working with a binding that does not use special wrappers, such as the Artix ESB XML binding, payload mode and message mode provide the same results.

You specify that a Dispatch object uses payload mode by providing the value java.xml.ws.Service.Mode.PAYLOAD when creating the Dispatch object.

Data Types

Overview

Dispatch objects, because they are low-level objects, are not optimized for using the same JAXB generated types as the higher level consumer APIs. Dispatch objects work with the following types of objects:

• javax.xml.transform.Source
• javax.xml.soap.SOAPMessage
• javax.activation.DataSource
• JAXB

Using Source objects

A Dispatch object can accept and return objects that are derived from the javax.xml.transform.Source interface. Source objects are low level objects that hold XML documents. Each Source implementation provides methods that access the stored XML documents and manipulate its contents. The following objects implement the Source interface:

• DOMSource
• SAXSource
• StreamSource

  When using Source objects the developer is responsible for ensuring that all required binding specific wrappers are added to the message. For example, when interacting with a service expecting SOAP messages, the developer must ensure that the required SOAP envelope is added to the outgoing request and that the SOAP envelope's contents are correct.

Using SOAPMessage objects

Dispatch objects can use javax.xml.soap.SOAPMessage objects when the following conditions are true:

• the Dispatch object is using the SOAP binding.
• the Dispatch object is using message mode.

Using DataSource objects

Dispatch objects can use objects that implement the javax.activation.DataSource interface when the following conditions are true:

• the Dispatch object is using the HTTP binding.
• the Dispatch object is using message mode.

DataSource objects provide a mechanism for working with MIME typed data from a variety of sources including URLs, files, and byte arrays.

Using JAXB objects

While Dispatch objects are intended to be low level API that allows you to work with raw messages, they also allow you to work with JAXB objects. To work with JAXB objects a Dispatch object must be passed a JAXBContext that knows how to marshal and unmarshal the JAXB objects in use. The JAXBContext is passed when the Dispatch object is created.

You can pass any JAXB object understood by the JAXBContext object as the parameter to the invoke() method. You can also cast the returned message into any JAXB object understood by the JAXBContext object.

Working with Dispatch Objects

Procedure

To use a Dispatch object to invoke a remote service you do the following:

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

Creating a Dispatch object

To create a Dispatch object do the following:

1. Create a Service object to represent the wsdl:service element defining the service on which the Dispatch object will make invocations.
2. Create the Dispatch object using the Service object's createDispatch() method.

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

   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;

The following table describes the parameters for createDispatch().

The code bellow creates a Dispatch object that works with DOMSource objects in payload mode.

package com.iona.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 = 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 XMLSchema document that defines the messages. While service providers vary greatly there are a few guidelines that can be followed:

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

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

• The root element of the request will be namespace qualified.
• If the service being invoked uses rpc/literal messages, the top-level elements in the request will not be namespace qualified.

  The children of top-level elements may be namespace qualified. To be certain you will need to 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.

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, you use the Dispatch object's invoke() method shown bellow.

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 created a Dispatch object using createDispatch(portName, SOAPMessage.class, Service.Mode.MESSAGE) the response and the request would both be SOAPMessage objects.

When using JAXB objects, 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.

The code bellow makes a synchronous invocation on a remote service using a DOMSource 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 Chapter 4, 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 periodically polled to see if the response has arrived.

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

When using the callback approach the invokeAsync() method takes an AsyncHandler implementation that processes the response when it is returned.

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

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, you make remote invocations using the Dispatch object's invokeOneWay().

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) the request would be packaged into a DOMSource object.

When using JAXB objects, 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.

The code bellow makes a one way invocation on a remote service using a JAXB 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);