Working with Contexts in a Service Implementation

Overview

Context information is made available to service implementations using the WebServiceContext interface. From the WebServiceContext object you can obtain a MessageContext object that is populated with the current request's context properties in the application scope. You can manipulate the values of the properties, and they are propagated back through the response chain.

	Note
	The `MessageContext` interface inherits from the `java.util.Map` interface. Its contents can be manipulated using the `Map` interface's methods.

Obtaining a context

To obtain the message context in a service implementation do the following:

Declare a variable of type WebServiceContext.
Decorate the variable with the javax.annotation.Resource annotation to indicate that the context information is being injected into the variable.
Obtain the MessageContext object from the WebServiceContext object using the getMessageContext() method.
Important
getMessageContext() can only be used in methods that are decorated with the @WebMethod annotation.

Example 20.2 shows code for obtaining a context object.

Example 20.2. Obtaining a Context Object in a Service Implementation

import javax.xml.ws.*;
import javax.xml.ws.handler.*;
import javax.annotation.*;

@WebServiceProvider
public class WidgetServiceImpl
{
  @Resource
  WebServiceContext wsc;

  @WebMethod
  public String getColor(String itemNum)
  {
    MessageContext context = wsc.getMessageContext();
  }

  ...
}

Reading a property from a context

Once you have obtained the MessageContext object for your implementation, you can access the properties stored there using the get() method shown in Example 20.3.

Example 20.3. The MessageContext.get() Method

V get(Object key);

	Note
	This `get()` is inherited from the `Map` interface.

The key parameter is the string representing the property you want to retrieve from the context. The get() returns an object that must be cast to the proper type for the property. Table 20.1 lists a number of the properties that are available in a service implementation's context.

	Important
	Changing the values of the object returned from the context also changes the value of the property in the context.

Example 20.4 shows code for getting the name of the WSDL operation element that represents the invoked operation.

Example 20.4. Getting a Property from a Service's Message Context

import javax.xml.ws.handler.MessageContext;
import org.apache.cxf.message.Message;

  ...
  // MessageContext context retrieved in a previous example
  QName wsdl_operation = (QName)context.get(Message.WSDL_OPERATION);

Setting properties in a context

Once you have obtained the MessageContext object for your implementation, you can set properties, and change existing properties, using the put() method shown in Example 20.5.

Example 20.5. The MessageContext.put() Method

V put(K key,
      V value)
    throws ClassCastException, IllegalArgumentException, NullPointerException;

If the property being set already exists in the message context, the put() method replaces the existing value with the new value and returns the old value. If the property does not already exist in the message context, the put() method sets the property and returns null.

Example 20.6 shows code for setting the response code for an HTTP request.

Example 20.6. Setting a Property in a Service's Message Context

import javax.xml.ws.handler.MessageContext;
import org.apache.cxf.message.Message;

  ...
  // MessageContext context retrieved in a previous example
  context.put(Message.RESPONSE_CODE, new Integer(404));

Supported contexts

Table 20.1 lists the properties accessible through the context in a service implementation object.

Table 20.1. Properties Available in the Service Implementation Context

Base Class
Property Name	Description
`org.apache.cxf.message.Message`
`PROTOCOL_HEADERS`^[a]	Specifies the transport specific header information. The value is stored as a `java.util.Map<String, List<String>>`.
`RESPONSE_CODE`^[a]	Specifies the response code returned to the consumer. The value is stored as an `Integer` object.
`ENDPOINT_ADDRESS`	Specifies the address of the service provider. The value is stored as a `String`.
`HTTP_REQUEST_METHOD`^[a]	Specifies the HTTP verb sent with a request. The value is stored as a `String`.
`PATH_INFO`^[a]	Specifies the path of the resource being requested. The value is stored as a `String`. The path is the portion of the URI after the hostname and before any query string. For example, if an endpoint's URI is `http://cxf.apache.org/demo/widgets` the path is `/demo/widgets`.
`QUERY_STRING`^[a]	Specifies the query, if any, attached to the URI used to invoke the request. The value is stored as a `String`. Queries appear at the end of the URI after a `?`. For example, if a request is made to `http://cxf.apache.org/demo/widgets?color` the query is `color`.
`MTOM_ENABLED`	Specifies whether or not the service provider can use MTOM for SOAP attachments. The value is stored as a `Boolean`.
`SCHEMA_VALIDATION_ENABLED`	Specifies whether or not the service provider validates messages against a schema. The value is stored as a `Boolean`.
`FAULT_STACKTRACE_ENABLED`	Specifies if the runtime provides a stack trace along with a fault message. The value is stored as a `Boolean`.
`CONTENT_TYPE`	Specifies the MIME type of the message. The value is stored as a `String`.
`BASE_PATH`	Specifies the path of the resource being requested. The value is stored as a `java.net.URL`. The path is the portion of the URI after the hostname and before any query string. For example, if an endpoint's URL is `http://cxf.apache.org/demo/widgets` the base path is `/demo/widgets`.
`ENCODING`	Specifies the encoding of the message. The value is stored as a `String`.
`FIXED_PARAMETER_ORDER`	Specifies whether the parameters must appear in the message in a particular order. The value is stored as a `Boolean`.
`MAINTAIN_SESSION`	Specifies if the consumer wants to maintain the current session for future requests. The value is stored as a `Boolean`.
`WSDL_DESCRIPTION`^[a]	Specifies the WSDL document that defines the service being implemented. The value is stored as a `org.xml.sax.InputSource` object.
`WSDL_SERVICE`^[a]	Specifies the qualified name of the `wsdl:service` element that defines the service being implemented. The value is stored as a `QName`.
`WSDL_PORT`^[a]	Specifies the qualified name of the `wsdl:port` element that defines the endpoint used to access the service. The value is stored as a `QName`.
`WSDL_INTERFACE`^[a]	Specifies the qualified name of the `wsdl:portType` element that defines the service being implemented. The value is stored as a `QName`.
`WSDL_OPERATION`^[a]	Specifies the qualified name of the `wsdl:operation` element that corresponds to the operation invoked by the consumer. The value is stored as a `QName`.
`javax.xml.ws.handler.MessageContext`
`MESSAGE_OUTBOUND_PROPERTY`	Specifies if a message is outbound. The value is stored as a `Boolean`. `true` specifies that a message is outbound.
`INBOUND_MESSAGE_ATTACHMENTS`	Contains any attachments included in the request message. The value is stored as a `java.util.Map<String, DataHandler>`. The key value for the map is the MIME Content-ID for the header.
`OUTBOUND_MESSAGE_ATTACHMENTS`	Contains any attachments for the response message. The value is stored as a `java.util.Map<String, DataHandler>`. The key value for the map is the MIME Content-ID for the header.
`WSDL_DESCRIPTION`	Specifies the WSDL document that defines the service being implemented. The value is stored as a `org.xml.sax.InputSource` object.
`WSDL_SERVICE`	Specifies the qualified name of the `wsdl:service` element that defines the service being implemented. The value is stored as a `QName`.
`WSDL_PORT`	Specifies the qualified name of the `wsdl:port` element that defines the endpoint used to access the service. The value is stored as a `QName`.
`WSDL_INTERFACE`	Specifies the qualified name of the `wsdl:portType` element that defines the service being implemented. The value is stored as a `QName`.
`WSDL_OPERATION`	Specifies the qualified name of the `wsdl:operation` element that corresponds to the operation invoked by the consumer. The value is stored as a `QName`.
`HTTP_RESPONSE_CODE`	Specifies the response code returned to the consumer. The value is stored as an `Integer` object.
`HTTP_REQUEST_HEADERS`	Specifies the HTTP headers on a request. The value is stored as a `java.util.Map<String, List<String>>`.
`HTTP_RESPONSE_HEADERS`	Specifies the HTTP headers for the response. The value is stored as a `java.util.Map<String, List<String>>`.
`HTTP_REQUEST_METHOD`	Specifies the HTTP verb sent with a request. The value is stored as a `String`.
`SERVLET_REQUEST`	Contains the servlet's request object. The value is stored as a `javax.servlet.http.HttpServletRequest`.
`SERVLET_RESPONSE`	Contains the servlet's response object. The value is stored as a `javax.servlet.http.HttpResponse`.
`SERVLET_CONTEXT`	Contains the servlet's context object. The value is stored as a `javax.servlet.ServletContext`.
`PATH_INFO`	Specifies the path of the resource being requested. The value is stored as a `String`. The path is the portion of the URI after the hostname and before any query string. For example, if an endpoint's URL is `http://cxf.apache.org/demo/widgets` the path is `/demo/widgets`.
`QUERY_STRING`	Specifies the query, if any, attached to the URI used to invoke the request. The value is stored as a `String`. Queries appear at the end of the URI after a `?`. For example, if a request is made to `http://cxf.apache.org/demo/widgets?color` the query string is `color`.
`REFERENCE_PARAMETERS`	Specifies the WS-Addressing reference parameters. This includes all of the SOAP headers whose `wsa:IsReferenceParameter` attribute is set to `true`. The value is stored as a `java.util.List`.
`org.apache.cxf.transport.jms.JMSConstants`
`JMS_SERVER_HEADERS`	Contains the JMS message headers. For more information see Working with JMS Message Properties.
^[a]When using HTTP this property is the same as the standard JAX-WS defined property.

	Important
	`getMessageContext()` can only be used in methods that are decorated with the `@WebMethod` annotation.