JAX-WS
Java™ API for XML-Based Web Services (JAX-WS) is the next generation web services programming model complimenting the foundation provided by the Java API for XML-based RPC (JAX-RPC) programming model. Using JAX-WS, development of web services and clients is simplified with more platform independence for Java applications by the use of dynamic proxies and Java annotations.
JAX-WS is a programming model that simplifies application development through support of a standard, annotation-based model to develop web service applications and clients. The JAX-WS technology strategically aligns itself with the current industry trend towards a more document-centric messaging model and replaces the remote procedure call programming model as defined by JAX-RPC. While the JAX-RPC programming model and applications are still supported by this product, JAX-RPC has limitations and does not support various complex document-centric services. JAX-WS is the strategic programming model for developing web services and is a required part of the Java Platform, Enterprise Edition 6 (Java EE 6). JAX-WS is also known as JSR 224.
Version 8.0 supports the JAX-WS Version 2.2 and Web Services for Java EE (JSR 109) Version 1.3 specifications.
The JAX-WS 2.2 specification supersedes and includes functions within the JAX-WS 2.1 specification. JAX-WS 2.2 adds client-side support for using WebServiceFeature-related annotations such as @MTOM, @Addressing, and the @RespectBinding annotations. JAX-WS 2.1 had previously added support for these annotations on the server. There is also now the ability to enable and configure WS-Addressing support on a client or service by adding WS-Policy assertions into the WSDL document. In addition, 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 Java Architecture for XML Binding (JAXB) Version 2.2 for data binding.
The implementation of the JAX-WS programming standard provides the following enhancements for developing web services and clients:
Enhanced platform independence for Java applications.
Using JAX-WS APIs, development of web services and clients is simplified with enhanced 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 provides 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 defined by the JAX-WS 2.2 specification. 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.
@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 you can use annotations to specify all of the information that is contained within the deployment descriptor file. You can 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 that is specified by annotations.
- the @WebService annotation:
@WebService(wsdlLocation="http://myhost.com/location/of/the/wsdl/ExampleService.wsdl")
- the webservices.xml file 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>
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.
@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);
}
CreditRatingService svc = ...;
Future<?> invocation = svc.getCreditScoreAsync(customerFred,
new AsyncHandler<Score>() {
public void handleResponse (
Response<Score> response)
{
Score score = response.get();
// do work here...
}
}
);
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();
Using 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 your web service application to the application container environment, itself. JAX-WS provides support for a subset of annotations that are defined in JSR-250 for resource injection and application life cycle in its runtime environment.
The application server 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 specification that is
included in Java Platform, Enterprise Edition 5 (Java EE 5). By placing the @Resource annotation on a variable of
type javax.xml.ws.WebServiceContext
within a service endpoint implementation class,
you can request a resource injection and collect the javax.xml.ws.WebServiceContext
interface related to that particular endpoint invocation. From the WebServiceContext interface, you
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.
@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.2
JAX-WS leverages the Java Architecture for XML Binding (JAXB) 2.2 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.
JAX-WS 2.2 requires JAXB 2.2 for data binding. JAXB 2.2 provides minor enhancements to its annotations for improved schema generation and better integration with JAX-WS.
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
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 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 Java Architecture for XML Binding (JAXB) 2.2. 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 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 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, you can start with either a WSDL file or an implementation bean class. If you 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 you 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.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.