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

 

+

Search Tips   |   Advanced Search

 

Overview

WS-Addressing provides addressing information using WS-Addressing endpoint references.

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

   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.

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

      EndpointReferenceManager.getReferenceParameterFromMessageContext(QName resource_id_name)

   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 EE way by looking up the service in the JNDI, or alternatively create an empty Call object.

   2. Associate the endpoint reference with the proxy object.

      Use the method..

      setProperty(String property_name, Object value)

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

      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, an exception...

      javax.xml.rpc.JAXRPCException

      ...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 Web Services Addressing API to access a generic Web service resource instance.

 

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

---

Creating endpoint references using the Web Services Addressing support

 

Related tasks

Enabling and disabling Web Services Addressing support
Use the Web Services Addressing API: Creating an application that uses endpoint references

 

Related Reference

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