Understanding Contexts

Overview

In many instances it is necessary to pass information about a message to other parts of an application. FUSE Services Framework does this using a context mechanism. Contexts are maps that hold properties relating to an outgoing or an incoming message. The properties stored in the context are typically metadata about the message, and the underlying transport used to communicate the message. For example, the transport specific headers used in transmitting the message, such as the HTTP response code or the JMS correlation ID, are stored in the JAX-WS contexts.

The contexts are available at all levels of a JAX-WS application. However, they differ in subtle ways depending upon where in the message processing stack you are accessing the context. JAX-WS Handler implementations have direct access to the contexts and can access all properties that are set in them. Service implementations access contexts by having them injected, and can only access properties that are set in the APPLICATION scope. Consumer implementations can only access properties that are set in the APPLICATION scope.

Figure 20.1 shows how the context properties pass through FUSE Services Framework. As a message passes through the messaging chain, its associated message context passes along with it.

Figure 20.1. Message Contexts and Message Processing Path

message contexts are available through out the client and server message processing chains

How properties are stored in a context

The message contexts are all implementations of the javax.xml.ws.handler.MessageContext interface. The MessageContext interface extends the java.util.Map<String key, Object value> interface. Map objects store information as key value pairs.

In a message context, properties are stored as name/value pairs. A property's key is a String that identifies the property. The value of a property can be any value stored in any Java object. When the value is returned from a message context, the application must know the type to expect and cast accordingly. For example, if a property's value is stored in a UserInfo object it is still returned from a message context as an Object object that must be cast back into a UserInfo object.

Properties in a message context also have a scope. The scope determines where a property can be accessed in the message processing chain.

Property scopes

Properties in a message context are scoped. A property can be in one of the following scopes:

APPLICATION: Properties scoped as APPLICATION are available to JAX-WS Handler implementations, consumer implementation code, and service provider implementation code. If a handler needs to pass a property to the service provider implementation, it sets the property's scope to APPLICATION. All properties set from either the consumer implementation or the service provider implementation contexts are automatically scoped as APPLICATION.
HANDLER: Properties scoped as HANDLER are only available to JAX-WS Handler implementations. Properties stored in a message context from a Handler implementation are scoped as HANDLER by default.

You can change a property's scope using the message context's setScope() method. Example 20.1 shows the method's signature.

Example 20.1. The MessageContext.setScope() Method

void setScope(String key,
              MessageContext.Scope scope)
    throws java.lang.IllegalArgumentException;

The first parameter specifies the property's key. The second parameter specifies the new scope for the property. The scope can be either:

MessageContext.Scope.APPLICATION
MessageContext.Scope.HANDLER

Overview of contexts in handlers

Classes that implement the JAX-WS Handler interface have direct access to a message's context information. The message's context information is passed into the Handler implementation's handleMessage(), handleFault(), and close() methods.

Handler implementations have access to all of the properties stored in the message context, regardless of their scope. In addition, logical handlers use a specialized message context called a LogicalMessageContext. LogicalMessageContext objects have methods that access the contents of the message body.

Overview of contexts in service implementations

Service implementations can access properties scoped as APPLICATION from the message context. The service provider's implementation object accesses the message context through the WebServiceContext object.

For more information see Working with Contexts in a Service Implementation.

Overview of contexts in consumer implementations

Consumer implementations have indirect access to the contents of the message context. The consumer implementation has two separate message contexts:

Request context — holds a copy of the properties used for outgoing requests
Response context — holds a copy of the properties from an incoming response

The dispatch layer transfers the properties between the consumer implementation's message contexts and the message context used by the Handler implementations.

When a request is passed to the dispatch layer from the consumer implementation, the contents of the request context are copied into the message context that is used by the dispatch layer. When the response is returned from the service, the dispatch layer processes the message and sets the appropriate properties into its message context. After the dispatch layer processes a response, it copies all of the properties scoped as APPLICATION in its message context to the consumer implementation's response context.

For more information see Working with Contexts in a Consumer Implementation.