Working with Dispatch Objects - 6.1

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

To create a Dispatch object do the following:

The following table describes the parameters for createDispatch() .

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

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

The code below 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);

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

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

void invokeOneWay(T msg)
throws WebServiceException;

// Creating a JAXBContext and an Unmarshaller for the request
JAXBContext jbc = JAXBContext.newInstance("org.mycompany.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);