Working with Dispatch Objects

Procedure

About this task

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

Procedure

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

Creating a Dispatch object

About this task

To create a Dispatch object do the following:

Procedure

Create a Service object to represent the wsdl:service element defining the service on which the Dispatch object will make invocations.

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;

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;

Results

The following table describes the parameters for createDispatch() .

Parameter	Description
portName	Specifies the QName of the wsdl:port element that represent the service provider on which the Dispatch object will make invocations.
type	Specifies the data type of the objects used by the Dispatch object.
mode	Specifies the usage mode for the Dispatch object.

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

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.

Information noteWarning: 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 referred 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.

Information noteNote: 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.

Procedure

About this task

Procedure

Creating a Dispatch object

About this task

Procedure

Results

Constructing request messages

In this section

Did this page help you?