+

Search Tips   |   Advanced Search

Create a JAX-WS web service application that uses Web Services Addressing

Web Services Addressing (WS-Addressing) aids interoperability between web services by defining a standard way to address web services and provide addressing information in messages. This task describes the steps required to create a JAX-WS web service that is accessed using a WS-Addressing endpoint reference. The task also describes the extra steps required to use stateful resources as part of the web service.

The steps described in this task apply to servers and clients that run on WebSphere Application Server.

Complete this task if we are creating a JAX-WS web service that uses the WS-Addressing specification. This task uses the JAX-WS WS-Addressing APIs to create the required endpoint reference. Alternatively, we can create endpoint references using the IBM proprietary WS-Addressing API, and convert them into JAX-WS API objects for use with the rest of the application.


Tasks

  1. Provide a web service interface that returns an endpoint reference to the target service.

    The interface must return an endpoint reference, which it can do using a factory operation or a separate factory service. The target service can front a resource instance, for example a shopping cart.

  2. Implement the web service created in the previous step. For the WS-Addressing portion of the implementation, complete the following steps:

    1. Optional: Include annotations to specify WS-Addressing behavior. See Web Services Addressing annotations for more details.

    2. Optional: If our interface involves a web service that fronts a resource instance, create or look up the resource instance.

    3. Optional: If we are using a resource instance, obtain the identifier of the resource. The resource identifier is application dependent and might be generated during the creation of the resource instance.

      Do not put sensitive information in the resource identifier, because the identifier is propagated in the SOAP message.

    4. Create an endpoint reference that references the web service by following the instructions in Create endpoint references using the JAX-WS Web Services Addressing API. If we are using a resource instance, pass in the resource identifier as a parameter.
    5. Return the endpoint reference.

  3. If our web service uses resource instances, extend the implementation to match incoming messages to the appropriate resource instances. Because you associated the resource identifier with the endpoint reference that we created earlier, any incoming messages targeted at that endpoint reference contain the resource identifier information as a reference parameter in the SOAP header of the message. Because the resource identifier is passed in the SOAP header, we do not have to expose it on the web service interface. When WAS receives the message, it puts this information into the message context on the thread. Extend the implementation to undertake the following actions:

    1. Obtain the resource instance identifier from the message context.

      • If we are using the 2005/08 WS-Addressing namespace, use the REFERENCE_PARAMETERS property of the MessageContext class.

      • If we are using the 2004/08 WS-Addressing namespace, we must use the IBM WS-Addressing API, specifically the EndpointReferenceManager.getReferenceParameterFrom essageContext(QName resource_id) method.

      Use the following method for the 2005/08 namespace: 

      ...
List resourceIDList = (List)getContext().getMessageContext().get(MessageContext.REFERENCE_PARAMETERS);
...
      Use the following method for the 2004/08 namespace: 
      ...

String resource_identifier = 
        EndpointReferenceManager.getReferenceParameterFromMessageContext(PRINTER_ID_PARAM_QNAME);
...

    2. Forward the message to the appropriate resource instance.

  4. Optional: Configure a proxy client to communicate with the service.

    1. Use the wsimport or xjc tool to generate the artifacts required by the client.

      To use the 2004/08 WS-Addressing specification, specify the provided binding file, app_server_root/util/SubmissionEndpointReference.xjb, as the -b parameter of the tool. This parameter tells the tool to generate endpoint reference objects using the SubmissionEndpointReference class that is part of the IBM implementation of the standard JAX-WS API. If we do not specify this bindings file, the resulting endpoint reference objects will not work with the standard JAX-WS API.

    2. In the client code, create an instance of the service class.
    3. Obtain a proxy object from the service class. There are several ways to use the JAX-WS API to obtain proxy objects. For example, there are several getPort methods on the Service class and one on the EndpointReference class. For more information, refer to the API documentation.

    4. Optional: Use the Addressing or SubmissionAddressing feature to enable WS-Addressing support. For example, create a proxy using a getPort method that accepts web service features as a parameter. If we prefer, we can enable WS-Addressing support using another method, such as policy sets. For more information see Enable Web Services Addressing support for JAX-WS applications.

    5. Use the proxy object to invoke the service method that returns the endpoint reference.

    The following sample code shows a client invoking a web service to add two numbers together. The web service issues a ticket (the resource identifier) to the client, and requires the client to use this ticket when invoking the web service.

    The client creates two proxies. The first proxy obtains the ticket as an endpoint reference from the service. The second proxy uses the AddressingFeature class to enable WS-Addressing for the 2005/08 specification, and invokes the service to add the two numbers together. 

    ...
CalculatorService service = new CalculatorService();
// Create the first proxy
Calculator port1 = service.getCalculatorServicePort();
// Obtain the ticket as an endpoint reference from the service
W3CEndpointReference epr = port1.getTicket();

// Create the second proxy, using an addressing feature to enable WS-Addressing
Calculator port2 = epr.getPort(Calculator.class, new AddressingFeature());
// Invoke the service to add the numbers
int answer = port2.add(value0, value1);
System.out.println("The answer is: " + answer);
...

    If the metadata of the endpoint reference conflicts with the information already associated with the outbound message, for example if the proxy object is configured to represent a different interface, a javax.xml.ws.WebServiceException exception is thrown on attempts to invoke the endpoint. If to set message-addressing properties, such as a reply to endpoint, use the IBM proprietary WS-Addressing SPI and the BindingProvider class, as described in Specify and acquiring message-addressing properties using the IBM proprietary Web Services Addressing SPIs.

  5. Optional: Configure a Dispatch client to communicate with the service. We can configure a client in different ways; the following steps describe one example.

    1. Create an instance of the service.

    2. Add a port to the service object.

    3. Create an instance of the Dispatch class, passing in the endpoint reference.

    4. Create a Dispatch object. Use the Service.createDispatch method with the following parameters:

      There are several variations of the Service.createDispatch method; see the API documentation for more details.

    5. Compose the client request message.

    6. Invoke the service endpoint with the Dispatch client.

    The following code shows an example fragment of a Dispatch client that enables 2004/08 WS-Addressing. 

    ...
CalculatorService service = new CalculatorService();
Dispatch(<SOAPMessage> dispatch = service.createDispatch( 
    endpointReference,
    SOAPMessage.class,  
    Service.Mode.MESSAGE,  
    new SubmissionAddressingFeature(true));
...

The web service and client are configured to use endpoint references through the WS-Addressing support. For a detailed example that includes code, see Example: Creating a web service that uses the JAX-WS Web Services Addressing API to access a generic web service resource instance.


What to do next


Subtopics


Related:

  • JAX-WS client programming model
  • Web Services Addressing APIs
  • IBM proprietary Web Services Addressing SPIs
  • Enable Web Services Addressing support for JAX-WS applications
  • Specify and acquiring message-addressing properties using the IBM proprietary Web Services Addressing SPIs
  • Implement web services applications with JAX-WS
  • Generate Java artifacts for JAX-WS applications from a WSDL file
  • Generate Java artifacts for JAX-WS applications
  • wsgen command for JAX-WS applications
  • wsimport command for JAX-WS applications
  • Example: Creating a web service that uses the JAX-WS Web Services Addressing API to access a generic web service resource instance
  • JAX-WS API: http://jcp.org/aboutJava/communityprocess/mrel/jsr224/index2.html