Creating a JAX-RPC 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-RPC Web service that is accessed by 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 Web service that uses the WS-Addressing specification.

Procedure

  1. Provide a Web service interface, by creating or generating a Web Services Description Language (WSDL) document for the Web service, 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. Create an endpoint reference that references the Web service, by following the instructions in Creating endpoint references by using the IBM proprietary Web Services Addressing API.
    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 and associate it with the endpoint reference as a reference parameter, by using the EndpointReference.setReferenceParameter(QName resource_id_name, String value) method. 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.
      The endpoint reference now targets the resource.
    4. 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, by using the EndpointReferenceManager.getReferenceParameterFromMessageContext(QName resource_id_name) method.
    2. Forward the message to the appropriate resource instance.
  4. To configure a client to communicate with the service, use the endpoint reference that is produced by the service in the first step to send messages to the endpoint.
    1. Obtain a Stub object (by looking up the service in the Java™ Naming and Directory Interface (JNDI)), or create an empty Call object.
    2. Associate the endpoint reference with the proxy object. Use the setProperty(String property_name, Object value) method of the Stub or Call object. Use the WS-Addressing constant WSADDRESSING_DESTINATION_EPR as the property name, and the endpoint reference as the value.
      This procedure automatically configures the Stub or Call object, to represent the Web service (or resource instance if your interface uses a Web service that fronts a resource instance) of the endpoint reference. For Call objects, this process includes the configuration of the interface and endpoint metadata (portType and port elements) that are associated with the endpoint reference.
      Note: If the metadata of the endpoint reference conflicts with the information already associated with the outbound message, for example if the Stub object is configured to represent a different interface, a javax.xml.rpc.JAXRPCException exception is thrown on attempts to invoke the endpoint.

    Invocations on the Stub or Call object are now targeted at the Web service or resource instance that is defined by the endpoint reference. When an invocation occurs, the product adds appropriate message addressing properties, such as a reference parameter contained within the endpoint reference that identifies a target resource, to the message header.

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 IBM proprietary 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    

Terms of Use | Feedback

Last updated: Oct 21, 2010 3:36:59 AM CDT
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=compass&product=was-express-iseries&topic=twbs_wsa_rap
File name: twbs_wsa_rap.html