org.apache.axis

Class MessageContext

public class MessageContext extends Object implements SOAPMessageContext

A MessageContext is the Axis implementation of the javax SOAPMessageContext class, and is core to message processing in handlers and other parts of the system. This class also contains constants for accessing some well-known properties. Using a hierarchical namespace is strongly suggested in order to lower the chance for conflicts. (These constants should be viewed as an explicit list of well known and widely used context keys, there's nothing wrong with directly using the key strings. This is the reason for the hierarchical constant namespace. Actually I think we might just list the keys in the docs and provide no such constants since they create yet another namespace, but we'd have no compile-time checks then. Whaddya think? - todo by Jacek)

Author: Doug Davis (dug@us.ibm.com) Jacek Kopecky (jacek@idoox.com)

Field Summary
static StringACCEPTMISSINGPARAMS
A boolean param, to control whether we accept missing parameters as nulls or refuse to acknowledge them.
static StringATTACHMENTS_DIR
The directory where in coming attachments are created.
static StringAUTHUSER
Place to store an AuthenticatedUser.
static StringCALL
If on the client - this is the Call object.
static StringENGINE_HANDLER
Contains an instance of Handler, which is the ServiceContext and the entrypoint of this service. (if it has been so configured - will our deployment tool do this by default?
static StringHTTP_TRANSPORT_VERSION
The value of the property is used by service WSDL generation (aka ?
static StringIS_MSG
Are we doing Msg vs RPC?
protected static Loglog
The Log used for logging all messages.
static StringQUIT_REQUESTED
Has a quit been requested?
protected static StringsystemTempDir
Temporary directory to store attachments.
static StringSECURITY_PROVIDER
The security provider.
static StringTRANS_URL
This String is the URL that the message came to.
static StringWSDLGEN_INTFNAMESPACE
The value of the property is used by service WSDL generation (aka ?
static StringWSDLGEN_SERV_LOC_URL
The value of the property is used by service WSDL generation (aka ?
Constructor Summary
MessageContext(AxisEngine engine)
Create a message context.
Method Summary
booleancontainsProperty(String name)
Returns true if the MessageContext contains a property with the specified name.
voiddispose()
if a message (or subclass) has any disposal needs, this method is where it goes.
protected voidfinalize()
during finalization, the dispose() method is called.
IteratorgetAllPropertyNames()
Returns an Iterator view of the names of the properties in this MessageContext and any parents of the LockableHashtable
AxisEnginegetAxisEngine()
Get the axis engine.
ClassLoadergetClassLoader()
Get the classloader, implicitly binding to the thread context classloader if an override has not been supplied.
static MessageContextgetCurrentContext()
Get the active message context.
MessagegetCurrentMessage()
Return the current (i.e. request before the pivot, response after) message.
StringgetEncodingStyle()
Returns the encoding style as a URI that should be used for the SOAP message.
booleangetMaintainSession()
Discover if we are maintaining session state.
SOAPMessagegetMessage()
Gets the SOAPMessage from this message context.
OperationDescgetOperation()
The current operation.
OperationDescgetOperationByQName(QName qname)
get the first possible operation that could match a body containing an element of the given QName.
StylegetOperationStyle()
Get the operation style.
UsegetOperationUse()
Get the operation use.
StringgetPassword()
Get the password.
booleangetPastPivot()
Determine when we've passed the pivot.
OperationDesc[]getPossibleOperationsByQName(QName qname)
Returns a list of operation descriptors that could may possibly match a body containing an element of the given QName.
ObjectgetProperty(String name)
Returns the value associated with the named property - or null if not defined/set.
IteratorgetPropertyNames()
Returns an Iterator view of the names of the properties in this MessageContext.
MessagegetRequestMessage()
Get the request message.
MessagegetResponseMessage()
Get the response message.
String[]getRoles()
Gets the SOAP actor roles associated with an execution of the HandlerChain and its contained Handler instances.
SchemaVersiongetSchemaVersion()
Get the XML schema version information.
SOAPServicegetService()
Get the SOAPService used to handle services in this context.
SessiongetSession()
Get the current session.
StringgetSOAPActionURI()
Get the soapAction URI.
SOAPConstantsgetSOAPConstants()
Get the SOAPConstants used by this message context.
StringgetStrProp(String propName)
Get a String property by name.
StringgetTargetService()
Get the name of the targed service for this message.
intgetTimeout()
Get timeout from our MessageContext.
StringgetTransportName()
The name of the transport for this context.
TypeMappinggetTypeMapping()
Return the type mapping currently in scope for our encoding style.
TypeMappingRegistrygetTypeMappingRegistry()
Get the currently in-scope type mapping registry.
StringgetUsername()
Get the user name.
booleanisClient()
Let us know whether this is the client or the server.
booleanisEncoded()
Indicates if the opration is encoded.
booleanisHighFidelity()
Read the high fidelity property.
booleanisPropertyTrue(String propName)
Tests to see if the named property is set in the 'bag', returning false if it is not present at all.
booleanisPropertyTrue(String propName, boolean defaultVal)
Test if a property is set to something we consider to be true in the 'bag'.
voidremoveProperty(String propName)
voidreset()
Return this context to a clean state.
voidsetClassLoader(ClassLoader cl)
Set a new classloader.
voidsetCurrentMessage(Message curMsg)
Set the current message.
voidsetEncodingStyle(String namespaceURI)
Sets the encoding style to the URI passed in.
voidsetHighFidelity(boolean highFidelity)
Set the high fidelity propert.
voidsetMaintainSession(boolean yesno)
Set whether we are maintaining session state.
voidsetMessage(SOAPMessage message)
Sets the SOAPMessage for this message context.
voidsetOperation(OperationDesc operation)
Set the current operation.
voidsetPassword(String password)
Set the password.
voidsetPastPivot(boolean pastPivot)
Indicate when we've passed the pivot.
voidsetProperty(String name, Object value)
Allows you to set a named property to the passed in value.
voidsetPropertyParent(Hashtable parent)
Set the Hashtable that contains the default values for our properties.
voidsetRequestMessage(Message reqMsg)
Set the request message, and make sure that message is associated with this MessageContext.
voidsetResponseMessage(Message respMsg)
Set the response message, and make sure that message is associated with this MessageContext.
voidsetRoles(String[] roles)
Set the SOAP actor roles associated with an executioni of CodeHandlerChain and its contained Handler instances.
voidsetSchemaVersion(SchemaVersion schemaVersion)
Set the XML schema version this message context will use.
voidsetService(SOAPService sh)
Set the SOAPService used to handle services in this context.
voidsetSession(Session session)
Set the current session.
voidsetSOAPActionURI(String SOAPActionURI)
Set the soapAction URI.
voidsetSOAPConstants(SOAPConstants soapConstants)
Set the SOAPConstants used by this message context.
voidsetTargetService(String tServ)
Set the target service for this message.
voidsetTimeout(int value)
Set timeout in our MessageContext.
voidsetTransportName(String transportName)
Set the transport name for this context.
voidsetTypeMappingRegistry(TypeMappingRegistry reg)
Replace the engine's type mapping registry with a local one.
voidsetUsername(String username)
Set the username.
voidsetUseSOAPAction(boolean useSOAPAction)
Enable or dissable the use of soap action information.
booleanuseSOAPAction()
Indicates wether the soap action URI is being used or not.

Field Detail

ACCEPTMISSINGPARAMS

public static final String ACCEPTMISSINGPARAMS
A boolean param, to control whether we accept missing parameters as nulls or refuse to acknowledge them.

ATTACHMENTS_DIR

public static final String ATTACHMENTS_DIR
The directory where in coming attachments are created.

AUTHUSER

public static final String AUTHUSER
Place to store an AuthenticatedUser.

CALL

public static final String CALL
If on the client - this is the Call object.

ENGINE_HANDLER

public static final String ENGINE_HANDLER
Contains an instance of Handler, which is the ServiceContext and the entrypoint of this service. (if it has been so configured - will our deployment tool do this by default? - todo by Jacek)

HTTP_TRANSPORT_VERSION

public static final String HTTP_TRANSPORT_VERSION
The value of the property is used by service WSDL generation (aka ?WSDL). Set this property to request a certain level of HTTP. The values MUST use org.apache.axis.transport.http.HTTPConstants.HEADER_PROTOCOL_10 for HTTP 1.0 The values MUST use org.apache.axis.transport.http.HTTPConstants.HEADER_PROTOCOL_11 for HTTP 1.1

IS_MSG

public static final String IS_MSG
Are we doing Msg vs RPC? - For Java Binding.

log

protected static Log log
The Log used for logging all messages.

QUIT_REQUESTED

public static final String QUIT_REQUESTED
Has a quit been requested? Hackish... but useful... -- RobJ

systemTempDir

protected static String systemTempDir
Temporary directory to store attachments.

SECURITY_PROVIDER

public static final String SECURITY_PROVIDER
The security provider.

TRANS_URL

public static final String TRANS_URL
This String is the URL that the message came to.

WSDLGEN_INTFNAMESPACE

public static final String WSDLGEN_INTFNAMESPACE
The value of the property is used by service WSDL generation (aka ?WSDL) For the service's interface namespace if not set TRANS_URL property is used.

WSDLGEN_SERV_LOC_URL

public static final String WSDLGEN_SERV_LOC_URL
The value of the property is used by service WSDL generation (aka ?WSDL). For the service's location if not set TRANS_URL property is used. (helps provide support through proxies.

Constructor Detail

MessageContext

public MessageContext(AxisEngine engine)
Create a message context.

Parameters: engine the controlling axis engine. Null is actually accepted here, though passing a null engine in is strongly discouraged as many of the methods assume that it is in fact defined.

Method Detail

containsProperty

public boolean containsProperty(String name)
Returns true if the MessageContext contains a property with the specified name.

Parameters: name Name of the property whose presense is to be tested

Returns: Returns true if the MessageContext contains the property; otherwise false

dispose

public void dispose()
if a message (or subclass) has any disposal needs, this method is where it goes. Subclasses *must* call super.dispose(), and be prepared to be called from the finalizer as well as earlier

finalize

protected void finalize()
during finalization, the dispose() method is called.

See Also: dispose

getAllPropertyNames

public Iterator getAllPropertyNames()
Returns an Iterator view of the names of the properties in this MessageContext and any parents of the LockableHashtable

Returns: Iterator for the property names

getAxisEngine

public AxisEngine getAxisEngine()
Get the axis engine. This will be null if the message was created outside an engine

Returns: the current axis engine

getClassLoader

public ClassLoader getClassLoader()
Get the classloader, implicitly binding to the thread context classloader if an override has not been supplied.

Returns: the class loader

getCurrentContext

public static MessageContext getCurrentContext()
Get the active message context.

Returns: the current active message context

getCurrentMessage

public Message getCurrentMessage()
Return the current (i.e. request before the pivot, response after) message.

Returns: the current Message

getEncodingStyle

public String getEncodingStyle()
Returns the encoding style as a URI that should be used for the SOAP message.

Returns: String URI of the encoding style to use

getMaintainSession

public boolean getMaintainSession()
Discover if we are maintaining session state.

Returns: true if we are maintaining state, false otherwise

getMessage

public SOAPMessage getMessage()
Gets the SOAPMessage from this message context.

Returns: the SOAPMessage, null if no request SOAPMessage is present in this SOAPMessageContext

getOperation

public OperationDesc getOperation()
The current operation.

Returns: the current operation; may be null

getOperationByQName

public OperationDesc getOperationByQName(QName qname)
get the first possible operation that could match a body containing an element of the given QName. Sets the currentOperation field in the process; if that field is already set then its value is returned instead

Parameters: qname name of the message body

Returns: an operation or null

Throws: AxisFault

getOperationStyle

public Style getOperationStyle()
Get the operation style. This is either the style of the current operation or if that is not set, the style of the service handler, or if that is not set, Style.RPC.

Returns: the Style of this message

getOperationUse

public Use getOperationUse()
Get the operation use.

Returns: the operation Use

getPassword

public String getPassword()
Get the password.

Returns: the current password String

getPastPivot

public boolean getPastPivot()
Determine when we've passed the pivot.

Returns: true if we have, false otherwise

getPossibleOperationsByQName

public OperationDesc[] getPossibleOperationsByQName(QName qname)
Returns a list of operation descriptors that could may possibly match a body containing an element of the given QName. For non-DOCUMENT, the list of operation descriptors that match the name is returned. For DOCUMENT, all the operations that have qname as a parameter are returned

Parameters: qname of the first element in the body

Returns: list of operation descriptions

Throws: AxisFault if the operation names could not be looked up

getProperty

public Object getProperty(String name)
Returns the value associated with the named property - or null if not defined/set.

Parameters: name the property name

Returns: Object value of the property - or null

getPropertyNames

public Iterator getPropertyNames()
Returns an Iterator view of the names of the properties in this MessageContext.

Returns: an Iterator over all property names

getRequestMessage

public Message getRequestMessage()
Get the request message.

Returns: the request message (may be null).

getResponseMessage

public Message getResponseMessage()
Get the response message.

Returns: the response message (may be null).

getRoles

public String[] getRoles()
Gets the SOAP actor roles associated with an execution of the HandlerChain and its contained Handler instances.

Not (yet) implemented method in the SOAPMessageContext interface.

Note: SOAP actor roles apply to the SOAP node and are managed using HandlerChain.setRoles() and HandlerChain.getRoles(). Handler instances in the HandlerChain use this information about the SOAP actor roles to process the SOAP header blocks. Note that the SOAP actor roles are invariant during the processing of SOAP message through the HandlerChain.

Returns: an array of URIs for SOAP actor roles

See Also: (java.lang.String[]) HandlerChain.setRoles(java.lang.String[]) HandlerChain.getRoles()

getSchemaVersion

public SchemaVersion getSchemaVersion()
Get the XML schema version information.

Returns: the SchemaVersion in use

getService

public SOAPService getService()
Get the SOAPService used to handle services in this context.

Returns: the service handler

getSession

public Session getSession()
Get the current session.

Returns: the Session this message context is within

getSOAPActionURI

public String getSOAPActionURI()
Get the soapAction URI.

Returns: the URI of this soap action

getSOAPConstants

public SOAPConstants getSOAPConstants()
Get the SOAPConstants used by this message context.

Returns: the soap constants

getStrProp

public String getStrProp(String propName)
Get a String property by name.

Parameters: propName the name of the property to fetch

Returns: the value of the named property

Throws: ClassCastException if the property named does not have a String value

getTargetService

public String getTargetService()
Get the name of the targed service for this message.

Returns: the target service

getTimeout

public int getTimeout()
Get timeout from our MessageContext.

Returns: value the maximum amount of time, in milliseconds

getTransportName

public String getTransportName()
The name of the transport for this context.

Returns: the transport name

getTypeMapping

public TypeMapping getTypeMapping()
Return the type mapping currently in scope for our encoding style.

Returns: the type mapping

getTypeMappingRegistry

public TypeMappingRegistry getTypeMappingRegistry()
Get the currently in-scope type mapping registry. By default, will return a reference to the AxisEngine's TMR until someone sets our local one (usually as a result of setting the serviceHandler).

Returns: the type mapping registry to use for this request.

getUsername

public String getUsername()
Get the user name.

Returns: the user name as a String

isClient

public boolean isClient()
Let us know whether this is the client or the server.

Returns: true if we are a client

isEncoded

public boolean isEncoded()
Indicates if the opration is encoded.

Returns: true if it is encoded, false otherwise

isHighFidelity

public boolean isHighFidelity()
Read the high fidelity property.

Some behavior may be apropreate for high fidelity contexts that is not relevant for low fidelity ones or vica-versa.

Returns: true if the context is high fidelity, false otherwise

isPropertyTrue

public boolean isPropertyTrue(String propName)
Tests to see if the named property is set in the 'bag', returning false if it is not present at all. This is equivalent to isPropertyTrue(propName, false).

Parameters: propName the name of the property to check

Returns: true or false, depending on the value of the property

isPropertyTrue

public boolean isPropertyTrue(String propName, boolean defaultVal)
Test if a property is set to something we consider to be true in the 'bag'.

Parameters: propName the name of the property to check defaultVal the default value

Returns: true or false, depending on the value of the property

removeProperty

public void removeProperty(String propName)

reset

public void reset()
Return this context to a clean state.

setClassLoader

public void setClassLoader(ClassLoader cl)
Set a new classloader. Setting to null will result in getClassLoader() binding back to the thread context class loader.

Parameters: cl the new ClassLoader or null

setCurrentMessage

public void setCurrentMessage(Message curMsg)
Set the current message. This will set the request before the pivot, and the response afterwards, as guaged by the passedPivod property.

Parameters: curMsg the Message to assign

setEncodingStyle

public void setEncodingStyle(String namespaceURI)
Sets the encoding style to the URI passed in.

Parameters: namespaceURI URI of the encoding to use.

setHighFidelity

public void setHighFidelity(boolean highFidelity)
Set the high fidelity propert.

Users of the context may be changing what they do based upon this flag.

Parameters: highFidelity the new value of the highFidelity property

setMaintainSession

public void setMaintainSession(boolean yesno)
Set whether we are maintaining session state.

Parameters: yesno flag to set to true to maintain sessions

setMessage

public void setMessage(SOAPMessage message)
Sets the SOAPMessage for this message context. This is equivalent to casting message to Message and then passing it on to setCurrentMessage().

Parameters: message the SOAPMessage this context is for

setOperation

public void setOperation(OperationDesc operation)
Set the current operation.

Parameters: operation the Operation this context is executing

setPassword

public void setPassword(String password)
Set the password.

Parameters: password a String containing the new password

setPastPivot

public void setPastPivot(boolean pastPivot)
Indicate when we've passed the pivot.

Parameters: pastPivot true if we are past the pivot point, false otherwise

setProperty

public void setProperty(String name, Object value)
Allows you to set a named property to the passed in value. There are a few known properties (like username, password, etc) that are variables in Call. The rest of the properties are stored in a Hashtable. These common properties should be accessed via the accessors for speed/type safety, but they may still be obtained via this method. It's up to one of the Handlers (or the Axis engine itself) to go looking for one of them.

Parameters: name Name of the property value Value of the property

setPropertyParent

public void setPropertyParent(Hashtable parent)
Set the Hashtable that contains the default values for our properties.

Parameters: parent

setRequestMessage

public void setRequestMessage(Message reqMsg)
Set the request message, and make sure that message is associated with this MessageContext.

Parameters: reqMsg the new request Message.

setResponseMessage

public void setResponseMessage(Message respMsg)
Set the response message, and make sure that message is associated with this MessageContext.

Parameters: respMsg the new response Message.

setRoles

public void setRoles(String[] roles)
Set the SOAP actor roles associated with an executioni of CodeHandlerChain and its contained Handler instances.

Parameters: roles an array of String instances, each representing the URI for a SOAP actor role

setSchemaVersion

public void setSchemaVersion(SchemaVersion schemaVersion)
Set the XML schema version this message context will use.

Parameters: schemaVersion the new SchemaVersion

setService

public void setService(SOAPService sh)
Set the SOAPService used to handle services in this context. This method configures a wide range of MessageContext properties to suit the handler.

Parameters: sh the new service handler

Throws: AxisFault if the service could not be set

setSession

public void setSession(Session session)
Set the current session.

Parameters: session the new Session

setSOAPActionURI

public void setSOAPActionURI(String SOAPActionURI)
Set the soapAction URI.

Parameters: SOAPActionURI a String giving the new soap action URI

Throws: IllegalArgumentException if the URI is not liked

setSOAPConstants

public void setSOAPConstants(SOAPConstants soapConstants)
Set the SOAPConstants used by this message context. This may also affect the encoding style.

Parameters: soapConstants the new soap constants to use

setTargetService

public void setTargetService(String tServ)
Set the target service for this message.

This looks up the named service in the registry, and has the side effect of setting our TypeMappingRegistry to the service's.

Parameters: tServ the name of the target service

Throws: AxisFault if anything goes wrong in resolving or setting the service

setTimeout

public void setTimeout(int value)
Set timeout in our MessageContext.

Parameters: value the maximum amount of time, in milliseconds

setTransportName

public void setTransportName(String transportName)
Set the transport name for this context.

Parameters: transportName the name of the transport

setTypeMappingRegistry

public void setTypeMappingRegistry(TypeMappingRegistry reg)
Replace the engine's type mapping registry with a local one. This will have no effect on any type mappings obtained before this call.

Parameters: reg the new TypeMappingRegistry

setUsername

public void setUsername(String username)
Set the username.

Parameters: username the new user name

setUseSOAPAction

public void setUseSOAPAction(boolean useSOAPAction)
Enable or dissable the use of soap action information. When enabled, the message context will attempt to use the soap action URI information during binding of soap messages to service methods. When dissabled, it will make no such attempt.

Parameters: useSOAPAction true if soap action URI information should be used, false otherwise

useSOAPAction

public boolean useSOAPAction()
Indicates wether the soap action URI is being used or not.

Returns: true if it is, false otherwise

Copyright B) 2005 Apache Web Services Project. All Rights Reserved.