10.4.  Use Dispatch API to create a dynamic web service client.

XML web services use XML messages for communication between services and service clients. The higher level JAX-WS APIs are designed to hide the details of converting between Java method invocations and the corresponding XML messages, but in some cases operating at the XML message level is desirable. The javax.xml.ws.Dispatch interface provides support for this mode of interaction.

Dispatch supports two usage modes, identified by the constants javax.xml.ws.Service.Mode.MESSAGE and javax.xml.ws.Service.Mode.PAYLOAD respectively:

Dispatch is a low level API that requires clients to construct messages or message payloads as XML and requires an intimate knowledge of the desired message or payload structure. Dispatch is a generic interface that supports input and output of messages or message payloads of any type. Implementations are required to support the following types of object:

Dispatch instances are obtained using the createDispatch factory methods of a Service instance. The mode parameter of createDispatch controls whether the new Dispatch instance is message or message payload oriented. The type parameter controls the type of object used for messages or message payloads. Dispatch instances are not thread safe.

Dispatch instances are not required to be dynamically configurable for different protocol bindings; the WSDL binding from which the Dispatch instance is generated contains static information including the protocol binding and service endpoint address. However, a Dispatch instance may support configuration of certain aspects of its operation and provides methods (inherited from BindingProvider) to dynamically query and change the values of properties in its request and response contexts.

A Dispatch instance supports three invocation modes:

Dispatch supports two forms of asynchronous invocation:

The following interfaces are used to obtain the results of an operation invocation:

The following examples demonstrate use of Dispatch methods in the synchronous, asynchronous polling, and asynchronous callback modes:

Configuring the client BindingProviders

Both proxy-based clients and dispatch-based clients share a common configuration model. The configuration is performed programmatically in the context of the Java web service client code. By using this configuration, you can specify an explicit endpoint location, HTTP protocol session behavior, HTTP authentication credentials, and more.

The actual programmatic configuration is performed on the javax.xml.ws.BindingProvider client-side object. The dynamic proxies that are generated by the JAX-WS run time implement the javax.xml.ws.BindingProvider interface, where the Dispatch interface extends it. Therefore, dispatch objects produced by the JAX-WS Service class, by contract, also implement the BindingProvider behavior.

To configure the client BindingProvider, you add information to the request context, which is an ordinary java.util.Map<String, Object> that contains the actual configuration. The keys are strings and the values are objects. The map is available by using the BindingProvider.getRequestContext() method.

JAX-WS 2.1 specifies the following standard properties that can be used to configure the request context:

Example below shows how to allow the web service client to participate in web service endpoint initiated sessions:

import java.util.Map;
import by.boot.java.HelloMessenger;
import by.boot.java.HelloMessengerService;
import javax.xml.ws.BindingProvider;
public class HelloClientHttpSession {

    public static void main(String... args) throws Exception {

        // Obtain the dynamic stub from the Service
        HelloMessengerService service = new HelloMessengerService();
        HelloMessenger proxy = service.getHelloMessengerPort();

        // Cast the proxy to a BindingProvider
        BindingProvider bindingProvider = (BindingProvider) proxy;

       // Get the request context
       Map<String, Object> requestContext = bindingProvider.getRequestContext();

       // Configure session preference
       requestContext.put(BindingProvider.SESSION_MAINTAIN_PROPERTY, true);

       // Perform Web service method invocation and print the result
       String message = proxy.sayHello("Mikalai");

Professional hosting         'Oracle Certified Expert Web Services Developer 6' Quiz     Free SCDJWS 5.0 Guide