Create a Web service application that is referenced through a Web Services Addressing endpoint reference

Web Services Addressing (WS-Addressing) aids interoperability between Web services by defining a standard way to address Web services and to provide addressing information in messages. This task describes the steps that are required to create a 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 WebSphere Application Server.

Overview

Perform this task if you are creating a Web service that complies with the WS-Addressing interoperability protocol, in other words one that is addressed through an endpoint reference.

Procedure

1. Provide a Web service interface, by creating or generating a Web Services Description Language (WSDL) document for the Web service, which 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, perform the following steps:

   1. Create an endpoint reference that references the Web service, by following the instructions in Creating endpoint references using the Web Services Addressing support.

   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, 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, as 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 need 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 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 in the normal Java Platform, Enterprise Edition (Java EE) way by looking up the service in the Java Naming and Directory Interface (JNDI), or alternatively 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 to associate the endpoint reference, 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 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: For Stub objects, if the endpoint that is defined by the endpoint reference conflicts with the configuration of the Stub object, for example if the endpoint represents 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, WebSphere Application Server 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

What to do next

• Refer to Web Services Addressing security considerations for information about security with WS-Addressing.

• Deploy the application. For this scenario, you do not have to take any additional steps to enable the WS-Addressing support in WebSphere Application Server because you specified a WS-Adressing property on the client. For more information, and for other scenarios which might require additional steps, see Enabling and disabling Web Services Addressing support.

Related tasks

Related Reference