Chapter 41. Using Raw XML Messages

Dispatch objects have two usage modes:

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

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 must provide the Dispatch object’s invoke() method a fully specified SOAP message. The invoke() method also returns 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 working with JAXB objects.

To specify that a Dispatch object uses message mode provide the value java.xml.ws.Service.Mode.MESSAGE when creating the Dispatch object. For more information about creating a Dispatch object see the section called “Creating a Dispatch object”.

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 the invoke() method 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 Apache CXF XML binding, payload mode and message mode provide the same results.

To specify that a Dispatch object uses payload mode provide the value java.xml.ws.Service.Mode.PAYLOAD when creating the Dispatch object. For more information about creating a Dispatch object see the section called “Creating a Dispatch object”.

Because Dispatch objects are low-level objects, they 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:

A Dispatch object accepts and returns objects that are derived from the javax.xml.transform.Source interface. Source objects are supported by any binding, and in either message mode or payload mode.

Source objects are low level objects that hold XML documents. Each Source implementation provides methods that access the stored XML documents and then manipulate its contents. The following objects implement the Source interface:

If you create your Dispatch object so that it uses generic Source objects, Apache CXF returns the messages as SAXSource objects.

This behavior can be changed using the endpoint’s source-preferred-format property. See Part IV, “Configuring Web Service Endpoints” for information about configuring the Apache CXF runtime.

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

A SOAPMessage object holds a SOAP message. They contain one SOAPPart object and zero or more AttachmentPart objects. The SOAPPart object contains the SOAP specific portions of the SOAP message including the SOAP envelope, any SOAP headers, and the SOAP message body. The AttachmentPart objects contain binary data that is passed as an attachment.

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

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

While Dispatch objects are intended to be low level APIs that allow 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 can 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.

For information on creating a JAXBContext object see Chapter 39, Using A JAXBContext Object.

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

To create a Dispatch object do the following:

Example 41.2, “Creating a Dispatch Object” shows the code for creating a Dispatch object that works with DOMSource objects in payload mode.

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);
    ...

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:

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

For consumers that make synchronous invocations that generate a response, use the Dispatch object’s invoke() method shown in Example 41.3, “The Dispatch.invoke() Method”.

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.

Example 41.4, “Making a Synchronous Invocation Using a Dispatch Object” shows code for making 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);

Dispatch objects also support asynchronous invocations. As with the higher level asynchronous APIs discussed in Chapter 40, 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 41.5, “The Dispatch.invokeAsync() Method for Polling” shows the signature of the method used to make an asynchronous invocation using the polling approach.

For detailed information on using the polling approach for asynchronous invocations see Section 40.4, “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 41.6, “The Dispatch.invokeAsync() Method Using a Callback” shows the signature of the method used to make an asynchronous invocation using the callback approach.

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

When a request does not generate a response, make remote invocations using the Dispatch object’s invokeOneWay(). Example 41.7, “The Dispatch.invokeOneWay() Method” shows the signature for this method.

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.

Example 41.8, “Making a One Way Invocation Using a Dispatch Object” shows code for making a oneway 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);

Objects that implement the Provider interface have two messaging modes:

The messaging mode you specify determines the level of messaging detail that is passed to your implementation.

When using message mode, a Provider implementation works with complete messages. A complete message includes any binding specific headers and wrappers. For example, a Provider implementation that uses a SOAP binding receives requests as fully specified SOAP message. Any response returned from the implementation must be a fully specified SOAP message.

To specify that a Provider implementation uses message mode by provide the value java.xml.ws.Service.Mode.MESSAGE as the value to the javax.xml.ws.ServiceMode annotation, as shown in Example 41.9, “Specifying that a Provider Implementation Uses Message Mode”.

@WebServiceProvider
@ServiceMode(value=Service.Mode.MESSAGE)
public class stockQuoteProvider implements Provider<SOAPMessage>
{
  ...
}

In payload mode a Provider implementation works with only the payload of a message. For example, a Provider implementation working in payload mode works only with the body of a SOAP message. The binding layer processes any binding level wrappers and headers.

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

To specify that a Provider implementation uses payload mode by provide the value java.xml.ws.Service.Mode.PAYLOAD as the value to the javax.xml.ws.ServiceMode annotation, as shown in Example 41.10, “Specifying that a Provider Implementation Uses Payload Mode”.

@WebServiceProvider
@ServiceMode(value=Service.Mode.PAYLOAD)
public class stockQuoteProvider implements Provider<DOMSource>
{
  ...
}

If you do not provide a value for the @ServiceMode annotation, the Provider implementation uses payload mode.

Because they are low-level objects, Provider implementations cannot use the same JAXB generated types as the higher level consumer APIs. Provider implementations work with the following types of objects:

A Provider implementation 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:

If you create your Provider object so that it uses generic Source objects, Apache CXF returns the messages as SAXSource objects.

This behavior can be changed using the endpoint’s source-preferred-format property. See Part IV, “Configuring Web Service Endpoints” for information about configuring the Apache CXF runtime.

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

A SOAPMessage object holds a SOAP message. They contain one SOAPPart object and zero or more AttachmentPart objects. The SOAPPart object contains the SOAP specific portions of the SOAP message including the SOAP envelope, any SOAP headers, and the SOAP message body. The AttachmentPart objects contain binary data that is passed as an attachment.

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

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

The Provider interface is relatively easy to implement. It only has one method, invoke(), that must be implemented. In addition it has three simple requirements:

The complexity of implementing the Provider interface is in the logic handling the request messages and building the proper responses.

Unlike the higher-level SEI based service implementations, Provider implementations receive requests as raw XML data, and must send responses as raw XML data. This requires that the developer has intimate knowledge of the messages used by the service being implemented. These details can typically be found in the WSDL document describing the service.

WS-I Basic Profile provides guidelines about the messages used by services, including:

To be recognized by JAX-WS as a service implementation, a Provider implementation must be decorated with the @WebServiceProvider annotation.

Table 41.2, “@WebServiceProvider Properties” describes the properties that can be set for the @WebServiceProvider annotation.

All of these properties are optional, and are empty by default. If you leave them empty, Apache CXF creates values using information from the implementation class.

The Provider interface has only one method, invoke(), that must be implemented. The invoke() method receives the incoming request packaged into the type of object declared by the type of Provider interface being implemented, and returns the response message packaged into the same type of object. For example, an implementation of a Provider<SOAPMessage> interface receives the request as a SOAPMessage object and returns the response as a SOAPMessage object.

The messaging mode used by the Provider implementation determines the amount of binding specific information the request and the response messages contain. Implementations using message mode receive all of the binding specific wrappers and headers along with the request. They must also add all of the binding specific wrappers and headers to the response message. Implementations using payload mode only receive the body of the request. The XML document returned by an implementation using payload mode is placed into the body of the request message.

Example 41.11, “Provider<SOAPMessage> Implementation” shows a Provider implementation that works with SOAPMessage objects in message mode.

import javax.xml.ws.Provider;
import javax.xml.ws.Service;
import javax.xml.ws.ServiceMode;
import javax.xml.ws.WebServiceProvider;

@WebServiceProvider(portName="stockQuoteReporterPort"
                    serviceName="stockQuoteReporter")
@ServiceMode(value="Service.Mode.MESSAGE")
public class  stockQuoteReporterProvider implements Provider<SOAPMessage>
{
public stockQuoteReporterProvider()
  {
  }

public SOAPMessage invoke(SOAPMessage request)
  {
  SOAPBody requestBody = request.getSOAPBody();
  if(requestBody.getElementName.getLocalName.equals("getStockPrice"))
    {
    MessageFactory mf = MessageFactory.newInstance();
      SOAPFactory sf = SOAPFactory.newInstance();

    SOAPMessage response = mf.createMessage();
      SOAPBody respBody = response.getSOAPBody();
      Name bodyName = sf.createName("getStockPriceResponse");
      respBody.addBodyElement(bodyName);
      SOAPElement respContent = respBody.addChildElement("price");
      respContent.setValue("123.00");
      response.saveChanges();
    return response;
    }
    ...
  }
}

The code in Example 41.11, “Provider<SOAPMessage> Implementation” does the following:

Specifies that the following class implements a Provider object that implements the service whose wsdl:service element is named stockQuoteReporter, and whose wsdl:port element is named stockQuoteReporterPort.

Specifies that this Provider implementation uses message mode.

Provides the required default public constructor.

Provides an implementation of the invoke() method that takes a SOAPMessage object and returns a SOAPMessage object.

Extracts the request message from the body of the incoming SOAP message.

Checks the root element of the request message to determine how to process the request.

Creates the factories required for building the response.

Builds the SOAP message for the response.

Returns the response as a SOAPMessage object.

Example 41.12, “Provider<DOMSource> Implementation” shows an example of a Provider implementation using DOMSource objects in payload mode.

import javax.xml.ws.Provider;
import javax.xml.ws.Service;
import javax.xml.ws.ServiceMode;
import javax.xml.ws.WebServiceProvider;

@WebServiceProvider(portName="stockQuoteReporterPort" serviceName="stockQuoteReporter")
@ServiceMode(value="Service.Mode.PAYLOAD")
public class  stockQuoteReporterProvider implements Provider<DOMSource>
public stockQuoteReporterProvider()
  {
  }

public DOMSource invoke(DOMSource request)
  {
    DOMSource response = new DOMSource();
    ...
    return response;
  }
}

The code in Example 41.12, “Provider<DOMSource> Implementation” does the following:

Specifies that the class implements a Provider object that implements the service whose wsdl:service element is named stockQuoteReporter, and whose wsdl:port element is named stockQuoteReporterPort.

Specifies that this Provider implementation uses payload mode.

Provides the required default public constructor.

Provides an implementation of the invoke() method that takes a DOMSource object and returns a DOMSource object.