JAX-WS

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.

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>

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.

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

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.

WebSphere Application Server Version 8.0 supports the JAXB 2.2 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.

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.

• If the operation is document style, the parameter style is WRAPPED and the parameter does not map to a header. An empty namespace is mapped with the operation parameters and return types.
• If the parameter style is not WRAPPED, the value of the targetNamespace parameter specified using the @WebParam or @WebResult annotation is used.