Source code: org/apache/axis/MessageContext.java

   /*
    * Copyright 2001-2004 The Apache Software Foundation.
    * 
    * Licensed under the Apache License, Version 2.0 (the "License");
    * you may not use this file except in compliance with the License.
    * You may obtain a copy of the License at
    * 
    *      http://www.apache.org/licenses/LICENSE-2.0
    * 
   * Unless required by applicable law or agreed to in writing, software
   * distributed under the License is distributed on an "AS IS" BASIS,
   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   * See the License for the specific language governing permissions and
   * limitations under the License.
   */
  
  package org.apache.axis ;
  
  import org.apache.axis.attachments.Attachments;
  import org.apache.axis.client.AxisClient;
  import org.apache.axis.components.logger.LogFactory;
  import org.apache.axis.description.OperationDesc;
  import org.apache.axis.description.ServiceDesc;
  import org.apache.axis.encoding.TypeMapping;
  import org.apache.axis.encoding.TypeMappingRegistry;
  import org.apache.axis.constants.Style;
  import org.apache.axis.constants.Use;
  import org.apache.axis.handlers.soap.SOAPService;
  import org.apache.axis.schema.SchemaVersion;
  import org.apache.axis.session.Session;
  import org.apache.axis.soap.SOAPConstants;
  import org.apache.axis.utils.JavaUtils;
  import org.apache.axis.utils.LockableHashtable;
  import org.apache.axis.utils.Messages;
  import org.apache.commons.logging.Log;
  
  import javax.xml.namespace.QName;
  import javax.xml.rpc.Call;
  import javax.xml.rpc.handler.soap.SOAPMessageContext;
  import java.io.File;
  import java.util.ArrayList;
  import java.util.Hashtable;
  
  // fixme: fields are declared throughout this class, some at the top, and some
  //  near to where they are used. We should move all field declarations into a
  //  single block - it makes it easier to see what is decalred in this class and
  //  what is inherited. It also makes it easier to find them.
  /**
   * 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)
   * @author Jacek Kopecky (jacek@idoox.com)
   */
  public class MessageContext implements SOAPMessageContext {
      /** The <code>Log</code> used for logging all messages. */
      protected static Log log =
              LogFactory.getLog(MessageContext.class.getName());
  
      /**
       * The request message.  If we're on the client, this is the outgoing
       * message heading to the server.  If we're on the server, this is the
       * incoming message we've received from the client.
       */
      private Message      requestMessage;
  
      /**
       * The response message.  If we're on the server, this is the outgoing
       * message heading back to the client.  If we're on the client, this is the
       * incoming message we've received from the server.
       */
      private Message      responseMessage;
  
      /**
       * That unique key/name that the next router/dispatch handler should use
       * to determine what to do next.
       */
      private String       targetService;
  
      /**
       * The name of the Transport which this message was received on (or is
      * headed to, for the client).
      */
     private String       transportName;
 
     /**
      * The default <code>ClassLoader</code> that this service should use.
      */
     private ClassLoader  classLoader;
 
     /**
      * The AxisEngine which this context is involved with.
      */
     private AxisEngine   axisEngine;
 
     /**
      * A Session associated with this request.
      */
     private Session      session;
 
     /**
      * Should we track session state, or not?
      * default is not.
      * Could potentially refactor this so that
      * maintainSession iff session != null...
      */
     private boolean      maintainSession = false;
 
     // fixme: ambiguity here due to lac of docs - havePassedPivot vs
     //  request/response, vs sending/processing & recieving/responding
     //  I may have just missed the key bit of text
     /**
      * Are we doing request stuff, or response stuff? True if processing
      * response (I think).
      */
     private boolean      havePassedPivot = false;
 
     /**
      * Maximum amount of time to wait on a request, in milliseconds.
      */
     private int          timeout = Constants.DEFAULT_MESSAGE_TIMEOUT;
 
     /**
      * An indication of whether we require "high fidelity" recording of
      * deserialized messages for this interaction.  Defaults to true for
      * now, and can be set to false, usually at service-dispatch time.
      */
     private boolean      highFidelity = true;
 
     /**
      * Storage for an arbitrary bag of properties associated with this
      * MessageContext.
      */
     private LockableHashtable bag = new LockableHashtable();
 
     /*
      * These variables are logically part of the bag, but are separated
      * because they are used often and the Hashtable is more expensive.
      *
      * fixme: this may be fixed by moving to a plain Map impl like HashMap.
      *  Alternatively, we could hide all this magic behind a custom Map impl -
      *  is synchronization on the map needed? these properties aren't
      *  synchronized so I'm guessing not.
      */
     private String  username       = null;
     private String  password       = null;
     private String  encodingStyle  = Use.ENCODED.getEncoding();
     private boolean useSOAPAction  = false;
     private String  SOAPActionURI  = null;
 
     /**
      * SOAP Actor roles.
      */
     private String[] roles;
 
     /** Our SOAP namespaces and such. */
     private SOAPConstants soapConstants = Constants.DEFAULT_SOAP_VERSION;
 
     /** Schema version information - defaults to 2001. */
     private SchemaVersion schemaVersion = SchemaVersion.SCHEMA_2001;
 
     /** Our current operation. */
     private OperationDesc currentOperation = null;
 
     /**
      * The current operation.
      *
      * @return the current operation; may be <code>null</code>
      */
     public  OperationDesc getOperation()
     {
         return currentOperation;
     }
 
     /**
      * Set the current operation.
      *
      * @param operation  the <code>Operation</code> this context is executing
      */
     public void setOperation(OperationDesc operation)
     {
         currentOperation = operation;
     }
 
     /**
      * 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
      *
      * @param qname of the first element in the body
      * @return list of operation descriptions
      * @throws AxisFault if the operation names could not be looked up
      */
     public OperationDesc [] getPossibleOperationsByQName(QName qname) throws AxisFault
     {
         if (currentOperation != null) {
             return new OperationDesc [] { currentOperation };
         }
 
         OperationDesc [] possibleOperations = null;
 
         if (serviceHandler == null) {
             try {
                 if (log.isDebugEnabled()) {
                     log.debug(Messages.getMessage("dispatching00",
                                                    qname.getNamespaceURI()));
                 }
 
                 // Try looking this QName up in our mapping table...
                 setService(axisEngine.getConfig().
                            getServiceByNamespaceURI(qname.getNamespaceURI()));
             } catch (ConfigurationException e) {
                 // Didn't find one...
             }
 
         }
 
         if (serviceHandler != null) {
             ServiceDesc desc = serviceHandler.getInitializedServiceDesc(this);
 
             if (desc != null) {
                 if (desc.getStyle() != Style.DOCUMENT) {
                     possibleOperations = desc.getOperationsByQName(qname);
                 } else {
                     // DOCUMENT Style
                     // Get all of the operations that have qname as
                     // a possible parameter QName
                     ArrayList allOperations = desc.getOperations();
                     ArrayList foundOperations = new ArrayList();
                     for (int i=0; i < allOperations.size(); i++ ) {
                         OperationDesc tryOp =
                             (OperationDesc) allOperations.get(i);
                         if (tryOp.getParamByQName(qname) != null) {
                             foundOperations.add(tryOp);
                         }
                     }
                     if (foundOperations.size() > 0) {
                         possibleOperations = (OperationDesc[])
                             JavaUtils.convert(foundOperations,
                                               OperationDesc[].class);
                     }
                 }
             }
         }
         return possibleOperations;
     }
 
     /**
      * 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
      * @param qname name of the message body
      * @return an operation or null
      * @throws AxisFault
      */
     public OperationDesc getOperationByQName(QName qname) throws AxisFault
     {
         if (currentOperation == null) {
             OperationDesc [] possibleOperations = getPossibleOperationsByQName(qname);
             if (possibleOperations != null && possibleOperations.length > 0) {
                 currentOperation = possibleOperations[0];
             }
         }
 
         return currentOperation;
     }
 
     /**
      * Get the active message context.
      *
      * @return the current active message context
      */
     public static MessageContext getCurrentContext() {
        return AxisEngine.getCurrentMessageContext();
     }
 
     /**
      * Temporary directory to store attachments.
      */
     protected static String systemTempDir= null;
     /**
      * set the temp dir
      * TODO: move this piece of code out of this class and into a utilities
      * class.
      */
     static {
         try {
             //get the temp dir from the engine
             systemTempDir=AxisProperties.getProperty(AxisEngine.ENV_ATTACHMENT_DIR);
         } catch(Throwable t) {
             systemTempDir= null;
         }
 
         if(systemTempDir== null) {
             try {
                 //or create and delete a file in the temp dir to make
                 //sure we have write access to it.
                 File tf= File.createTempFile("Axis", ".tmp");
                 File dir= tf.getParentFile();
                 if (tf.exists()) {
                     tf.delete();
                 }
                 if (dir != null) {
                   systemTempDir= dir.getCanonicalPath();
                 }
             } catch(Throwable t) {
                 log.debug("Unable to find a temp dir with write access");
                 systemTempDir= null;
             }
         }
     }
 
     /**
      * Create a message context.
      * @param 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.
      */
     public MessageContext(AxisEngine engine) {
         this.axisEngine = engine;
 
         if(null != engine){
             java.util.Hashtable opts= engine.getOptions();
             String attachmentsdir= null;
             if(null!=opts) {
                 attachmentsdir= (String) opts.get(AxisEngine.PROP_ATTACHMENT_DIR);
             }
             if(null == attachmentsdir) {
                 attachmentsdir= systemTempDir;
             }
             if(attachmentsdir != null){
                 setProperty(ATTACHMENTS_DIR, attachmentsdir);
             }
 
             // If SOAP 1.2 has been specified as the default for the engine,
             // switch the constants over.
             String defaultSOAPVersion = (String)engine.getOption(
                                                  AxisEngine.PROP_SOAP_VERSION);
             if (defaultSOAPVersion != null && "1.2".equals(defaultSOAPVersion)) {
                 setSOAPConstants(SOAPConstants.SOAP12_CONSTANTS);
             }
 
             String singleSOAPVersion = (String)engine.getOption(
                                         AxisEngine.PROP_SOAP_ALLOWED_VERSION);
             if (singleSOAPVersion != null) {
                 if ("1.2".equals(singleSOAPVersion)) {
                     setProperty(Constants.MC_SINGLE_SOAP_VERSION,
                                 SOAPConstants.SOAP12_CONSTANTS);
                 } else if ("1.1".equals(singleSOAPVersion)) {
                     setProperty(Constants.MC_SINGLE_SOAP_VERSION,
                                 SOAPConstants.SOAP11_CONSTANTS);
                 }
             }
         }
     }
 
     /**
      * during finalization, the dispose() method is called.
      * @see #dispose()
      */
     protected void finalize() {
         dispose();
     }
 
     /**
      * Mappings of QNames to serializers/deserializers (and therfore
      * to Java types).
      */
     private TypeMappingRegistry mappingRegistry = null;
 
     /**
      * Replace the engine's type mapping registry with a local one. This will
      * have no effect on any type mappings obtained before this call.
      *
      * @param reg  the new <code>TypeMappingRegistry</code>
      */
     public void setTypeMappingRegistry(TypeMappingRegistry reg) {
         mappingRegistry = reg;
     }
 
     /**
      * 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).
      *
      * @return the type mapping registry to use for this request.
      */
     public TypeMappingRegistry getTypeMappingRegistry() {
         if (mappingRegistry == null) {
             return axisEngine.getTypeMappingRegistry();
         }
 
         return mappingRegistry;
     }
 
     /**
      * Return the type mapping currently in scope for our encoding style.
      *
      * @return the type mapping
      */
     public TypeMapping getTypeMapping()
     {
         return (TypeMapping)getTypeMappingRegistry().
                 getTypeMapping(encodingStyle);
     }
 
     /**
      * The name of the transport for this context.
      *
      * @return the transport name
      */
     public String getTransportName()
     {
         return transportName;
     }
 
     // fixme: the transport names should be a type-safe e-num, or the range
     //  of legal values should be specified in the documentation and validated
     //  in the method (raising IllegalArgumentException)
     /**
      * Set the transport name for this context.
      *
      * @param transportName the name of the transport
      */
     public void setTransportName(String transportName)
     {
         this.transportName = transportName;
     }
 
     /**
      * Get the <code>SOAPConstants</code> used by this message context.
      *
      * @return the soap constants
      */
     public SOAPConstants getSOAPConstants() {
         return soapConstants;
     }
 
     /**
      * Set the <code>SOAPConstants</code> used by this message context.
      * This may also affect the encoding style.
      *
      * @param soapConstants  the new soap constants to use
      */
     public void setSOAPConstants(SOAPConstants soapConstants) {
         // when changing SOAP versions, remember to keep the encodingURI
         // in synch.
         if (this.soapConstants.getEncodingURI().equals(encodingStyle)) {
             encodingStyle = soapConstants.getEncodingURI();
         }
 
         this.soapConstants = soapConstants;
     }
 
     /**
      * Get the XML schema version information.
      *
      * @return the <code>SchemaVersion</code> in use
      */
     public SchemaVersion getSchemaVersion() {
         return schemaVersion;
     }
 
     /**
      * Set the XML schema version this message context will use.
      *
      * @param schemaVersion  the new <code>SchemaVersion</code>
      */
     public void setSchemaVersion(SchemaVersion schemaVersion) {
         this.schemaVersion = schemaVersion;
     }
 
     /**
      * Get the current session.
      *
      * @return the <code>Session</code> this message context is within
      */
     public Session getSession()
     {
         return session;
     }
 
     /**
      * Set the current session.
      *
      * @param session  the new <code>Session</code>
      */
     public void setSession(Session session)
     {
         this.session = session;
     }
 
     /**
      * Indicates if the opration is encoded.
      *
      * @return <code>true</code> if it is encoded, <code>false</code> otherwise
      */
     public boolean isEncoded() {
         return (getOperationUse() == Use.ENCODED);
         //return soapConstants.getEncodingURI().equals(encodingStyle);
     }
 
     /**
      * Set whether we are maintaining session state.
      *
      * @param yesno flag to set to <code>true</code> to maintain sessions
      */
     public void setMaintainSession (boolean yesno) {
         maintainSession = yesno;
     }
 
     /**
      * Discover if we are maintaining session state.
      *
      * @return <code>true</code> if we are maintaining state, <code>false</code>
      *              otherwise
      */
     public boolean getMaintainSession () {
         return maintainSession;
     }
 
     /**
      * Get the request message.
      *
      * @return the request message (may be null).
      */
     public Message getRequestMessage() {
         return requestMessage ;
     }
 
     /**
      * Set the request message, and make sure that message is associated
      * with this MessageContext.
      *
      * @param reqMsg the new request Message.
      */
     public void setRequestMessage(Message reqMsg) {
         requestMessage = reqMsg ;
         if (requestMessage != null) {
             requestMessage.setMessageContext(this);
         }
     }
 
     /**
      * Get the response message.
      *
      * @return the response message (may be null).
      */
     public Message getResponseMessage() { return responseMessage ; }
 
     /**
      * Set the response message, and make sure that message is associated
      * with this MessageContext.
      *
      * @param respMsg the new response Message.
      */
     public void setResponseMessage(Message respMsg) {
         responseMessage = respMsg;
         if (responseMessage != null) {
             responseMessage.setMessageContext(this);
 
             //if we have received attachments of a particular type
             // than that should be the default type to send.
             Message reqMsg = getRequestMessage();
             if (null != reqMsg) {
                 Attachments reqAttch = reqMsg.getAttachmentsImpl();
                 Attachments respAttch = respMsg.getAttachmentsImpl();
                 if (null != reqAttch && null != respAttch) {
                     if (respAttch.getSendType() == Attachments.SEND_TYPE_NOTSET)
                         //only if not explicity set.
                         respAttch.setSendType(reqAttch.getSendType());
                 }
             }
         }
     }
 
     /**
      * Return the current (i.e. request before the pivot, response after)
      * message.
      *
      * @return the current <code>Message</code>
      */
     public Message getCurrentMessage()
     {
         return (havePassedPivot ? responseMessage : requestMessage);
     }
 
     /**
      *  Gets the SOAPMessage from this message context.
      *
      *  @return the <code>SOAPMessage</code>, <code>null</code> if no request
      *          <code>SOAPMessage</code> is present in this
      *          <code>SOAPMessageContext</code>
      */
     public javax.xml.soap.SOAPMessage getMessage() {
         return getCurrentMessage();
     }
 
     /**
      * Set the current message. This will set the request before the pivot,
      * and the response afterwards, as guaged by the passedPivod property.
      *
      * @param curMsg  the <code>Message</code> to assign
      */
     public void setCurrentMessage(Message curMsg)
     {
         curMsg.setMessageContext(this);
 
         if (havePassedPivot) {
             responseMessage = curMsg;
         } else {
             requestMessage = curMsg;
         }
     }
 
     /**
      * Sets the SOAPMessage for this message context.
      * This is equivalent to casting <code>message</code> to
      * <code>Message</code> and then passing it on to
      * <code>setCurrentMessage()</code>.
      *
      * @param message  the <code>SOAPMessage</code> this context is for
      */
     public void setMessage(javax.xml.soap.SOAPMessage message) {
         setCurrentMessage((Message)message);
     }
 
     /**
      * Determine when we've passed the pivot.
      *
      * @return <code>true</code> if we have, <code>false</code> otherwise
      */
     public boolean getPastPivot()
     {
         return havePassedPivot;
     }
 
     // fixme: is there any legitimate case where we could pass the pivot and
     //  then go back again? Is there documentation about the life-cycle of a
     //  MessageContext, and in particular the re-use of instances that would be
     //  relevant?
     /**
      * Indicate when we've passed the pivot.
      *
      * @param pastPivot  true if we are past the pivot point, false otherwise
      */
     public void setPastPivot(boolean pastPivot)
     {
         havePassedPivot = pastPivot;
     }
 
     /**
      * Set timeout in our MessageContext.
      *
      * @param value the maximum amount of time, in milliseconds
      */
     public void setTimeout (int value) {
         timeout = value;
     }
 
     /**
      * Get timeout from our MessageContext.
      *
      * @return value the maximum amount of time, in milliseconds
      */
     public int getTimeout () {
         return timeout;
     }
 
     /**
      * Get the classloader, implicitly binding to the thread context
      * classloader if an override has not been supplied.
      *
      * @return the class loader
      */
     public ClassLoader getClassLoader() {
         if ( classLoader == null ) {
             classLoader = Thread.currentThread().getContextClassLoader();
         }
         return( classLoader );
     }
 
     /**
      * Set a new classloader. Setting to null will result in getClassLoader()
      * binding back to the thread context class loader.
      *
      * @param cl    the new <code>ClassLoader</code> or <code>null</code>
      */
     public void setClassLoader(ClassLoader cl ) {
         classLoader = cl ;
     }
 
     /**
      * Get the name of the targed service for this message.
      *
      * @return the target service
      */
     public String getTargetService() {
         return targetService;
     }
 
     /**
      * Get the axis engine. This will be <code>null</code> if the message was
      * created outside an engine
      *
      * @return the current axis engine
      */
     public AxisEngine getAxisEngine()
     {
         return axisEngine;
     }
 
     /**
      * Set the target service for this message.
      * <p>
      * This looks up the named service in the registry, and has
      * the side effect of setting our TypeMappingRegistry to the
      * service's.
      *
      * @param tServ the name of the target service
      * @throws AxisFault  if anything goes wrong in resolving or setting the
      *              service
      */
     public void setTargetService(String tServ) throws AxisFault {
         log.debug("MessageContext: setTargetService(" + tServ+")");
 
         if (tServ == null) {
             setService(null);
         }
         else {
             try {
                 setService(getAxisEngine().getService(tServ));
             } catch (AxisFault fault) {
                 // If we're on the client, don't throw this fault...
                 if (!isClient()) {
                     throw fault;
                 }
             }
         }
         targetService = tServ;
     }
 
     /** ServiceHandler is the handler that is the "service".  This handler
      * can (and probably will actually be a chain that contains the
      * service specific request/response/pivot point handlers
      */
     private SOAPService serviceHandler ;
 
     /**
      * Get the <code>SOAPService</code> used to handle services in this
      * context.
      *
      * @return the service handler
      */
     public SOAPService getService() {
         return  serviceHandler;
     }
 
     /**
      * Set the <code>SOAPService</code> used to handle services in this
      * context. This method configures a wide range of
      * <code>MessageContext</code> properties to suit the handler.
      *
      * @param sh the new service handler
      * @throws AxisFault if the service could not be set
      */
     public void setService(SOAPService sh) throws AxisFault
     {
         log.debug("MessageContext: setServiceHandler("+sh+")");
         serviceHandler = sh;
         if (sh != null) {
             if(!sh.isRunning()) {
                 throw new AxisFault(Messages.getMessage("disabled00"));
             }
             targetService = sh.getName();
             SOAPService service = sh;
             TypeMappingRegistry tmr = service.getTypeMappingRegistry();
             setTypeMappingRegistry(tmr);
 
             // styles are not "soap version aware" so compensate...
             setEncodingStyle(service.getUse().getEncoding());
 
             // This MessageContext should now defer properties it can't find
             // to the Service's options.
             bag.setParent(sh.getOptions());
 
             // Note that we need (or don't need) high-fidelity SAX recording
             // of deserialized messages according to the setting on the
             // new service.
             highFidelity = service.needsHighFidelityRecording();
 
             service.getInitializedServiceDesc(this);
         }
     }
 
     /**
      * Let us know whether this is the client or the server.
      *
      * @return true if we are a client
      */
     public boolean isClient()
     {
         return (axisEngine instanceof AxisClient);
     }
 
     // fixme: public final statics tend to go in a block at the top of the
     //  class deffinition, not marooned in the middle
     // fixme: chose public static final /or/ public final static
     /** 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)
      */
     public static final String ENGINE_HANDLER      = "engine.handler";
 
     /** This String is the URL that the message came to.
      */
     public static final String TRANS_URL           = "transport.url";
 
     /** Has a quit been requested? Hackish... but useful... -- RobJ */
     public static final String QUIT_REQUESTED = "quit.requested";
 
     /** Place to store an AuthenticatedUser. */
     public static final String AUTHUSER            = "authenticatedUser";
 
     /** If on the client - this is the Call object. */
     public static final String CALL                = "call_object" ;
 
     /** Are we doing Msg vs RPC? - For Java Binding. */
     public static final String IS_MSG              = "isMsg" ;
 
     /** The directory where in coming attachments are created. */
     public static final String ATTACHMENTS_DIR   = "attachments.directory" ;
 
     /** A boolean param, to control whether we accept missing parameters
      * as nulls or refuse to acknowledge them.
      */
     public final static String ACCEPTMISSINGPARAMS = "acceptMissingParams";
 
     /** 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.
      */
     public static final String WSDLGEN_INTFNAMESPACE      = "axis.wsdlgen.intfnamespace";
 
     /** 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.
      */
     public static final String WSDLGEN_SERV_LOC_URL      = "axis.wsdlgen.serv.loc.url";
 
     // fixme: should this be a type-safe e-num?
     /** 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
      */
     public static final String HTTP_TRANSPORT_VERSION  = "axis.transport.version";
 
     // fixme: is this the name of a security provider, or the name of a security
     //  provider class, or the actualy class of a security provider, or
     //  something else?
     /**
      * The security provider.
      */
     public static final String SECURITY_PROVIDER = "securityProvider";
 
     /*
      * IMPORTANT.
      * If adding any new constants to this class. Make them final. The
      * ones above are left non-final for compatibility reasons.
      */
 
     /**
      * Get a <code>String</code> property by name.
      *
      * @param propName the name of the property to fetch
      * @return the value of the named property
      * @throws ClassCastException if the property named does not have a
      *              <code>String</code> value
      */
     public String getStrProp(String propName) {
         return (String) getProperty(propName);
     }
 
     /**
      * Tests to see if the named property is set in the 'bag', returning
      * <code>false</code> if it is not present at all.
      * This is equivalent to <code>isPropertyTrue(propName, false)</code>.
      *
      * @param propName  the name of the property to check
      * @return true or false, depending on the value of the property
      */
     public boolean isPropertyTrue(String propName) {
         return isPropertyTrue(propName, false);
     }
 
     /**
      * Test if a property is set to something we consider to be true in the
      * 'bag'.
      * <ul>
      * <li>If not there then <code>defaultVal</code> is returned.</li>
      * <li>If there, then...<ul>
      *   <li>if its a <code>Boolean</code>, we'll return booleanValue()</li>
      *   <li>if its an <code>Integer</code>,  we'll return <code>false</code>
      *   if its <code>0</code> else <code>true</code></li>
      *   <li>if its a <code>String</code> we'll return <code>false</code> if its
      *   <code>"false"</code>" or <code>"0"</code> else <code>true</code></li>
      *   <li>All other types return <code>true</code></li>
      * </ul></li>
      * </ul>
      *
      * @param propName  the name of the property to check
      * @param defaultVal  the default value
      * @return true or false, depending on the value of the property
      */
     public boolean isPropertyTrue(String propName, boolean defaultVal) {
         return JavaUtils.isTrue(getProperty(propName), defaultVal);
     }
 
     /**
      * 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.
      *
      * @param name  Name of the property
      * @param value Value of the property
      */
     public void setProperty(String name, Object value) {
         if (name == null || value == null) {
             return;
             // Is this right?  Shouldn't we throw an exception like:
             // throw new IllegalArgumentException(msg);
         }
         else if (name.equals(Call.USERNAME_PROPERTY)) {
             if (!(value instanceof String)) {
                 throw new IllegalArgumentException(
                         Messages.getMessage("badProp00", new String[] {
                         name, "java.lang.String", value.getClass().getName()}));
             }
             setUsername((String) value);
         }
         else if (name.equals(Call.PASSWORD_PROPERTY)) {
             if (!(value instanceof String)) {
                 throw new IllegalArgumentException(
                         Messages.getMessage("badProp00", new String[] {
                         name, "java.lang.String", value.getClass().getName()}));
             }
             setPassword((String) value);
         }
         else if (name.equals(Call.SESSION_MAINTAIN_PROPERTY)) {
             if (!(value instanceof Boolean)) {
                 throw new IllegalArgumentException(
                         Messages.getMessage("badProp00", new String[]
                         {name,
                         "java.lang.Boolean",
                         value.getClass().getName()}));
             }
             setMaintainSession(((Boolean) value).booleanValue());
         }
         else if (name.equals(Call.SOAPACTION_USE_PROPERTY)) {
             if (!(value instanceof Boolean)) {
                 throw new IllegalArgumentException(
                         Messages.getMessage("badProp00", new String[]
                         {name,
                         "java.lang.Boolean",
                         value.getClass().getName()}));
             }
             setUseSOAPAction(((Boolean) value).booleanValue());
        }
        else if (name.equals(Call.SOAPACTION_URI_PROPERTY)) {
            if (!(value instanceof String)) {
                throw new IllegalArgumentException(
                        Messages.getMessage("badProp00", new String[]
                        {name,
                        "java.lang.String",
                        value.getClass().getName()}));
            }
            setSOAPActionURI((String) value);
        }
        else if (name.equals(Call.ENCODINGSTYLE_URI_PROPERTY)) {
            if (!(value instanceof String)) {
                throw new IllegalArgumentException(
                        Messages.getMessage("badProp00", new String[]
                        {name,
                        "java.lang.String",
                        value.getClass().getName()}));
            }
            setEncodingStyle((String) value);
        }
        else {
            bag.put(name, value);
        }
    } // setProperty

    /**
     *  Returns true if the MessageContext contains a property with the specified name.
     *  @param   name Name of the property whose presense is to be tested
     *  @return  Returns true if the MessageContext contains the
          property; otherwise false
     */
    public boolean containsProperty(String name) {
        Object propertyValue = getProperty(name);
        return (propertyValue != null);
    }

    /**
     * Returns an <code>Iterator</code> view of the names of the properties in
     * this <code>MessageContext</code>.
     *
     * @return an <code>Iterator</code> over all property names
     */
    public java.util.Iterator getPropertyNames() {
        // fixme: this is potentially unsafe for the caller - changing the
        //  properties will kill the iterator. Consider iterating over a copy:
        // return new HashSet(bag.keySet()).iterator();
        return bag.keySet().iterator();
    }

    /**
     *  Returns an Iterator view of the names of the properties 
     *  in this MessageContext and any parents of the LockableHashtable
     *  @return Iterator for the property names
     */
    public java.util.Iterator getAllPropertyNames() {
        return bag.getAllKeys().iterator();
    }

    /**
     * Returns the value associated with the named property - or null if not
     * defined/set.
     *
     * @param name  the property name
     * @return Object value of the property - or null
     */
    public Object getProperty(String name) {
        if (name != null) {
            if (name.equals(Call.USERNAME_PROPERTY)) {
                return getUsername();
            }
            else if (name.equals(Call.PASSWORD_PROPERTY)) {
                return getPassword();
            }
            else if (name.equals(Call.SESSION_MAINTAIN_PROPERTY)) {
                return getMaintainSession() ? Boolean.TRUE : Boolean.FALSE;
            }
            else if (name.equals(Call.OPERATION_STYLE_PROPERTY)) {
                return (getOperationStyle() == null) ? null : getOperationStyle().getName();
            }
            else if (name.equals(Call.SOAPACTION_USE_PROPERTY)) {
                return useSOAPAction() ? Boolean.TRUE : Boolean.FALSE;
            }
            else if (name.equals(Call.SOAPACTION_URI_PROPERTY)) {
                return getSOAPActionURI();
            }
            else if (name.equals(Call.ENCODINGSTYLE_URI_PROPERTY)) {
                return getEncodingStyle();
            }
            else if (bag == null) {
                return null;
            }
            else {
                return bag.get(name);
            }
        }
        else {
            return null;
        }
    }

    // fixme: this makes no copy of parent, so later modifications to parent
    //  can alter this context - is this intended? If so, it needs documenting.
    //  If not, it needs fixing.
    /**
     * Set the Hashtable that contains the default values for our
     * properties.
     *
     * @param parent
     */
    public void setPropertyParent(Hashtable parent)
    {
        bag.setParent(parent);
    }

    /**
     * Set the username.
     *
     * @param username  the new user name
     */
    public void setUsername(String username) {
        this.username = username;
    } // setUsername

    /**
     * Get the user name.
     *
     * @return the user name as a <code>String</code>
     */
    public String getUsername() {
        return username;
    } // getUsername

    /**
     * Set the password.
     *
     * @param password  a <code>String</code> containing the new password
     */
    public void setPassword(String password) {
        this.password = password;
    } // setPassword

    /**
     * Get the password.
     *
     * @return the current password <code>String</code>
     */
    public String getPassword() {
        return password;
    } // getPassword

    /**
     * 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, <code>Style.RPC</code>.
     *
     * @return the <code>Style</code> of this message
     */
    public Style getOperationStyle() {
        if (currentOperation != null) {
            return currentOperation.getStyle();
        }

        if (serviceHandler != null) {
            return serviceHandler.getStyle();
        }

        return Style.RPC;
    } // getOperationStyle

    /**
     * Get the operation use.
     *
     * @return the operation <code>Use</code>
     */
    public Use getOperationUse() {
        if (currentOperation != null) {
            return currentOperation.getUse();
        }

        if (serviceHandler != null) {
            return serviceHandler.getUse();
        }

        return Use.ENCODED;
    } // getOperationUse

    /**
     * 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.
     *
     * @param useSOAPAction  <code>true</code> if soap action URI information
     *              should be used, <code>false</code> otherwise
     */
    public void setUseSOAPAction(boolean useSOAPAction) {
        this.useSOAPAction = useSOAPAction;
    } // setUseSOAPAction

    // fixme: this doesn't follow beany naming conventions - should be
    //  isUseSOAPActions or getUseSOAPActions or something prettier
    /**
     * Indicates wether the soap action URI is being used or not.
     *
     * @return <code>true</code> if it is, <code>false</code> otherwise
     */
    public boolean useSOAPAction() {
        return useSOAPAction;
    } // useSOAPAction

    // fixme: this throws IllegalArgumentException but never raises it -
    //  perhaps in a sub-class?
    // fixme: IllegalArgumentException is unchecked. Best practice says you
    //  should document unchecked exceptions, but not list them in throws
    /**
     * Set the soapAction URI.
     *
     * @param SOAPActionURI  a <code>String</code> giving the new soap action
     *              URI
     * @throws IllegalArgumentException if the URI is not liked
     */
    public void setSOAPActionURI(String SOAPActionURI)
            throws IllegalArgumentException {
        this.SOAPActionURI = SOAPActionURI;
    } // setSOAPActionURI

    /**
     * Get the soapAction URI.
     *
     * @return the URI of this soap action
     */
    public String getSOAPActionURI() {
        return SOAPActionURI;
    } // getSOAPActionURI

    /**
     * Sets the encoding style to the URI passed in.
     *
     * @param namespaceURI URI of the encoding to use.
     */
    public void setEncodingStyle(String namespaceURI) {
        if (namespaceURI == null) {
            namespaceURI = Constants.URI_LITERAL_ENC;
        }
        else if (Constants.isSOAP_ENC(namespaceURI)) {
            namespaceURI = soapConstants.getEncodingURI();
        }

        encodingStyle = namespaceURI;
    } // setEncodingStype

    /**
     * Returns the encoding style as a URI that should be used for the SOAP
     * message.
     *
     * @return String URI of the encoding style to use
     */
    public String getEncodingStyle() {
        return encodingStyle;
    } // getEncodingStyle

    public void removeProperty(String propName)
    {
        if (bag != null) {
            bag.remove(propName);
        }
    }

    /**
     * Return this context to a clean state.
     */
    public void reset()
    {
        if (bag != null) {
            bag.clear();
        }
        serviceHandler = null;
        havePassedPivot = false;
        currentOperation = null;
    }

    /**
     * Read the high fidelity property.
     * <p>
     * Some behavior may be apropreate for high fidelity contexts that is not
     * relevant for low fidelity ones or vica-versa.
     *
     * @return <code>true</code> if the context is high fidelity,
     *              <code>false</code> otherwise
     */
    public boolean isHighFidelity() {
        return highFidelity;
    }

    /**
     * Set the high fidelity propert.
     * <p>
     * Users of the context may be changing what they do based upon this flag.
     *
     * @param highFidelity  the new value of the highFidelity property
     */
    public void setHighFidelity(boolean highFidelity) {
        this.highFidelity = highFidelity;
    }

    /**
     * Gets the SOAP actor roles associated with an execution of the
     * <code>HandlerChain</code> and its contained <code>Handler</code>
     * instances.
     * <p>
     * <i>Not (yet) implemented method in the SOAPMessageContext interface</i>.
     * <p>
     * <b>Note:</b> SOAP actor roles apply to the SOAP node and are managed
     * using <code>HandlerChain.setRoles()</code> and
     * <code>HandlerChain.getRoles()</code>. Handler instances in the
     * <code>HandlerChain</code> 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
     * <code>HandlerChain</code>.
     *
     * @return an array of URIs for SOAP actor roles
     * @see javax.xml.rpc.handler.HandlerChain#setRoles(java.lang.String[]) HandlerChain.setRoles(java.lang.String[])
     * @see javax.xml.rpc.handler.HandlerChain#getRoles() HandlerChain.getRoles()
     */
    public String[] getRoles() {
        //TODO: Flesh this out.
        return roles;
    }

    /**
     * Set the SOAP actor roles associated with an executioni of
     * <code>CodeHandlerChain</code> and its contained <code>Handler</code>
     * instances.
     *
     * @param roles an array of <code>String</code> instances, each representing
     *              the URI for a SOAP actor role
     */
    public void setRoles( String[] roles) {
        this.roles = roles;
    }

    /**
     * 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
     */
    public synchronized void dispose() {
        log.debug("disposing of message context");
        if(requestMessage!=null) {
            requestMessage.dispose();
            requestMessage=null;
        }
        if(responseMessage!=null) {
            responseMessage.dispose();
            responseMessage=null;
        }
    }
}