Specifying and acquiring message addressing properties using the Web Services Addressing SPI

 

The Web Services Addressing (WS-Addressing) system programming interface (SPI) enables you to add WS-Addressing message addressing properties (MAPs) to the SOAP headers of an outbound message, through properties on the JAX-RPC Stub or Call interface. When the target endpoint receives the message, the SPI enables the endpoint to acquire the MAPs through properties on the message context.

 

Overview

Perform this task if you are a Web service developer using the WS-Addressing support, or a system programmer using the WS-Addressing SPIs to specify message addressing properties, such as fault or reply endpoint references, on Web services messages. The properties that you can set or retrieve are detailed, with the Java type of property instances, in Web Services Addressing SPI. Most properties are of type com.ibm.websphere.wsaddressing.EndpointReference, for example destination, reply or fault endpoint references. The relationship property is a java.util.Set object that contains instances of the com.ibm.wsspi.wsaddressing.Relationship class. Use relationships when you want to specify an association between messages, for example in a response message you might want to specify the ID of the message to which you are replying. The action property is an AttributedURI object that identifies a specific method or operation within the target endpoint.

The destination endpoint reference and action properties are required for the message to be WS-Addressing compliant.

 

Procedure

1. On the client, obtain the endpoint reference from the service and associate it with your Stub or Call object, as described in Creating a Web service application that is referenced through a Web Services Addressing endpoint reference.

2. Create instances of the required properties. For example, if you want to specify an endpoint reference for the target service to send replies to, create an instance of the com.ibm.websphere.wsaddressing.EndpointReference class, to use as the WSADDRESSING_REPLYTO_EPR property.

3. Set the required properties by associating them with the Stub or Call object, using the setProperty(String property_name, Object value) method of the Stub or Call object. The following example sets a destination endpoint reference and a reply endpoint reference on a Call object:

   import javax.xml.rpc.Call;
   ...
    // Associate the endpoint reference for the Web service. This property is required for the message 
    // to be WS-Addressing compliant.
    call.setProperty(com.ibm.websphere.wsaddressing.WSAConstants.
                                WSADDRESSING_DESTINATION_EPR, destinationEpr);
    // Associate the endpoint reference that represents the reply to endpoint reference
    call.setProperty(com.ibm.wsspi.wsaddressing.WSAConstants.
                                WSADDRESSING_REPLYTO_EPR, replyToEpr);
   
   

   When an invocation occurs on the Stub or Call object, WAS adds the appropriate MAPs to the message header.

4. On the server, retrieve the MAPs from the inbound message through the message context, using the MessageContext.getProperty(String propertyName) method. When WAS receives the message, it puts the MAP information into the message context on the thread, making it available to the service. You can retrieve the message context by, for example, using the session context of the endpoint enterprise bean. For more information about message contexts, refer to the JSR-109 standard. The following example retrieves the reply endpoint reference:

   import javax.xml.rpc.handler.MessageContext;
   ...
   
     // If the endpoint is implemented as an enterprise bean, you can use its session context
     // to obtain the message context
     private SessionContext sessionContext;
     MessageContext context = sessionContext.getMessageContext();
   
     // Retrieve the reply endpoint reference
     replyToEpr = context.getProperty(WSADDRESSING_INBOUND_REPLYTO_EPR);
   
   

---

 

Related tasks

Use the WS-Addressing SPI: Performing more advanced Web Service Addressing tasks

 

Related Reference

Web Services Addressing SPI