JAX-WS

 

+

Search Tips   |   Advanced Search

 

Overview

Java API for XML-Based Web Services (JAX-WS), also known as JSR 224, is the next generation Web services model complimenting the foundation provided by JAX-RPC.

JAX-WS supports dynamic proxies and Java annotations.

JAX-WS replaces the remote procedure call model as defined by JAX-RPC. While JAX-RPC applications are still supported by WAS v7, JAX-RPC has limitations and does not support various complex document-centric services.

WAS v7.0 supports JAX-WS 2.1, which supports WS-Addressing, allowing us to create, transmit and use endpoint references to target a Web service endpoint. Use WS-Addressing to specify the action URIs associated with the WSDL operations of the Web service.

JAX-WS 2.1 introduces the concept of features as a way to programmatically control specific functions and behaviors. There are three standard features:

• AddressingFeature for WS-Addressing
• MTOMFeature when optimizing the transmission of binary attachments
• RespectBindingFeature for wsdl:binding extensions

JAX-WS 2.1 requires JAXB v2.1 for data binding

The implementation of the JAX-WS programming standard provides the following enhancements for developing Web services and clients:

 

Better platform independence for Java applications

JAX-WS takes advantage of the dynamic proxy mechanism to provide a formal delegation model with a pluggable provider.

This is an enhancement over JAX-RPC, which relies on the generation of vendor-specific stubs for invocation.

 

Annotations

JAX-WS introduces support for annotating Java classes with metadata to indicate that the Java class is a Web service. JAX-WS supports the use of annotations based on the JSR 175 specification, JSR 181, and JAX-WS 2.1.

Using annotations within the Java source and within the Java class simplifies development of Web services. Use annotations to define information that is typically specified in deployment descriptor files, WSDL files, or mapping metadata from XML and WSDL files into the source artifacts.

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. Using annotations makes it much easier to expose Java artifacts as Web services. In addition, 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 because you 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.

For JAX-WS Web services, the use of the webservices.xml deployment descriptor is optional because we can use annotations to specify all of the information contained within the deployment descriptor file. Use the deployment descriptor file to augment or override existing JAX-WS annotations. Any information that you define in the webservices.xml deployment descriptor overrides any corresponding information specified by annotations.

For example, if wer service implementation class for the JAX-WS Web service includes...

@WebService(wsdlLocation="http://myhost.com/location/of/the/wsdl/ExampleService.wsdl")

...webservices.xml specifies a different file name for the WSDL document as follows:

<webservices>
    <webservice-description>
        <webservice-description-name>ExampleService</webservice-description-name>
        <wsdl-file>META-INF/wsdl/ExampleService.wsdl</wsdl-file>
    </webservice-description>
</webservices>

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 that contains 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...
       }
   }
);

Use the following code example 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

JAX-WS supports resource injection to further simplify development of Web services. JAX-WS uses this key feature of Java EE 5 to shift the burden of creating and initializing common resources in a Java runtime environment from the Web service application to the application container environment, itself. JAX-WS provides support for a subset of annotations defined in JSR-250 for resource injection and application life cycle in its runtime environment.

The appserver also supports the usage of the @Resource or @WebServiceRef annotation to declare JAX-WS managed clients and to request injection of JAX-WS services and ports. When either of these annotations are used on a field or method, they result in injection of a JAX-WS service or port instance. The usage of these annotations also results in the type specified by the annotation being bound into the JNDI namespace.

The @Resource annotation is defined by the JSR-250, Common Annotations spec that is included in Java EE 5 (Java EE 5). By placing the @Resource annotation on a variable of type javax.xml.ws.WebServiceContext within a service endpoint implementation class, we can request a resource injection and collect the javax.xml.ws.WebServiceContext interface related to that particular endpoint invocation. From the WebServiceContext interface, we can collect the MessageContext for the request associated with the particular method call using the getMessageContext() method.

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

The following example illustrates using the @Resource and @WebServiceRef annotations for resource injection:

@WebService public class MyService {
    
    @Resource
    private WebServiceContext ctx;

    @Resource
    private SampleService svc;

    @WebServiceRef
    private SamplePort port;

    public String echo (String input) {
        ...
    }
     
}

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.1

JAX-WS leverages the Java Architecture for XML Binding (JAXB) 2.1 API as the binding technology for mappings between Java objects and XML documents. JAX-WS tooling relies on JAXB tooling for default data binding for two-way mappings between Java objects and XML documents. JAXB data binding replaces the data binding described by the JAX-RPC specification.

The JAXB 2.1 spec provides enhancements such as improved compilation support and introduces support for the @XMLSeeAlso annotation. With the improved compilation support, you now have the flexibility to control the whether a new schema file is generated when using the schemagen schema generator and we can configure the xjc schema compiler so that it does not automatically generate new classes for a particular schema. Use the @XMLSeeAlso annotation to ensure that JAXB is aware of all the classes included in an inheritance hierarchy for a service endpoint interface.

 

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

Use JAX-WS, 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, SOAP Attachments API for Java (SAAJ) 1.3, and JAXB 2.1. 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.1 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. When creating JAX-WS Web services, we can start with either a WSDL file or an implementation bean class. If we start with an implementation bean class, use the wsgen command-line tool to generate all the Web services server artifacts, including a WSDL file if requested. If we start with a WSDL file, use the wsimport command-line tool to generate all the Web services artifacts for either the server or the client. The wsimport command-line tool processes the WSDL file with schema definitions to generate the portable artifacts, which include the service class, the service endpoint interface class, and the JAXB 2.1 classes for the corresponding XML schema.

 

Support for WS-Addressing (JAX-WS 2.1)

JAX-WS 2.1 integrates support for the WS-Addressing standard in to the API. The new API enables you to create, transmit and use endpoint references to target a specific Web service endpoint. We can also explicitly specify the action URIs associated with the WSDL operations of the Web service.

 

Support for JAX-WS 2.1 features

JAX-WS 2.1 introduces the concept of features as a way to programmatically control certain functions or behaviors.

There are three standard features:

AddressingFeature	Support for the WS-Addressing v1.0
MTOMFeature	Support for MTOM when sending binary attachments
RespectBindingFeature	Support for wsdl:binding extensions

The application server supports an additional feature, the SubmissionAddressingFeature, which is used to enable or disable support for WS-Addressing Member Submission specification (prior to WS-Addressing v1.0).

---

Subtopics

JAX-WS client model
JAX-WS annotations
JAX-WS application packaging

 

Related concepts

JAXB
Message Transmission Optimization Mechanism
Web Services for Java EE specification

 

Related tasks

Example: Installing a Web Services Sample with the console

 

Related

wsimport command for JAX-WS applications
wsgen command for JAX-WS applications
Web services specifications and APIs

 

Related information

JAX-WS API documentation
JAX-WS API User's Guide documentation
Metadata Facility for the Java Programming Language (JSR 175)
Web Services Metadata for the Java Platform (JSR 181)