Describe JAX-WS Client Communications Models.

Describe JAX-WS Client Communications Models.
Prev	Chapter 4. JAX-WS	Next


	[NONE] blah

The Java API for XML-Based Web Services (JAX-WS) Web service client programming model supports both the Dispatch client API and the Dynamic Proxy client API. The Dispatch client API is a dynamic client programming model, whereas the static client programming model for JAX-WS is the Dynamic Proxy client. The Dispatch and Dynamic Proxy clients enable both synchronous and asynchronous invocation of JAX-WS Web services.

Dispatch client: Use this client when you want to work at the XML message level or when you want to work without any generated artifacts at the JAX-WS level.
Dynamic Proxy client: Use this client when you want to invoke a Web service based on a service endpoint interface.

Dispatch client

XML-based Web services use XML messages for communications between Web services and Web services clients. The JAX-WS APIs provide high-level methods to simplify and hide the details of converting between Java method invocations and their associated XML messages. However, in some cases, you might desire to work at the XML message level. Support for invoking services at the XML message level is provided by the Dispatch client API.

The Dispatch client API, javax.xml.ws.Dispatch, is a dynamic JAX-WS client programming interface. To write a Dispatch client, you must 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 client can send data in either MESSAGE or PAYLOAD mode.

When using the javax.xml.ws.Service.Mode.MESSAGE mode, the Dispatch client is responsible for providing the entire SOAP envelope including the soap:Envelope, soap:Header, and soap:Body elements.

When using the javax.xml.ws.Service.Mode.PAYLOAD mode, the Dispatch client is only responsible for providing the contents of the soap:Body and JAX-WS includes the payload in a soap:Envelope element.

The Dispatch client API requires application clients to construct messages or payloads as XML which requires a detailed knowledge of the message or message payload. The Dispatch client supports the following types of objects:

javax.xml.transform.Source: Use Source objects to enable clients to use XML APIs directly. You can use Source objects with SOAP or 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 or HTTP bindings.
javax.xml.soap.SOAPMessage: Use SOAPMessage objects so that clients can work with SOAP messages. You can only use SOAPMessage objects with SOAP 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.

For example, if the input parameter type is javax.xml.transform.Source, the call to the Dispatch client API is similar to the following code example:

					
Dispatch<Source> dispatch = ... ; //create a Dispatch<Source>
Source request = ... ; //create a Source object
Source response = dispatch.invoke(request);

The Dispatch parameter value determines the return type of the invoke() method.

The Dispatch client is invoked in one of three ways:

Synchronous invocation for requests and responses using the invoke method
Asynchronous invocation for requests and responses using the invokeAsync method with a callback or polling object
One-way invocation using the invokeOneWay methods

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

Synchronous, Payload-Oriented


Source reqMsg = ...;
Service service = ...;
Dispatch<Source> disp = service.createDispatch(portName, Source.class, PAYLOAD);
Source resMsg = disp.invoke(reqMsg);

Synchronous, Message-Oriented


SOAPMessage soapReqMsg = ...;
Service service = ...;
Dispatch<SOAPMessage> disp = service.createDispatch(portName, SOAPMessage.class, MESSAGE);
SOAPMessage soapResMsg = disp.invoke(soapReqMsg);

Synchronous, Payload-Oriented With JAXB Objects


JAXBContext jc = JAXBContext.newInstance("primer.po");
Unmarshaller u = jc.createUnmarshaller();
PurchaseOrder po = (PurchaseOrder)u.unmarshal(new FileInputStream("po.xml"));
Service service = ...;
Dispatch<Object> disp = service.createDispatch(portName, jc, PAYLOAD);
OrderConfirmation conf = (OrderConfirmation)disp.invoke(po);

Asynchronous, Polling, Message-Oriented


SOAPMessage soapReqMsg = ...;
Service service = ...;
Dispatch<SOAPMessage> disp = service.createDispatch(portName, SOAPMessage.class, MESSAGE);
Response<SOAPMessage> res = disp.invokeAsync(soapReqMsg);
while (!res.isDone()) {
  // do something while we wait
}
SOAPMessage soapResMsg = res.get();

Asynchronous, Callback, Payload-Oriented


class MyHandler implements AsyncHandler<Source> {
  ...
  public void handleResponse(Response<Source> res) {
    Source resMsg = res.get();
    // do something with the results
  }
}

Source reqMsg = ...;
Service service = ...;
Dispatch<Source> disp = service.createDispatch(portName, Source.class, PAYLOAD);
MyHandler handler = new MyHandler();
disp.invokeAsync(reqMsg, handler);

Dynamic Proxy client

The static client programming model for JAX-WS is the called the Dynamic Proxy client. The Dynamic Proxy client invokes a Web service based on a Service Endpoint Interface (SEI) which must be provided. The Dynamic Proxy client is similar to the stub client in the Java API for XML-based RPC (JAX-RPC) programming model. Although the JAX-WS Dynamic Proxy client and the JAX-RPC stub client are both based on the Service Endpoint Interface (SEI) that is generated from a WSDL file , there is a major difference. The Dynamic Proxy client is dynamically generated at run time using the Java 5 Dynamic Proxy functionality, while the JAX-RPC-based stub client is a non-portable Java file that is generated by tooling. Unlike the JAX-RPC stub clients, the Dynamic Proxy client does not require you to regenerate a stub prior to running the client on an application server for a different vendor because the generated interface does not require the specific vendor information.

The Dynamic Proxy instances extend the java.lang.reflect.Proxy class and leverage the Dynamic Proxy function in the base Java Runtime Environment Version 5. The client application can then provide an interface that is used to create the proxy instance while the runtime is responsible for dynamically creating a Java object that represents the SEI.

The following example shows the use of a proxy to invoke a method (getLastTradePrice) on a service endpoint interface (com.example.StockQuoteProvider). Note that no statically generated stub class is involved.


javax.xml.ws.Service service = ... ;
com.example.StockQuoteProvider proxy = service.getPort(portName, com.example.StockQuoteProvider.class);
javax.xml.ws.BindingProvider bp = (javax.xml.ws.BindingProvider)proxy;
Map<String,Object> context = bp.getRequestContext();
context.setProperty("javax.xml.ws.session.maintain", Boolean.TRUE);
proxy.getLastTradePrice("ACME");

Prev	Up	Next
Describe creating a Web Service using JAX-WS.	Home	Given a set of requirements, design and develop a Web service client, such as a Java EE client and a stand-alone client, using JAX-WS.