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.
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
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.
You specify that a
Dispatch object uses message mode by providing the value
java.xml.ws.Service.Mode.MESSAGE when creating the 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
invoke() the binding level wrappers and headers are already striped away and only the body of the message is left.
You specify that a
Dispatch object uses payload mode by providing the value
java.xml.ws.Service.Mode.PAYLOAD when creating the
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:
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
Dispatch objects can use
javax.xml.soap.SOAPMessage objects when the following conditions are true:
Dispatchobject is using the SOAP binding.
Dispatchobject is using message mode.
Dispatch objects can use objects that implement the
javax.activation.DataSource interface when the following conditions are true:
Dispatchobject is using the HTTP binding.
Dispatchobject 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
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
To use a Dispatch object to invoke a remote service you do the following:
- Create a
- Construct a request message.
- Call the proper
- Parse the response message.
To create a
Dispatch object do the following:
- Create a
Serviceobject to represent the
wsdl:serviceelement defining the service on which the
Dispatchobject will make invocations.
- Create the
Dispatchobject using the
The following table describes the parameters for
Specifies the QName of the
Specifies the data type of the objects used by the
Specifies the usage mode for the
The code below creates a
Dispatch object that works with
DOMSource objects in payload mode.
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:operationelement that corresponds to the operation being invoked.
- 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.
- 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.
For consumers that make synchronous invocations that generate a response, you use the
invoke() method shown bellow.
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
The code bellow makes a synchronous invocation on a remote service using a
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.
When using the callback approach the
invokeAsync() method takes an
AsyncHandler implementation that processes the response when it is returned.
When a request does not generate a response, you make remote invocations using the
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
The code bellow makes a one way invocation on a remote service using a JAXB object.
When using a
Dispatch client with a WSDL file, the operation name will be set under one of the following cases.
- The javax.xml.ws.handler.MessageContext.WSDL_OPERATION property of the request context is set with the operation QName.
- The addressing feature is enabled (in the bus or at the endpoint) and there is a matching operation to the payload element.
- The "find.dispatch.operation" property of the request context is set to Boolean.TRUE and there is a matching operation to the payload element. This property is not set by default.Determining the correct operation will affect the processing such as setting the correct SOAPAction or WS-Addressing's Action.