Chapter 42. Working with Contexts

In many instances it is necessary to pass information about a message to other parts of an application. Apache CXF 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 42.1, “Message Contexts and Message Processing Path” shows how the context properties pass through Apache CXF. As a message passes through the messaging chain, its associated message context passes along with it.

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.

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

You can change a property's scope using the message context's setScope() method. Example 42.1, “The MessageContext.setScope() Method” shows the method's signature.

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

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.

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 Section 42.2, “Working with Contexts in a Service Implementation”.

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

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 Section 42.3, “Working with Contexts in a Consumer Implementation”.