Web Services Addressing SPI

The Web Services Addressing (WS-Addressing) system programming interface (SPI) extends the application programming interface to enable you to create and reason about the contents of endpoint references and other WS-Addressing artifacts, and to set or retrieve WS-Addressing message addressing properties (MAPs) on or from Web service messages.

The programming interfaces in this topic are described in more detail in the WS-Addressing SPI documentation.

Creating, refining, and reasoning about the contents of endpoint references

The SPI extends the WS-Addressing com.ibm.websphere.wsaddressing.EndpointReference API to provide a number of additional methods through the com.ibm.wsspi.wsaddressing.EndpointReference interface. You can cast instances of com.ibm.websphere.wsaddressing.EndpointReference to com.ibm.wsspi.wsaddressing.EndpointReference to access this additional functionality.

Similarly, the SPI com.ibm.wsspi.wsaddressing.EndpointReferenceManager extends the functionality that is provided in the com.ibm.websphere.wsaddressing.EndpointReferenceManager API. You can perform the following actions using the additional methods that are provided by the EndpointReference and EndpointReferenceManager SPIs:

Create endpoint references

Create EndpointReference objects by specifying the URI of the endpoint that the EndpointReference object is to represent, using the createEndpointReference(URI) operation, or the EndpointReferenceManager.createEndpointReference(AttributedURI) operation. These methods differ from the createEndpointReference method that is provided at the API level, in that they do not automatically generate the URI for the EndpointReference instance. You might use these methods when you know that the URI of the endpoint is stable, for example in a test environment with no deployment considerations.

Map between XML and Java representations of an endpoint reference

You can serialize instances of the EndpointReference interface to their corresponding SOAP element instances using the EndpointReference.getSOAPElement operation. Conversely, you can deserialize SOAP elements of type EndpointReferenceType into their corresponding EndpointReference Java representation, by using the EndpointReference.createEndpointReference(SOAPElement) operation. You might find these serialization and deserialization interfaces useful if you are creating custom binders for types that contain EndpointReference instances.

Use more complex reference parameter types

The interfaces that are provided at the API level are restricted to reference parameters of type xsd:string to allow for a simpler programming model. The SPIs extend this support to allow reference parameters of type <xsd:any>. The EndpointReference interface provides mechanisms for getting and setting reference parameters as SOAP elements. Additionally, the EndpointReferenceManager class provides the getSOAPElementReferenceParameterFromMessageContext operation, which enables receiving endpoints to acquire reference parameters that are not of type String from the incoming message.

Note: When invoking a service with an EndpointReference object that contains a reference parameter, you must create the reference parameter using a complete QName object, with all parts present: namespace, localpart, and prefix. If the QName object is not complete, service invocations will fail.

Set and reason about endpoint reference contents

The EndpointReference interface provides operations for you to set and reason about the contents of an EndpointReference instance, such as its WS-Addressing [address] and [metadata] properties. Additional interfaces are provided to represent the artifacts making up an endpoint reference: Metadata, AttributedURI, and ServiceName. You create instances of these interfaces using operations that are provided by the WSAddressingFactory class.

Acquire and change the supported namespace

The WS-Addressing support in WebSphere Application Server supports multiple namespaces. The setNamespace and getNamespace operations that are provided on the EndpointReference interface enable you to change and acquire the namespace that is associated with a particular EndpointReference object. Serialization to SOAP elements is in accordance with the namespace of the EndpointReference object. By default, the namespace of the destination endpoint reference (the endpoint reference set as the com.ibm.websphere.wsaddressing.WSAConstants.WSADDRESSING_DESTINATION_EPR property on the JAX-RPC Stub or Call object), defines the namespace of the message addressing properties of the message.

Setting and Retrieving WS-Addressing message addressing properties

Setting WS-Addressing message addressing properties on outbound messages You can add WS-Addressing message information headers to outgoing messages by setting the appropriate properties on the JAX-RPC Stub or Call interface prior to invoking a message in the Stub or Call object. The following table summarizes the relevant properties and their types.

Table 1. Outbound properties that you can set on the BindingProvider object's request context (or Stub or Call object), their Java types and equivalent abstract WS-Addressing MAP name or names.

Property name (of type String)	Java type of property value	Abstract WS-Addressing MAP name or names	Default value
WSADDRESSING_DESTINATION_EPR	com.ibm.websphere.wsaddressing.EndpointReference	[destination] URI [reference parameters]* (any)	Not set Note that this property comes from the API.
WSADDRESSING_FROM_EPR	com.ibm.websphere.wsaddressing.EndpointReference	[source endpoint]	Not set
WSADDRESSING_REPLYTO_EPR	com.ibm.websphere.wsaddressing.EndpointReference	[reply endpoint]	Not set, unless the message is a one-way message with no reply
WSADDRESSING_FAULTTO_EPR	com.ibm.websphere.wsaddressing.EndpointReference	[fault endpoint]	Not set
WSADDRESSING_RELATIONSHIP_SET	java.util.Set containing instances of com.ibm.wsspi.wsaddressing.Relationship	[relationship]	Not set
WSADDRESSING_MESSAGE_ID	com.ibm.wsspi.wsaddressing.AttributedURI	[message id]	Generated and set to a unique value
WSADDRESSING_ACTION	com.ibm.wsspi.wsaddressing.AttributedURI	[action]	Generated and set, according to the WS-Addressing specification
WSADDRESSING_OUTBOUND_NAMESPACE	String	none	The WS-Addressing namespace of the WSADDRESSING_DESTINATION_EPR property, if specified, otherwise the default namespace

Retrieving WS-Addressing message addressing properties from inbound messages WS-Addressing message information headers that correspond to the last inbound message are available from the inbound properties that are defined in the WSAConstants class. The following table summarizes the available inbound properties. You acquire reference parameters from the message context using the EndpointReferenceManager.getReferenceParameter interface.

Table 2. Inbound properties that you can acquire from the message context, their Java types and equivalent abstract WS-Addressing MAP name.

Message context property name (of type String)	Java type of property value	Abstract WS-Addressing MAP name
WSADDRESSING_INBOUND_TO	com.ibm.wsspi.wsaddressing.AttributedURI	[destination]
No specific property. Use the EndpointReferenceManager.getReferenceParameter(QName name) method to obtain the associated MAP.	Any type	[reference parameters]*
WSADDRESSING_INBOUND_FROM_EPR	com.ibm.websphere.wsaddressing.EndpointReference	[source endpoint]
WSADDRESSING_INBOUND_REPLYTO_EPR	com.ibm.websphere.wsaddressing.EndpointReference	[reply endpoint]
WSADDRESSING_INBOUND_FAULTTO_EPR	com.ibm.websphere.wsaddressing.EndpointReference	[fault endpoint]
WSADDRESSING_INBOUND_RELATIONSHIP	java.util.Set containing instances of com.ibm.wsspi.wsaddressing.Relationship	[relationship]
WSADDRESSING_INBOUND_MESSAGE_ID	com.ibm.wsspi.wsaddressing.AttributedURI	[message id]
WSADDRESSING_INBOUND_ACTION	com.ibm.wsspi.wsaddressing.AttributedURI	[action]
WSADDRESSING_INBOUND_NAMESPACE	String	The WS-Addressing namespace of the incoming message

Related concepts

Related tasks

Related Reference

Related information

Reference topic