Chapter 40. Working with Contexts
JAX-WS uses contexts to pass metadata along the messaging chain. This metadata, depending on its scope, is accessible to implementation level code. It is also accessible to JAX-WS handlers that operate on the message below the implementation level.
40.1. Understanding 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
Handlerimplementations 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
APPLICATIONscope. Consumer implementations can only access properties that are set in the
Figure 40.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.
Figure 40.1. Message Contexts and Message Processing Path
How properties are stored in a context
The message contexts are all implementations of the
MessageContextinterface extends the
java.util.Map<String key, Object value>interface.
Mapobjects store information as key value pairs.
In a message context, properties are stored as name/value pairs. A property's key is a
Stringthat 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
UserInfoobject it is still returned from a message context as an
Objectobject that must be cast back into a
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:
- Properties scoped as
APPLICATIONare available to JAX-WS
Handlerimplementations, 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
- Properties scoped as
HANDLERare only available to JAX-WS
Handlerimplementations. Properties stored in a message context from a
Handlerimplementation are scoped as
You can change a property's scope using the message context's
setScope()method. Example 40.1, “The
MessageContext.setScope()Method” shows the method's signature.
Example 40.1. The
void setScope(String key,
The first parameter specifies the property's key. The second parameter specifies the new scope for the property. The scope can be either:
Overview of contexts in handlers
Classes that implement the JAX-WS
Handlerinterface have direct access to a message's context information. The message's context information is passed into the
Handlerimplementations 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
LogicalMessageContextobjects have methods that access the contents of the message body.
Overview of contexts in service implementations
Service implementations can access properties scoped as
APPLICATIONfrom the message context. The service provider's implementation object accesses the message context through the
For more information see Section 40.2, “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
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
APPLICATIONin its message context to the consumer implementation's response context.
For more information see Section 40.3, “Working with Contexts in a Consumer Implementation”.