Creating 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 that are required to create a JAX-WS web service that is accessed using a WS-Addressing endpoint reference. The task also describes the extra steps that are required to use stateful resources as part of the web service.

Before you begin

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

About this task

Complete this task if you 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, you can create endpoint references by using the IBM proprietary WS-Addressing API, and convert them into JAX-WS API objects for use with the rest of the application.

Procedure

  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 by 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. Include annotations to specify WS-Addressing behavior. See Web Services Addressing annotations for more details.
    2. Optional: If your interface involves a web service that fronts a resource instance, create or look up the resource instance.
    3. Optional: If you 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.
      Attention: 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 Creating endpoint references by using the JAX-WS Web Services Addressing API. If you are using a resource instance, pass in the resource identifier as a parameter.
    5. Return the endpoint reference.
  3. If your 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 you 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, you do not have to expose it on the web service interface. When WebSphere Application Server 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 you are using the 2005/08 WS-Addressing namespace, use the REFERENCE_PARAMETERS property of the MessageContext class.
      • If you are using the 2004/08 WS-Addressing namespace, you must use the IBM WS-Addressing API, specifically the EndpointReferenceManager.getReferenceParameterFrom MessageContext(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.
      Note: If you want 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 by using the SubmissionEndpointReference class that is part of the IBM implementation of the standard JAX-WS API. If you 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 by using a getPort method that accepts web service features as a parameter. If you prefer, you can enable WS-Addressing support by using another method, such as policy sets. For more information see Enabling 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);
    ...
    Note: 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 you want to set message-addressing properties, such as a reply to endpoint, you must use the IBM proprietary WS-Addressing SPI and the BindingProvider class, as described in Specifying and acquiring message-addressing properties by using the IBM proprietary Web Services Addressing SPIs.
  5. Optional: Configure a Dispatch client to communicate with the service. You 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<T> 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));
    ...

Results

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




In this information ...


IBM Redbooks, demos, education, and more

(Index)

Use IBM Suggests to retrieve related content from ibm.com and beyond, identified for your convenience.

This feature requires Internet access.

Task topic Task topic    

Terms of Use | Feedback

Last updatedLast updated: Sep 19, 2011 7:16:32 PM CDT
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=matt&product=was-express-iseries&topic=twbs_wsa_rap_jaxws
File name: twbs_wsa_rap_jaxws.html