WebSphere Application Server Version 6.1 Feature Pack for Web Services
             Operating Systems: AIX, HP-UX, i5/OS, Linux, Solaris, Windows, z/OS

             Personalize the table of contents and search results
             New or updated topic for this feature pack

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

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

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. New or updated for this feature pack If your application uses JAX-WS, use the EndpointReferenceConverter class to convert the EndpointReference object into either a W3C or a Submission endpoint reference, depending on the WS-Addressing specification listed in the namespace of the EndpointReference object. If the namespace is http://www.w3.org/2005/08/addressing, convert to a W3CEndpointReference object. If the namespace is http://schemas.xmlsoap.org/ws/2004/08/addressing, convert to a SubmissionEndpointReference object. Any endpoint reference that is passed in the body of the SOAP message must be converted in this way.
    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 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 JAX-WS BindingProvider object, or JAX-RPC Stub object (by looking up the service in the Java Naming and Directory Interface (JNDI)), or create an empty JAX-RPC Call object.
    2. New or updated for this feature pack If your application uses JAX-WS, use the EndpointReferenceConverter class to convert the W3CEndpointReference or SubmissionEndpointReference object that is returned from the server back into an EndpointReference object.
    3. 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.For JAX-WS applications, set the WSADDRESSING_DESTINATION_EPR property on the request context of the BindingProvider object. For JAX-RPC applications, 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 BindingProvider request context, or 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.ws.WebServiceException or javax.xml.rpc.JAXRPCException exception is thrown on attempts to invoke the endpoint.

    Invocations on the BindingProvider, 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

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




In this information ...


IBM Redbooks, demos, education, and more


Use IBM Suggests to retrieve related content from ibm.com and beyond, identified for your convenience.

This feature requires Internet access.

IBM Suggests
Task topic    

Terms of Use | Feedback

Last updated: Nov 25, 2008 2:35:59 AM CST
http://publib.boulder.ibm.com/infocenter/wasinfo/v6r1/index.jsp?topic=/com.ibm.websphere.wsfep.multiplatform.doc/info/ae/ae/twbs_wsa_rap.html