+

Search Tips   |   Advanced Search

JAX-WS

JAX-WS uses proxies and annotations to provide an alternative to, JAX-RPC. JAX-WS is part of the industry trend towards a more document-centric messaging model, replacing the remote procedure call programming model as defined by JAX-RPC.

JAX-WS is the strategic programming model for developing web services, and is a required part of the Java EE 6. JAX-WS.

WAS v8.0 supports JAX-WS Version 2.2 (JSR 224) and Web Services for Java EE (JSR 109) Version 1.3 specifications.

JAX-WS 2.2 adds client-side support for using WebServiceFeature-related annotations such as @MTOM, @Addressing, and the @RespectBinding. JAX-WS 2.1 had previously added support for these annotations on the server.

JAX-WS 2.2 adds the ability to configure WS-Addressing support on a client or service by adding WS-Policy assertions into the WSDL document.

The Web Services for Java EE 1.3 specification introduces support for these WebServiceFeature-related annotations, as well as support for using deployment descriptor elements to configure these features on both the client and server.

JAX-WS 2.2 requires JAXB Version 2.2 for data binding.

JAX-WS uses a dynamic proxy to provide a formal delegation model with a pluggable provider. JAX-RPC relies on the generation of vendor-specific stubs for invocation.

JAX-WS supports annotating Java classes with metadata to indicate that the Java class is a Web service.

Support for annotations is based on...

Annotations define information typically specified in deployment descriptor files and WSDL files.

For example, we can embed a simple @WebService tag in the Java source to expose the bean as a web service. 

@WebService 
public class QuoteBean implements StockQuote 
{
    public float getQuote(String sym) {...}
}
The @WebService annotation tells the server runtime environment to expose all public methods on that bean as a web service. Additional levels of granularity can be controlled by adding additional annotations on individual methods or parameters.

Annotations expose Java artifacts as web services. As artifacts are created from using some of the top-down mapping tools starting from a WSDL file, annotations are included within the source and Java classes as a way of capturing the metadata along with the source files.

Using annotations also improves the development of web services within a team structure as we do not need to define every web service in a single or common deployment descriptor as required with JAX-RPC web services. Taking advantage of annotations with JAX-WS web services enables parallel development of the service and the required metadata.

Using a webservices.xml deployment descriptor is optional. We can use webservices.xml to augment or override existing JAX-WS annotations. Any information defined in webservices.xml overrides any corresponding information specified by annotations.

In this case, the value specified in the deployment descriptor, META-INF/wsdl/ExampleService.wsdl overrides the annotation value.


Invoking web services asynchronously

With JAX-WS, Web services are called both synchronously and asynchronously. JAX-WS adds support for both a polling and callback mechanism when calling web services asynchronously. Using a polling model, a client can issue a request, get a response object back, which is polled to determine if the server has responded. When the server responds, the actual response is retrieved. Using the callback model, the client provides a callback handler to accept and process the inbound response object. Both the polling and callback models enable the client to focus on continuing to process work without waiting for a response to return, while providing for a more dynamic and efficient model to invoke Web services.

For example, a web service interface might have methods for both synchronous and asynchronous requests. Asynchronous requests are identified in bold in the following example: 

@WebService
public interface CreditRatingService {
      // sync operation       
      Score getCreditScore(Customer customer);
      // async operation with polling       
      Response<Score> getCreditScoreAsync(Customer customer);
      // async operation with callback
      Future<?> getCreditScoreAsync(Customer customer, 
         AsyncHandler<Score> handler);
}

The asynchronous invocation that uses the callback mechanism requires an additional input by the client programmer. The callback is an object containing the application code that is run when an asynchronous response is received. Use the following code example to invoke an asynchronous callback handler: 

CreditRatingService svc = ...;

Future<?> invocation = svc.getCreditScoreAsync(customerFred, new AsyncHandler<Score>() {
    public void handleResponse (
        Response<Score> response)
      {
        Score score = response.get();
        // do work here...
      }
   }
);

To invoke an asynchronous polling client... 

CreditRatingService svc = ...;
Response<Score> response = svc.getCreditScoreAsync(customerFred);

while (!response.isDone()) 
{
  // Complete an action while we wait.
}

// No cast needed, because of generics.
Score score = response.get();


Use resource injection

Resource injection shifts the burden of creating common resources in a Java runtime environment from the application to the application container,

The application server can use the @Resource or @WebServiceRef annotations to declare JAX-WS managed clients, and injection of services and ports. The type specified by the annotation is bound into the JNDI namespace.

@Resource annotation is defined by the JSR-250 specification, Common Annotations specification included in Java EE 5. Placing @Resource on a variable of type...

...within a service endpoint implementation class allows us to request a resource injection, and collect the interface related to that particular endpoint invocation. From the interface, we can collect the MessageContext using getMessageContext().

@WebServiceRef annotation is defined by the JAX-WS specification.

Use @Resource and @WebServiceRef for resource injection...

Refer to sections 5.2.1 and 5.3 of the JAX-WS specification for more information on resource injection.


Data binding with JAXB 2.2

JAX-WS leverages the JAXB 2.2 API and tools as the binding technology for two-way mappings between Java objects and XML documents. JAX-WS 2.2 requires JAXB 2.2 for data binding. JAXB 2.2 provides improved schema generation.


Dynamic and static clients

The dynamic client API for JAX-WS is called the dispatch client (javax.xml.ws.Dispatch). The dispatch client is an XML messaging oriented client. The data is sent 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 adds the <soap:Envelope> and <soap:Header> elements. When using the MESSAGE mode, the dispatch client is responsible for providing the entire SOAP envelope including the <soap:Envelope>, <soap:Header>, and <soap:Body> elements. JAX-WS does not add anything additional to the message. The dispatch client supports asynchronous invocations using a callback or polling mechanism.

The static client programming model for JAX-WS is the called the proxy client. The proxy client invokes a web service based on a Service Endpoint interface (SEI), which must be provided.


Support for MTOM

We can send binary attachments such as images or files along with web services requests. JAX-WS adds support for optimized transmission of binary data as specified by Message Transmission Optimization Mechanism(MTOM) .


Multiple data binding technologies

JAX-WS exposes the following binding technologies to the end user:

XML Source enables a user to pass a javax.xml.transform.Source into the runtime environment which represents the data in a Source object to be processed. SAAJ 1.3 now has the ability to pass an entire SOAP document across the interface rather than just the payload itself. This action is done by the client passing the SAAJ SOAPMessage object across the interface. JAX-WS leverages the JAXB 2.2 support as the data binding technology of choice between Java and XML.


Support for SOAP 1.2

Support for SOAP 1.2 has been added to JAX-WS 2.0. JAX-WS supports both SOAP 1.1 and SOAP 1.2 so that we can send binary attachments such as images or files along with web services requests. JAX-WS adds support for optimized transmission of binary data as specified by MTOM.


Development tools

JAX-WS provides the wsgen and wsimport command-line tools for generating portable artifacts for JAX-WS web services.

If we start with an implementation bean class, use wsgen to generate server artifacts, including a WSDL file.

If we start with a WSDL file, use wsimport to generate artifacts for either the server or the client. The wsimport tool processes the WSDL file with schema definitions to generate portable artifacts, including the service class, the service endpoint interface class, and the JAXB 2.2 classes for the corresponding XML schema.


Support for Web Services for Java EE, version 1.3

The Web Services for Java EE version 1.3 specification adds support for configuring the MTOM, Addressing, and RespectBinding features on JAX-WS services and clients through the use of both annotations and deployment descriptor entries.


Support for empty targetNamespace for the WRAPPED parameter style and return types

JAX-WS 2.2 supports method parameters and return types. In a JAX-WS web services operation, we can define a web services operation with an operation parameter and an optional return type. If the operation parameter and return type define an empty targetNamespace property by specifying a "" value for the targetNamespace property with either the @WebParam or @WebResult annotation, the JAX-WS runtime environment behaves in the following way:


Subtopics


Related concepts

JAXB
  • Message Transmission Optimization Mechanism
  • Web Services for Java EE specification
  • Enable MTOM for JAX-WS web services
  • Enforcing adherence to WSDL bindings in JAX-WS web services
  • Enable Web Services Addressing support for JAX-WS applications using addressing features
  • Example: Install a web services sample with the console


    Related reference:

  • wsimport command for JAX-WS applications
  • wsgen command for JAX-WS applications
  • Web services specifications and APIs
    JAX-WS API documentation
    JAX-WS API User's Guide documentation
    A Metadata Facility for the Java Programming Language (JSR 175)
    Web Services Metadata for the Java Platform (JSR 181)