JAX-WS
Java™ API for XML-Based Web Services (JAX-WS), which is also known as JSR-224, is the next generation Web services programming model that extends the foundation provided by the Java API for XML-based RPC (JAX-RPC) programming model. Using JAX-WS, developing Web services and clients is simplified with greater platform independence for Java applications by the use of dynamic proxies and Java annotations. The Web services tools included in this product support JAX-WS 2.0 and 2.1.
JAX-WS is a new programming model that simplifies application development through support of a standard, annotation-based model to develop Web Service applications and clients. The JAX-WS programming standard strategically aligns itself with the current industry trend toward a more document-centric messaging model and replaces the remote procedure call programming model as defined by JAX-RPC. Although this product still supports the JAX-RPC programming model and applications, JAX-RPC has limitations and does not support many current document-centric services. JAX-WS is the strategic programming model for developing Web services and is a required part of the Java EE 5 platform.
Implementing the JAX-WS programming standard provides the following enhancements for developing Web services and clients:
- Better platform independence for Java applications
- Using JAX-WS APIs, developing Web services and clients is simplified with better platform independence for Java applications. JAX-WS takes advantage of dynamic proxies whereas JAX-RPC uses generated stubs. The dynamic proxy client invokes a Web service based on a Service Endpoint Interface (SEI) which is generated or provided. The dynamic proxy client is similar to the stub client in the 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. Refer to Chapter 4 of the JAX-WS 2.0 specification for more information on using dynamic proxy clients.
- 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 Metadata Facility for the Java Programming Language (JSR 175) specification, the Web Services Metadata for the Java Platform (JSR 181) specification and annotations that are defined by the JAX-WS 2.0 specification. Using annotations in the Java source and in the Java class simplifies development of Web services by defining some of the additional information that is typically obtained from deployment descriptor files, WSDL files, or mapping metadata from XML and WSDL files into the source artifacts.
For example, you 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 annotation @WebService 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.
- Invoking Web services asynchronously
With JAX-WS, Web services can be called both synchronously and asynchronously. JAX-WS adds support for both a polling mechanism 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 whether the server has responded. When the server responds, the actual response is retrieved. Using the polling model, the client can continue to process other work without waiting for a response to return. 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 while providing for a more dynamic and efficient model to invoke Web services.
For example, a Web service interface has 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 handler is an object that contains the application code that will be executed when an asynchronous response is received. The following is a code example for 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... } } );The following is a code example for an asynchronous polling client:
CreditRatingService svc = ...; Response<Score> response = svc.getCreditScoreAsync(customerFred); while (!response.isDone()) { // do something while we wait } // no cast needed, thanks to generics Score score = response.get(); </Score>- Data binding with JAXB 2.0 and 2.1
- JAX-WS leverages the JAXB API and tools 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.
WebSphere® Application Server Version 7.0 supports the JAXB 2.1 specification. JAX-WS 2.1 requires JAXB 2.1 for data binding. JAXB 2.1 provides enhancements such as improved compilation support and support for the @XMLSeeAlso annotation, and full schema 1.0 support.
- Dynamic and static clients
- The dynamic client programming 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> element 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 and JAX-WS does not add anything additional to the message. The dispatch client supports asynchronous invocations using a callback or polling mechanism. </soap:Body></soap:Header></soap:Envelope></soap:Header></soap:Envelope></soap:Body>
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 is generated or provided.
- MTOM support
- Using JAX-WS, you 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 payload structures
- JAX-WS exposes the following binding technologies to the user: XML Source, SOAP Attachments API for Java (SAAJ) 1.3, and Java Architecture for XML Binding (JAXB) 2.0. XML Source enables a user to pass a javax.xml.transform.Source into the runtime which represents the data in a Source object to be passed to the runtime. SAAJ 1.3 now has the ability to pass an entire SOAP document across the interface rather than just the payload itself. This is done by the client passing the SAAJ SOAPMessage object across the interface. JAX-WS leverages the JAXB 2.0 support as the data binding technology of choice between Java and XML.
- SOAP 1.2 support
- Support for SOAP 1.2 was added to JAX-WS 2.0. JAX-WS supports both SOAP 1.1 and SOAP 1.2. SOAP 1.2 provides a more specific definition of the SOAP processing model, which removes many of the ambiguities that sometimes led to interoperability problems in the absence of the Web Services-Interoperability (WS-I) profiles. SOAP 1.2 should reduce the chances of interoperability issues with SOAP 1.2 implementations between different vendors. It is not interoperable with earlier versions.
For more information on JAX-WS, refer to the official JSR-224 specification: JSR 224: Java API for XML-Based Web Services (JAX-WS) 2.0
Related concepts
IBM WebSphere JAX-WS runtime environment
Web services runtime environments
Web Services: What's new in this release
Web Services Description Language (WSDL)
Universal Description, Discovery, and Integration (UDDI)
Web Services Inspection Language (WSIL)
Using annotations to create Web services
Related tasks
Creating a JAX-WS enabled WebSphere server
Creating a JAX-WS enabled dynamic Web project
Creating a Web service and Java bean skeleton from WSDL
Creating a Web service from a Java bean
Setting Web services preferences