Develop a dynamic client using JAX-WS APIs

JAX-WS provides support for the dynamic invocation of service endpoint operations.

JAX-WS provides a new dynamic Dispatch client API that is more generic and offers more flexibility than the existing JAX-RPC-based Dynamic Invocation Interface (DII). The Dispatch client interface, javax.xml.ws.Dispatch, is an XML messaging oriented client that is intended for advanced XML developers who prefer to work at the XML level using XML constructs. To write a Dispatch client, have expertise with the Dispatch client APIs, the supported object types, and knowledge of the message representations for the associated Web Services Description Language (WSDL) file.

The Dispatch API can send data in either PAYLOAD or MESSAGE mode. When using the PAYLOAD mode, the Dispatch client is only responsible for providing the contents of the <soap:Body> and JAX-WS includes the input payload in a <soap:Envelope> element. When using the MESSAGE mode, the Dispatch client is responsible for providing the entire SOAP envelope. The Dispatch client API requires application clients to construct messages or payloads as XML and requires a detailed knowledge of the message or message payload. The Dispatch client can use HTTP bindings when using Source objects, JAXB objects, or data source objects. The Dispatch client supports the following types of objects:

• javax.xml.transform.Source: Use Source objects to enable clients to use XML APIs directly. Use Source objects with SOAP and HTTP bindings.
• JAXB objects: Use JAXB objects so that clients can use JAXB objects that are generated from an XML schema to create and manipulate XML with JAX-WS applications. JAXB objects can only be used with SOAP and HTTP bindings.

• javax.xml.soap.SOAPMessage: Use SOAPMessage objects so that clients can work with SOAP messages. We can only use SOAPMessage objects with SOAP version 1.1 or SOAP version 1.2 bindings.

• javax.activation.DataSource: Use DataSource objects so that clients can work with Multipurpose Internet Mail Extension (MIME) messages. Use DataSource only with HTTP bindings.

The Dispatch API uses the concept of generics that are introduced in Java SE Runtime Environment (JRE) 6. For each of the invoke() methods on the Dispatch interface, generics are used to determine the return type.

 

1. Determine if we want the dynamic client to send data in PAYLOAD or MESSAGE mode.

2. Create a service instance and add at least one port to it.

   The port carries the protocol binding and service endpoint address information.

3. Create a Dispatch<T> object using either the Service.Mode.PAYLOAD method or the Service.Mode.MESSAGE method.

4. Set the request context properties on the javax.xml.ws.BindingProvider interface. Use the request context to specify additional properties such as enabling HTTP authentication or specifying the endpoint address.

5. Compose the client request message for the dynamic client.

6. Invoke the service endpoint with the Dispatch client either synchronously or asynchronously.

7. Process the response message from the service.

 

Results

we have developed a dynamic JAX-WS client using the Dispatch API. Refer to Chapter 4, section 3 of the JAX-WS 2.0 spec for more information on using a Dispatch client.

 

Example

The following example illustrates the steps to create a Dispatch client and invoke a sample EchoService service endpoint.

String endpointUrl = ...;
    
QName serviceName = new QName("http://com/ibm/was/wssample/echo/",  "EchoService");
QName portName = new QName("http://com/ibm/was/wssample/echo/",  "EchoServicePort");
    
/** Create a service and add at least one port to it. **/  
Service service = Service.create(serviceName);
 service.addPort(portName, SOAPBinding.SOAP11HTTP_BINDING, endpointUrl);
    
/** Create a Dispatch instance from a service.**/  

Dispatch<SOAPMessage>
 dispatch = service.createDispatch(portName,  SOAPMessage.class, Service.Mode.MESSAGE);
  
/** Create SOAPMessage request. **/

// compose a request message 

MessageFactory mf = MessageFactory.newInstance(SOAPConstants.SOAP_1_1_PROTOCOL);


// Create a message.  This example works with the SOAPPART. 

SOAPMessage request = mf.createMessage();
 SOAPPart part = request.getSOAPPart();


// Obtain the SOAPEnvelope and header and body elements. 

SOAPEnvelope env = part.getEnvelope();
 SOAPHeader header = env.getHeader();
 SOAPBody body = env.getBody();


// Construct the message payload. 

SOAPElement operation = body.addChildElement("invoke", "ns1",  "http://com/ibm/was/wssample/echo/");
SOAPElement value = operation.addChildElement("arg0");
value.addTextNode("ping");
request.saveChanges();

/** Invoke the service endpoint. **/ 

SOAPMessage response = dispatch.invoke(request);

/** Process the response. **/

JAX-WS
JAX-WS client model

 

Related tasks

Implementing JAX-WS Web services clients
Develop a JAX-WS client from a WSDL file
Invoking JAX-WS Web services asynchronously
Develop a JAX-WS service endpoint implementation with annotations

 

Related

Web services specifications and APIs

 

Related information

Java API for XML Web Services (JAX-WS) API documentation
Java API for XML Web Services (JAX-WS) API User's Guide documentation