+

Search Tips   |   Advanced Search

Create 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 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 that are described in this task apply to servers and clients that run on WAS.

Perform this task if we are creating a Web service that uses the WS-Addressing specification.

 

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

    1. Create an endpoint reference that references the Web service, by following the instructions in Create endpoint references using the IBM proprietary Web Services Addressing API.

    2. If the interface involves a Web service that fronts a resource instance, create or look up the resource instance.

    3. For a resource instance, obtain the identifier of the resource and associate it with the endpoint reference as a reference parameter, 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.

      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 the 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 perform the following actions:

    1. Obtain the resource instance identifier from the message context, 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 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, using 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 the 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.

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

 

Next steps


Create endpoint references using the IBM proprietary Web Services Addressing API

 

Related tasks


Enable Web Services Addressing support for JAX-RPC applications
Use the Web Services Addressing APIs: Creating an application that uses endpoint references

 

Related


Web Services Addressing APIs
Example: Creating a Web service that uses the IBM proprietary Web Services Addressing API to access a generic Web service resource instance