A little bit about Message Context in JAX-WS

by Rama Pulavarthi

Sometimes, Invoking Web Services require exchange of additional information or metadata (not captured in SOAP message). This metadata forms the context of message exchange and may in-turn change the way the message is processed. JAX-WS Specification defines some standard properties to describe the metadata and also provides a standard way to manipulate or exchange such information. I will briefly describe how such metadata is exchanged between various parts of the application and then go over the common usage of the standard properties defined by JAX-WS.

A client application can configure metadata through request context and response context of the BindingProvider ( instance of proxy or Dispatch). The request and response contexts are of type java.util.Map<String,Object> and are obtained using getRequestContext and getResponseContext methods of the BindingProvider. The following example shows how you can access/update request and response context.

Map requestContext = ((BindingProvider)stub).getRequestContext();
Map responseContext = ((BindingProvider)stub).getResponseContext();
Integer responseCode = (Integer) responseContext.get(MessageContext.HTTP_RESPONSE_CODE);

MessageContext is a bag of properties to hold the metadata during the message exchange. The data from the request context is used to initialize the message context of the outbound message before invoking the handlers. This MessageContext is available to the all handlers in the handler-chain through which they can share processing related state. The contents of the message context are used to initialize the response context for an inbound message after invoking any handlers. The following example shows how one can access message context in a handler.

Handler {
    boolean handleMessage(SOAPMessageContext smc) {
        Boolean outbound = smc.get(MessageContext.MESSAGE_OUTBOUND_PROPERTY);
        SOAPMessage sm = smc.getMessage();

JAX-WS also defines ways to exchange context from client to the service endpoint implementation using the protocol binding in use. In SOAP/HTTP, some of this information goes in the HTTP Headers or in the SOAP Message. The client or handler can also use SOAP headers to exchange additional information.

This metadata for each invocation is accessible to the endpoint implementation through WebServiceContext. The server runtime will inject the WebServiceContext on any field marked with @Resource. getMessageContext method of WebServiceContext provides access to message context The following example shows the way to obtain message context in endpoint implementation.

WebServiceContext wsContext;

public String echoHello(String msg) {
    MessageContext context = wsContext.getMessageContext();
    Map requestHeaders = (Map) context.get(MessageContext.HTTP_REQUEST_HEADERS) ;

As mentioned earlier, JAX-WS defines standard properties in BindingProvider and MessageContext that form the metadata. Most of the properties are self-explanatory by their name. Below, I list these standard properties as described in the JAX-WS specification. Refer to the API Javadoc for these two classes MessageContext and BindingProvider for more information. Some of the properties are applicable to outgoing message and the rest are applicable to incoming message. Properties on the BindingProvider are used to configure the client binding through request context. Properties set on request context of a BindingProvider (proxy) will be applied to all invocations using that proxy unless modified between invocations. The properties on response context hold the values for the last invocation. Listed below are the standard properties defined by JAX-WS.

BindingProvider Properties

ENDPOINT_ADDRESS_PROPERTY (Type: java.lang.String): This holds the target service endpoint address. This is generally used to set endpoint address on a Dispatch instance or to modify the endpoint address of the proxy.

SESSION_MAINTAIN_PROPERTY (Type: java.lang.Boolean): This boolean property is used by the client to indicate whether or not it wants to participate in a session with a service endpoint. If this property is set to true, the service client indicates that it wants the session to be maintained. If set to false, the session is not maintained. The default value for this property is false.

USERNAME_PROPERTY (Type: java.lang.String) and PASSWORD_PROPERTY (Type: java.lang.String): These properties are used for HTTP basic authentication.

SOAPACTION_USE_PROPERTY (Type: java.lang.Boolean): This property controls whether or not SOAPAction is to be used. The default value of this property is false indicating that the SOAPAction is not used.

SOAPACTION_URI_PROPERTY (Type: java.lang.String): Indicates the SOAPAction URI, if the javax.xml.ws.soap.http.soapaction.use property is set to true.

These above soap action properties are generally used for Dispatch clients. In case of proxy, by default, the soap action uri for a operation in the wsdl binding definition would determine its usage.

MessageContext Properties

MESSAGE_OUTBOUND_PROPERTY (Type: boolean): Specifies the message direction, true for outbound messages, false for inbound. This is used in handlers to determine if the processing is on a outbound or inbound message.

INBOUND_MESSAGE_ATTACHMENTS (Type: java.util.Map): A map of attachments to an inbound message. The key is the MIME Content-ID, value is a DataHandler for the attachment data. This property can be used to process the attachments in inbound message.

OUTBOUND_MESSAGE_ATTACHMENTS (Type: java.util.Map): A map of attachments to an outbound message. The key is the MIME Content-ID, value is a DataHandler for the attachment data. This property can be used on a proxy to send attachments not described through WSDL Mime binding.

The following properties are specific to HTTP protocol and are available only in HTTP based bindings.

HTTP_REQUEST_METHOD (Type: java.lang.String): Holds the name of the HTTP method with which this request was made, for example, GET, POST, or PUT.

HTTP_REQUEST_HEADERS (Type: java.util.Map): Holds a map of the HTTP headers for the request message.

QUERY_STRING (Type: String): Property for the HTTP Query String for the request message.

PATH_INFO (Type: String) : Extra path information associated with the request URL . This is the path information following the base url path but precedes the query string. QUERY_STRING and PATH_INFO properties are generally used with REST style clients, where the endpoint address is same and only the query string varies between each invocation.

HTTP_RESPONSE_CODE (Type: java.lang.Integer ) : Holds HTTP response status code for the last invocation.

HTTP_RESPONSE_HEADERS (Type: java.util.Map>) : Holds a map of the HTTP response headers.

These properties are specific to endpoints with HTTP based binding and running inside a servlet container.

SERVLET_CONTEXT (Type: javax.servlet.ServletContext): This property contains the ServletContext object belonging to the web application that contains the web endpoint.

SERVLET_REQUEST (Type: javax.servlet.http.HttpServletRequest ): This property holds the HTTPServletRequest object associated with the request currently being served.

SERVLET_RESPONSE (Type: javax.servlet.http.HttpServletResponse): This property holds the HTTPServletResponse object associated with the request currently being served.

These following properties are not mandatory and might be present only if the binding has information about WSDL metadata.

WSDL_DESCRIPTION (Type: java.net.URI): A resolvable URI that may be used to obtain access to the WSDL for the endpoint.

WSDL_SERVICE (Type: javax.xml.namespace.QName ): The name of the Service being invoked.

WSDL_PORT (Type: javax.xml.namespace.QName ): The name of the port to which the current message was received.

WSDL_INTERFACE (Type: javax.xml.namespace.QName ): The name of the port type to which the current message belongs.

WSDL_OPERATION (Type: javax.xml.namespace.QName ) :The name of the WSDL operation to which the current message belongs. The namespace is the target namespace of the WSDL definitions element.

In addition to these standard properties, User can define application specific properties in the message context to share state between client application and handlers, and handlers can insert this information as SOAP headers to convey the same information to service endpoint implementation.

In conclusion, JAX-WS provides you an easier and standard way to share the metadata across. Check out the latest JAX-WS 2.0 Reference Implementation and try it yourself. I hope this is useful for developers – Your comments are most welcome.

Rama Pulavarthi is a Member of Technical Staff in the Java Web Services group at Sun Microsystems. He currently works on the development of JAX-WS Reference Implementation. He has previously lead the Software Quality Engineering effort of JAX-RPC.

Terms of Use; Privacy Policy; Copyright ©2013-2015 (revision 20151030.c1dd42a)
Please Confirm