Section 5.2. Architectural Concepts | Web Services Platform Architecture(c) SOAP, WSDL, WS-Policy, WS-Addressing, WS-BP[. .. ] More

5.2. Architectural Concepts

WS-Addressing defines two fundamental concepts: endpoint references as a general-purpose way of encoding the addressing information needed to reach service endpoints, and message information headers to support the use of endpoint references in addressing and exchanging Web service messages.

5.2.1. Endpoint References

An endpoint reference is a data structure that is defined to encapsulate all the information that is required to reach a service endpoint at runtime. A service endpoint in WS-Addressing is any potential source or destination of Web services messages. In view of this definition one can consider a Web Services Description Language (WSDL) port as a service endpoint. A WSDL port, however, is a descriptive abstraction that cannot (and, in fact, does not attempt to) capture the runtime character of service endpoints. The dynamic nature of service interactions often implies a more subtle relationship between the concepts of port and endpoint. In some cases, endpoints are dynamically generated and lack a WSDL description altogether. In other common situations, multiple endpoints share the same WSDL port representation, such as in the case of interactions with a service that provides the functions for processing multiple stateful resources. From the WS-Addressing point of view, a service endpoint maps to at most one WSDL port. As WSDL ports, endpoints can support at most one WSDL interface. Also, like WSDL ports (and with similar semantics), endpoints can have policies attached to them. On the other hand, endpoint references might carry additional runtime information (not present in the WSDL port definition) that is required to properly address and interact with an endpoint.

An endpoint reference contains two types of information: runtime information required for the interaction with the endpoint, and associated metadata. Runtime interaction information consists of three fields within an endpoint reference:

A mandatory address field (or "address property" in the terminology of the WS-Addressing specification)This is the only mandatory required field; its value is a URI that represents the address at which the service endpoint can be reached.
A set of endpoint "reference properties"These are information fields that are represented as XML elements; together with the endpoint address, they are used to help deliver messages to endpoint.
A set of "reference parameters"These are information fields, also represented as XML elements, which are necessary to successfully interact with the endpoint but are not required to identify the endpoint when routing messages to it. The endpoint issuer provides them to facilitate the interaction.

The runtime information in the endpoint reference supports the routing of messages to the endpoint. The issuer of the endpoint reference (typically the service-side middleware infrastructure) defines the runtime information within the endpoint reference. This information is otherwise opaque to consumer applications; that is, a consumer application should not attempt to introspect or interpret the runtime information contained within an endpoint reference it receives. Applications (usually the service requester middleware) are simply required to include these fields in messages that are addressed to the endpoint according to the specific data representation and protocol used. In the case of SOAP, the WS-Addressing specification defines how these properties are incorporated as headers of a SOAP message. SOAP binding is discussed later in this chapter (Section 5.2.4).

In addition to runtime information, an endpoint reference can include metadata associated with the endpoint. The metadata helps consuming applications configure their interaction with the endpoint. It has three fields:

The qualified name of the port type that the endpoint supports. This is an optional field. It might be omitted either because it is undefined (that is, no WSDL port type definition of the interface of the endpoint is available) or because it is assumed that the consumer of the endpoint reference has this information available through some out-of-band mechanism.
The WSDL service name (a qualified name) and port name that provide the static representation of the endpoint. Again, this is an optional field.
Policies that are applicable to the endpoint, represented by an optional set of WS-Policy policy elements that need to be followed when interacting with the endpoint.

Following is an example of an endpoint reference:

 <wsa:EndpointReference>    <wsa:Address>http://www.example.com/stq</wsa:Address>    <wsa:ReferenceProperties>        <exp:customer-id>xgtopsnlk-0001<exp:customer-id>    </wsa:ReferenceProperties>    <wsa:ReferenceParameters>        <exp:model-id>llp-11<exp:model-id>    </wsa:ReferenceParameters>    <wsa:PortType>tns:StockQuotePortType</wsa:PortType>    <wsa:ServiceName PortName="StockQuotePort">         tns:StockQuoteService    </wsa:ServiceName> </wsa:EndpointReference>

5.2.2. Comparing Endpoints

Among the runtime information included in an endpoint reference, the address and reference properties determine the message destination and the expected behavior of the endpoint. Two endpoint references with identical addresses and sets of reference properties must be assumed to represent the same endpoint in the sense that both point to the same location and follow the same behavior. In particular, both endpoints support the same interfaces and the same protocol binding and comply with the same policies. Thus, two endpoint references with different reference parameters represent the same endpoint as long as their address and reference properties match.

The runtime consequence of this distinction is that when the reference properties of an endpoint reference change, one must assume that a different set of polices applies to the endpoint, and the runtime infrastructure should make sure it has updated information about the applicable policy set for the new endpoint. One can accomplish this, for example, by using the metadata exchange service, described later in this book (see Chapter 9, "Web Services Metadata Exchange"). A change in the reference parameters does not imply a change in the set of applicable policies.

5.2.3. Message Information Headers

WS-Addressing introduces a set of message headers to allow messages to be directed to service endpoints and to provide the information necessary to support a rich bidirectional and asynchronous interaction. WS-Addressing explicitly recognizes the basic forms of interaction supported in WSDL 1.1 (one-way messages and request-reply interactions) and describes how message headers are used and processed in those cases. However, the use of WS-Addressing message headers is not limited to the two interactions and can support more complex message interactions as well.

Only two message headers are required on every message: one to identify the destination of the message, and a second one to indicate how to process the message:

The "To" header contains the URI address of the target endpoint.
The "Action" header contains a URI identifying the intent or semantics of the message.

Note that the identification of the target endpoint relies on the values of the endpoint reference properties as much as on the "To" URI address. If reference properties appear in the endpoint reference, they must be present on messages that are targeted to the endpoint. The way they appear on the message depends on the specific serialization (encoding) of the message. The next section presents the encoding rules that apply to SOAP messages. Not all endpoint references contain reference properties, however.

The "Action" header of a message identifies the message's intent. The content (body) of a message is described by a certain document type, typically an XML Schema definition, but this is not enough to uniquely identify its intent since one can use the same document type with different purposes. For example, one might use a "CustomerInformation" document in one interaction to create a new record in a customer database and to update an existing record in another. In both cases, the document that is contained in the body of the message is the same, but each message must be processed differently. The Action header contains a URI value that indicates how the sender of the message intended the message to be processed. In this example, messages that are sent as input to the "CreateRecord" and "UpdateRecord" operations contain the same document type but carry different URI values in the Action header. This allows the receiving side to decide how to deal with messages that arrive at the endpoint.

The value of the Action URI is naturally related to the WSDL operation to which the message is related. In fact, because the Action URI indicates the intent of an individual message, it is naturally mapped to each of the messages that appear in the definition of a WSDL operation, rather than to the operation itself. Therefore, the input, output, and possible fault messages of a WSDL operation typically are assigned distinct, unique Action URIs. WS-Addressing provides two mechanisms to assign these URIs to the messages of a WSDL operationone explicit and another implicit. WS-Addressing defines an attribute in the WS-Addressing namespace, "wsa:Action", which one can encode on the input, output, and fault elements of a WSDL operation definition to explicitly assign an Action value to them. The example that follows, from Section 3.3 of the WS-Addressing specification, shows how this is done.

 <portType name="StockQuotePortType">   <operation name="GetLastTradePrice">     <input message="tns:GetTradePricesInput"           wsa:Action="http://example.com/GetQuote"/>     <output message="tns:GetTradePricesOutput"           wsa:Action="http://example.com/Quote"/>   </operation> </portType>

To deal with WSDL documents that don't explicitly assign Action values to messages and to relieve WSDL authors from the burden of creating and encoding Action URIs for all their WSDL operation messages, WS-Addressing defines an implicit encoding scheme. When no explicit statement is made about the value of the Action URI for a message, it is implicitly assumed that the value is derived from a combination of the target namespace of the WSDL document and the port type and message names (the reader should refer to the WS-Addressing specification for a detailed definition of the corresponding algorithm to use for that purpose). If, in the preceding example, all the wsa:Action attributes were removed (and assuming the target namespace given next), the Action values for the input and output messages would be set by default to the following values:

   Target namespace: http://www.example.com/wsdl/stockquote   Input message Action: http://www.example.com/wsdl/stockquote/StockQuotePortType/ GetLastTradePriceRequest   Output message Action: http://www.example.com/wsdl/stockquote/StockQuotePortType/ GetLastTradePriceResponse

The "ReplyTo" header contains the endpoint to send reply messages. The reply message is required when the message is the request in a request-reply exchange; it is optional in other cases.
The "FaultTo" header (should there be one) contains the endpoint where fault messages should be sent. If "FaultTo" is absent, one may use the ReplyTo endpoint instead.
The "Source" endpoint indicates the endpoint that originated the message. The use of the Source header is optional in all cases, but it is useful in many situations, for example when no endpoint is explicitly provided to send replies to, or when it is different from the endpoint that originated the message. The Source header also allows the receiving endpoint to keep track of who is sending the message, regardless of who needs to receive the answer or whether there will be an answer at all.

Two additional headers are provided to allow defining relationships between individual messages.

The "MessageId" header contains a URI value that uniquely identifies the message that carries it. Message identifiers make it possible to reference individual messages and define relationships between them. The MessageId field is only required when the message is the request in a request-reply exchange.
The "RelatesTo" header contains a URI value that must be the MessageId of a previously exchanged message. It defines the current message relationship to the message that is being identified. The "RelationshipType" attribute in this header specifies what type of correlation between the two messages is being asserted.

The relationship type is represented by a qualified name. WS-Addressing defines one such relationship to be represented by the qualified name "wsa:Reply." It indicates that the message is the reply to a prior request, as part of a request-reply message exchange. Other relationship types will be defined in the future to support more complex relationships between messages derived from other message exchange patterns.

To illustrate how these headers are used together, this chapter examines how a service endpoint manipulates headers in the course of a request-reply interaction and uses the endpoint references provided in an incoming message to direct the response to the appropriate target. Before going into that, however, it's necessary to examine how to formulate a SOAP message addressed to an endpoint using the information contained in the endpoint reference.

5.2.4. Binding Endpoint References to SOAP Messages

WS-Addressing defines how to encode the fields of an endpoint reference as SOAP headers when directing a SOAP message to the endpoint. In the message one must only encode the runtime information from the endpoint reference:

The URI value of the Address field in the endpoint reference is copied as the value of the To header in the SOAP message.
Each reference property element is copied as an individual SOAP header.
Each reference parameter element is copied as an individual SOAP header.

The sender of the message (the "consumer" application for the endpoint reference) treats reference properties and parameters as opaque tokens and limits its manipulation to steps 2 and 3. On the receiving side, headers that originate from reference properties are extracted by the service middleware and used to route the message to the appropriate processing endpoints. Reference parameters are made available but are not required for routing. Even though reference properties are not identified as such on a SOAP message, they are always known to the receiving side, because the service middleware defines and encodes them when issuing the endpoint reference.

The relationship among the information in the endpoint reference, the WSDL definition, and the WS-Addressing message headers that appear in a SOAP message is illustrated in Figure 5-1.

Figure 5-1. WS-Addressing in SOAP messages.

5.2.5. Request-Reply Pattern in WS-Addressing

Even though WS-Addressing can support many other message exchange patterns, the request-reply pattern is particularly prevalent. For that reason, the request-reply pattern is explicitly discussed in the WS-Addressing specification. The specification provides normative guidance for the encoding of the request and reply messages.

Request Message

In the formulation of a request message, the ReplyTo and MessageID headers are mandatory. A ReplyTo header is naturally required when asynchronous responses are needed to indicate where to send the asynchronous reply. In the case of synchronous request-reply interaction, the reply message is sent back through the open channel used by the synchronous transport (typically HTTP) to deliver the request. WS-Addressing requires that the ReplyTo header also be included in synchronous request-reply interactions and mandates the encoding of an endpoint reference whose address URI is a predefined URI introduced by the specification to represent anonymous endpoints. Although the ReplyTo header is strictly unnecessary in this case, the resulting simplification has significant value. One of the consequences is to allow the service middleware on the receiving side to infer from the message headers whether a reply is expected, permitting more efficient processing of one-way requests. (For instance, one may close a connection as soon as it is determined that that no reply is expected.)

The presence of a message identifier supports correlating the asynchronous reply to the original request. Again, although it's not strictly required in the synchronous case, the requirement provides a uniform model for all requests and simplifies the encoding at the requester side and processing at the provider side.

Reply Message

To formulate a reply, the endpoint must follow three mandatory steps:

Extract the ReplyTo endpoint reference and use its contents to address the new reply message. In the case of a SOAP message, the rules to map its contents of the endpoint reference to SOAP headers are the ones defined before: the Address field is copied into the To header, while all reference properties and parameters become additional SOAP headers.
The RelatesTo header must be included, and the message identifier of the request is copied as its value. This allows the correlation of the reply with the original request.
The RelationshipType field is set to a value of "wsa:Reply" indicating that the message is a response message to the one identified by the value of the RelatesTo header.

Figure 5-2 illustrates how rules map the information that is contained in the request message and the WSDL definition of the invoked operation into the reply message.

Figure 5-2. WS-Addressing headers in response messages.

One interesting consequence of WS-Addressing and its normative support for request-reply interactions is the introduction of a more dynamic model for service interactions. Consider a service that, according to its WSDL service description, offers a request-reply operation over a synchronous protocol such as HTTP. Requesters who invoked the service would assume that the service returned its responses over the open HTTP channel. Assuming WS-Addressing compliance implies that requesters now have full control over where and how the service will send its response. If the requester wants to receive the response in the traditional way, a ReplyTo header with the anonymous URI address would be encoded. However, if the requester encoded a different endpoint reference in the ReplyTo header, the service provider would accordingly change its usual behavior. Upon receiving the request, it would close the incoming HTTP connection, open a new one to the address encoded in the ReplyTo, and use it to send its reply message. The result is that WS-Addressing endows the requester with an unprecedented degree of control over service behavior, which might seem to violate the WSDL binding contract of the service. Of course, after a service states its support for WS-Addressing, users of the services must assume conformance with the normative processing of request-reply patterns as part of the service behaviors.