+

Search Tips   |   Advanced Search

IBM proprietary Web Services Addressing SPIs

The IBM proprietary Web Services Addressing (WS-Addressing) SPIs extend the IBM proprietary WS-Addressing APIs 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.

We cannot use the standard JAX-WS API classes with these proprietary SPIs. However, we can convert endpoint references created using the standard JAX-WS API classes to instances of the proprietary class...

...using the class...

We can use these converted endpoint references with the proprietary SPIs.

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


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

The proprietary SPIs for creating, refining, and reasoning about the contents of endpoint references are contained in the com.ibm.wsspi.wsaddressing package and are summarized in the following illustration (the first two interfaces are proprietary API interfaces that are extended by the SPIs):

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

Similarly, the SPI com.ibm.wsspi.wsaddressing.EndpointReferenceManager extends the set of functions provided in the com.ibm.websphere.wsaddressing.EndpointReferenceManager API.

We can complete the following actions using the additional methods 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 provided at the API level, in that they do not automatically generate the URI for the EndpointReference instance. We might use these methods when you know that the URI of the endpoint is stable, for example in a test environment with no deployment restrictions.

Map between XML and Java representations of an endpoint reference

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

Use more complex reference parameter types

The proprietary interfaces 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.

When invoking a service with an EndpointReference object containing a reference parameter, create the reference parameter by using a complete QName object, with all parts present: namespace, localpart, and prefix. If the QName object is not complete, service invocations 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. We create instances of these interfaces by using operations provided by the proprietary WSAddressingFactory class.

Acquire and change the supported namespace

The WS-Addressing support in this product supports multiple namespaces. The setNamespace and getNamespace operations provided on the proprietary 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-WS BindingProvider object request context, or the JAX-RPC Stub or Call object), defines the namespace of the message-addressing properties of the message.


Set and Retrieving WS-Addressing message-addressing properties

The IBM proprietary WS-Addressing SPI provides a number of constants that identify JAX-WS or JAX-RPC properties that we can use to set WS-Addressing MAPs on outbound messages, and message context properties that we can use to retrieve MAPs on inbound messages. These constants are shown in the following diagram in the com.wsspi.wsaddresssing.WSAConstants class. The diagram also shows the interfaces required for generating instances of the appropriate property value types AttributedURI and Relationship. The first WSAConstants interface is a proprietary API interface.

Set WS-Addressing message-addressing properties on outbound messages:

We can add WS-Addressing message information headers to outgoing messages by setting the appropriate properties on the JAX-WS BindingProvider object request context, or the JAX-RPC Stub or Call object, prior to invoking a message with the BindingProvider, Stub, or Call object. The following table summarizes the relevant properties and their types.

object request context (or Stub or Call object). The table lists the different property names, their Java types, their abstract WS-Addressing MAP names and their default
Property name (of type String) Java type of property value Abstract WS-Addressing MAP name or names, using the notational convention of the W3C XML Information Set 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] Either 'none', if the message is a one-way message with no reply, or not set. For two-way asynchronous messages in JAX-WS applications, this property is generated automatically. If, in this situation, you attempt to set this property, a javax.xml.ws.WebServiceException exception is thrown. For two-way synchronous messages we can set this property only if the endpoint reference address is the anonymous URI. If the address is not the anonymous URI, a javax.xml.ws.WebServiceException exception is thrown.
WSADDRESSING_FAULTTO_EPR com.ibm.websphere.wsaddressing.EndpointReference [fault endpoint] Not set

If we attempt to set this property for two-way asynchronous messages in JAX-WS applications, a javax.xml.ws.WebServiceException exception is thrown. For two-way synchronous messages we can set this property only if the endpoint reference address is the anonymous URI. If the address is not the anonymous URI, a javax.xml.ws.WebServiceException exception is thrown.

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

Retrieve 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 defined in the WSAConstants class. The following table summarizes the available inbound properties. You acquire reference parameters from the message context using the proprietary EndpointReferenceManager.getReferenceParameter interface.

Message context property name (of type String) Java type of property value Abstract WS-Addressing MAP name, using the notational convention of the W3C XML Information Set
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

  • Web Services Addressing support
  • Web Services Resource Framework support


    Related tasks

  • Create stateful web services using the Web Services Resource Framework


    Related information:

  • Generated API documentation - Application programming interfaces
    W3C XML Information Set: http://www.w3.org/TR/xml-infoset/