40.3. Working with Contexts in a Consumer Implementation

Overview

Consumer implementations have access to context information through the BindingProvider interface. The BindingProvider instance holds context information in two separate contexts:
  • Request Context
    The request context enables you to set properties that affect outbound messages. Request context properties are applied to a specific port instance and, once set, the properties affect every subsequent operation invocation made on the port, until such time as a property is explicitly cleared. For example, you might use a request context property to set a connection timeout or to initialize data for sending in a header.
  • Response Context
    The response context enables you to read the property values set by the response to the last operation invocation made from the current thread. Response context properties are reset after every operation invocation. For example, you might access a response context property to read header information received from the last inbound message.
Important
Only information that is placed in the application scope of a message context can be accessed by the consumer implementation.

Obtaining a context

Contexts are obtained using the javax.xml.ws.BindingProvider interface. The BindingProvider interface has two methods for obtaining a context:
  • getRequestContext()
    The getRequestContext() method, shown in Example 40.7, “The getRequestContext() Method”, returns the request context as a Map object. The returned Map object can be used to directly manipulate the contents of the context.

    Example 40.7. The getRequestContext() Method

    Map<String, Object> getRequestContext();
  • getResponseContext()
    The getResponseContext(), shown in Example 40.8, “The getResponseContext() Method”, returns the response context as a Map object. The returned Map object's contents reflect the state of the response context's contents from the most recent successful request on a remote service made in the current thread.

    Example 40.8. The getResponseContext() Method

    Map<String, Object> getResponseContext();
Since proxy objects implement the BindingProvider interface, a BindingProvider object can be obtained by casting a proxy object. The contexts obtained from the BindingProvider object are only valid for operations invoked on the proxy object used to create it.
Example 40.9, “Getting a Consumer's Request Context” shows code for obtaining the request context for a proxy.

Example 40.9. Getting a Consumer's Request Context

// Proxy widgetProxy obtained previously
BindingProvider bp = (BindingProvider)widgetProxy;
Map<String, Object> requestContext = bp.getRequestContext();

Reading a property from a context

Consumer contexts are stored in java.util.Map<String, Object> objects. The map has keys that are String objects and values that contain arbitrary objects. Use java.util.Map.get() to access an entry in the map of response context properties.
To retrieve a particular context property, ContextPropertyName, use the code shown in Example 40.10, “Reading a Response Context Property”.

Example 40.10. Reading a Response Context Property

// Invoke an operation.
port.SomeOperation();

// Read response context property.
java.util.Map<String, Object> responseContext =
  ((javax.xml.ws.BindingProvider)port).getResponseContext();
PropertyType propValue = (PropertyType) responseContext.get(ContextPropertyName);

Setting properties in a context

Consumer contexts are hash maps stored in java.util.Map<String, Object> objects. The map has keys that are String objects and values that are arbitrary objects. To set a property in a context use the java.util.Map.put() method.
Tip
While you can set properties in both the request context and the response context, only the changes made to the request context have any impact on message processing. The properties in the response context are reset when each remote invocation is completed on the current thread.
The code shown in Example 40.11, “Setting a Request Context Property” changes the address of the target service provider by setting the value of the BindingProvider.ENDPOINT_ADDRESS_PROPERTY.

Example 40.11. Setting a Request Context Property

// Set request context property.
java.util.Map<String, Object> requestContext =
     ((javax.xml.ws.BindingProvider)port).getRequestContext();
requestContext.put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, "http://localhost:8080/widgets");
     
// Invoke an operation.
port.SomeOperation();
Important
Once a property is set in the request context its value is used for all subsequent remote invocations. You can change the value and the changed value will then be used.

Supported contexts

Apache CXF supports the following context properties in consumer implementations:

Table 40.2. Consumer Context Properties

Base Class
Property NameDescription
javax.xml.ws.BindingProvider
ENDPOINT_ADDRESS_PROPERTYSpecifies the address of the target service. The value is stored as a String.
USERNAME_PROPERTY[a]Specifies the username used for HTTP basic authentication. The value is stored as a String.
PASSWORD_PROPERTY[b]Specifies the password used for HTTP basic authentication. The value is stored as a String.
SESSION_MAINTAIN_PROPERTY[c]Specifies if the client wants to maintain session information. The value is stored as a Boolean object.
org.apache.cxf.ws.addressing.JAXWSAConstants
CLIENT_ADDRESSING_PROPERTIESSpecifies the WS-Addressing information used by the consumer to contact the desired service provider. The value is stored as a org.apache.cxf.ws.addressing.AddressingProperties.
org.apache.cxf.transports.jms.context.JMSConstants
JMS_CLIENT_REQUEST_HEADERSContains the JMS headers for the message. For more information see Section 40.4, “Working with JMS Message Properties”.
[a] This property is overridden by the username defined in the HTTP security settings.
[b] This property is overridden by the password defined in the HTTP security settings.
[c] The Apache CXF ignores this property.