Network Deployment (Distributed operating systems), v8.0 > Develop and deploying applications > Develop web services - Addressing (WS-Addressing) > Use the Web Services Addressing APIs: Creating an application that uses endpoint references


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

The steps described in this task apply to servers and clients that run on WAS.

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 Create 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 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 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, 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.
    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, WAS_HOME/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 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 by using the IBM proprietary Web Services Addressing SPIs.

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


Related


Create endpoint references by using the JAX-WS Web Services Addressing API
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 by 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
Use the Web Services Addressing APIs: Creating an application that uses endpoint references


Related


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
developerWorks article: JAX-WS client APIs in the Web Services Feature Pack for WAS V6.1, Part 1: Creating a Dispatch client
developerWorks article: JAX-WS client APIs in the Web Services Feature Pack for WAS V6.1, Part 2: Creating a proxy client

+

Search Tips   |   Advanced Search