Chapter 16. The javax.xml.rpc.handler.soap Package

   

---

MessageContext

javax.xml.rpc.handler

---

JAX-RPC 1.0; JWSDP 1.0, J2EE 1.4

 public interface MessageContext {  // Public Instance Methods  public abstract boolean containsProperty( String   name   );      public abstract Object getProperty( String   name   );      public abstract Iterator getPropertyNames(  );      public abstract void removeProperty( String   name   );      public abstract void setProperty(String   name   ,  Object value); } 

A MessageContext object contains the state that accompanies a message as it traverses the pipeline from the sender to the network when being sent from the network to its eventual recipient for an inbound message. The MessageContext object is passed to the handleRequest( ) , handleResponse( ) , or handleFault( ) method of each handler in the handler chain on the message path (if there is one), depending on the message type and the direction in which it is moving. In addition, a service implementation that implements the javax.xml.rpc.server.ServiceLifecycle interface can access the MessageContext associated with the message that caused a service endpoint interface method to be invoked by calling the getMessageContext( ) method of the javax.xml.rpc.server.ServletEndpointContext object passed to its init( ) method.

The MessageContext interface is concerned only with providing a mechanism for information to be propagated along the message path. Since all message handlers in the chain receive a reference to the same MessageContext object during the processing of a single message, one handler can insert objects that another handler or the web service implementation class (in the case of a server-side message chain) can extract and possibly modify further. A client application, however, cannot access the MessageContext .

The setProperty( ) method can be used to store an object in the context using any string as the key. Calling setProperty( ) a second time with the same key has the effect of replacing the original value. The getProperty( ) method returns the object stored under the given key, or returns null if the key is not in use. To get a list of all of the property names in use, employ the getPropertyNames( ) method. To determine whether a property with a given name has been set, use the containsProperty( ) method; to remove a property, use removeProperty( ) . Refer to Chapter 6 for an example that demonstrates how to use properties to communicate information from a SOAP message header to the web service implementation that receives the message, without requiring the service implementation to know anything about SOAP messages.

Since message handlers deal with messages, it might at first sight be surprising that MessageContext does not have a method that provides access to the message itself. In order to preserve a degree of independence of the underlying messaging protocol, MessageContext delegates the responsibility for providing access to the message to derived interfaces that are specific to individual messaging protocols. In the case of SOAP, the MessageContext object is actually an instance of the derived interface javax.xml.rpc.soap.SOAPMessageContext , which does contain a method that allows access to the SOAP message being sent or received.

Implementations

javax.xml.rpc.handler.soap.SOAPMessageContext

Passed To

GenericHandler.{handleFault( ) , handleRequest( ) , handleResponse( )} , javax.xml.rpc.handler.Handler.{handleFault( ) , handleRequest( ) , handleResponse( )} , HandlerChain.{handleFault( ) , handleRequest( ) , handleResponse( )}

Returned By

javax.xml.rpc.server.ServletEndpointContext.getMessageContext( )

---