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 20.7, returns the request context as a Map object. The returned Map object can be used to directly manipulate the contents of the context.
Example 20.7. The getRequestContext() Method
Map<String, Object> getRequestContext();
getResponseContext(): The getResponseContext(), shown in Example 20.8, 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 20.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 20.9 shows code for obtaining the request context for a proxy.

Example 20.9. Getting a Consumer's Request Context

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

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 20.10.

Example 20.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 20.11 changes the address of the target service provider by setting the value of the BindingProvider.ENDPOINT_ADDRESS_PROPERTY.

Example 20.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

FUSE Services Framework supports the following context properties in consumer implementations:

Table 20.2. Consumer Context Properties

Base Class
Property Name	Description
`javax.xml.ws.BindingProvider`
`ENDPOINT_ADDRESS_PROPERTY`	Specifies 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_PROPERTIES`	Specifies 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_HEADERS`	Contains the JMS headers for the message. For more information see 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 FUSE Services Framework ignores this property.