ws-axis-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From sam...@apache.org
Subject svn commit: r432655 - in /webservices/axis2/trunk/c: include/axis2_op_ctx.h modules/core/context/op_ctx.c
Date Fri, 18 Aug 2006 17:25:03 GMT
Author: samisa
Date: Fri Aug 18 10:25:03 2006
New Revision: 432655

URL: http://svn.apache.org/viewvc?rev=432655&view=rev
Log:
Fixed doc commetns and spellings

Modified:
    webservices/axis2/trunk/c/include/axis2_op_ctx.h
    webservices/axis2/trunk/c/modules/core/context/op_ctx.c

Modified: webservices/axis2/trunk/c/include/axis2_op_ctx.h
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/c/include/axis2_op_ctx.h?rev=432655&r1=432654&r2=432655&view=diff
==============================================================================
--- webservices/axis2/trunk/c/include/axis2_op_ctx.h (original)
+++ webservices/axis2/trunk/c/include/axis2_op_ctx.h Fri Aug 18 10:25:03 2006
@@ -19,23 +19,20 @@
 
 /**
  * @defgroup axis2_op_ctx operation context 
- * An op context represents a running "instance" of an op, which is
- * represented by an axis2_op struct. This concept is needed to allow
- * messages to be grouped into ops as in WSDL 2.0-speak ops are
- * essentially arbitrary message exchange patterns. So as messages are being
- * exchanged the op context remembers the state of where in the message
- * exchange pattern it is in.
- * The base implementation of op context
- * supports MEPs which have one input message and/or one output message. That
- * is, it supports the all the MEPs that are in the WSDL 2.0 specification. In
- * order to support another MEP one must extend this struct.
  * @ingroup axis2_context
+ * operation context represents a running "instance" of an operation.
+ * operation context allows messages to be grouped into operations as in 
+ * WSDL 2.0 specification. operations are essentially arbitrary message exchange 
+ * patterns (MEP). So as messages are being exchanged, operation context remembers 
+ * the state of message exchange pattern specifics.
+ * The implementation of operation context supports MEPs which have one input 
+ * message and/or one output message. In order to support other MEPs one must 
+ * extend this struct.
  * @{
  */
 
 /**
  * @file axis2_op_ctx.h
- * @brief axis2 Message Context interface
  */
 
 #include <axis2_defines.h>
@@ -53,17 +50,20 @@
     typedef struct axis2_op_ctx_ops axis2_op_ctx_ops_t;
     /** Type name for struct axis2_op_ctx */
     typedef struct axis2_op_ctx axis2_op_ctx_t;
+        
     struct axis2_svc_ctx;
 
     /**
-     * Message Context ops struct
-     * Encapsulator struct for ops of axis2_op_ctx
+     * operation context ops struct.
+     * Encapsulator struct for ops of axis2_op_ctx.
      */
     struct axis2_op_ctx_ops
     {
        /**
+        * Gets base which is of context type.
         * @param op_ctx pointer to operation context
         * @param env pointer to environment struct
+        * @return pointer to base context
         */
         axis2_ctx_t *(AXIS2_CALL *
                 get_base)(
@@ -71,8 +71,10 @@
                     const axis2_env_t *env);
 
        /**
+        * Frees operation context.
         * @param op_ctx pointer to operation context
         * @param env pointer to environment struct
+        * @return AXIS2_SUCCESS on success, else AXIS2_FAILURE
         */
         axis2_status_t (AXIS2_CALL *
                 free)(
@@ -80,10 +82,12 @@
                     const axis2_env_t *env);
 
         /**
-         * The method is used to do the intialization of the axis2_op_ctx
+         * Initializes operation context. This method traverses through all the 
+         * message contexts stored within it and initialize them all.
          * @param op_ctx pointer to operation context
-         * @param env pointer to enviornment struct
-         * @param conf pointer to conf 
+         * @param env pointer to environment struct
+         * @param conf pointer to conf configuration
+         * @return AXIS2_SUCCESS on success, else AXIS2_FAILURE
          */
         axis2_status_t (AXIS2_CALL *
                 init)(
@@ -92,9 +96,10 @@
                     struct axis2_conf *conf);
 
         /**
+         * Gets operation the operation context is related to.
          * @param op_ctx pointer to operation context
          * @param env pointer to environment struct
-         * @return Returns the op.
+         * @return pointer to operation
          */
         struct axis2_op *(AXIS2_CALL *
                 get_op)(
@@ -102,9 +107,11 @@
                     const axis2_env_t *env);
 
         /**
+         * Gets parent which is of service context type. 
          * @param op_ctx pointer to operation context
          * @param env pointer to environment struct
-         * @return Return the struct axis2_svc_ctx * in which this op_ctx lives.
+         * @return pointer to service context within which this operation 
+         * context lives
          */
         struct axis2_svc_ctx *(AXIS2_CALL *
                 get_parent)(
@@ -112,13 +119,12 @@
                     const axis2_env_t *env);
 
         /**
-         * When a new message is added to the <code>MEPContext</code> the logic
-         * should be included remove the MEPContext from the table in the
-         * <code>axis2_conf_ctx</code>. Example: IN_IN_OUT At the second IN
-         * message the MEPContext should be removed from the AxisOperation
+         * Adds a message context. 
          * @param op_ctx pointer to operation context
          * @param env pointer to environment struct
-         * @param msg_ctx pointer to message context
+         * @param msg_ctx pointer to message context struct, message context 
+         * does not assume the ownership of the struct
+         * @return AXIS2_SUCCESS on success, else AXIS2_FAILURE
          */
         axis2_status_t (AXIS2_CALL *
                 add_msg_ctx)(
@@ -127,9 +133,11 @@
                     axis2_msg_ctx_t *msg_ctx);
 
         /**
+         * Gets message context with the given message ID.
          * @param op_ctx pointer to operation context
          * @param env pointer to environment struct
-         * @param message_id ponter to message id
+         * @param message_id message ID string
+         * @return pointer to message context with given ID
          */
         axis2_msg_ctx_t *(AXIS2_CALL *
                 get_msg_ctx)(
@@ -138,10 +146,12 @@
                     const axis2_char_t *message_id);
 
         /**
-         * Checks to see if the MEP is complete. i.e. whether all the messages that
-         * are associated with the MEP has arrived and MEP is complete.
+         * Gets the bool value indicating if the MEP is complete.
+         * MEP is considered complete when all the messages that
+         * are associated with the MEP has arrived.
          * @param op_ctx pointer to operation context
          * @param env pointer to environment struct
+         * @return AXIS2_TRUE if MEP invocation is complete, else AXIS2_FALSE
          */
         axis2_bool_t (AXIS2_CALL *
                 get_is_complete)(
@@ -149,9 +159,14 @@
                     const axis2_env_t *env);
 
         /**
-         * @param op_ctx pointer to operatoin context
+         * Sets the bool value indicating if the MEP is complete.
+         * MEP is considered complete when all the messages that
+         * are associated with the MEP has arrived.
+         * @param op_ctx pointer to operating context
          * @param env pointer to environment struct
-         * @param is_complete is_complete
+         * @param is_complete AXIS2_TRUE if MEP invocation is complete, else 
+         * AXIS2_FALSE
+         * @return AXIS2_SUCCESS on success, else AXIS2_FAILURE
          */
         axis2_status_t (AXIS2_CALL *
                 set_complete)(
@@ -160,16 +175,11 @@
                     axis2_bool_t is_complete);
 
         /**
-         * Removes the pointers to this <code>op_ctx</code> in the
-         * <code>axis2_conf_ctx</code>'s op_ctxaxis2_hash_t *so that this
-         * <code>op_ctx</code> will eventually get garbage collected
-         * along with the <code>axis2_msg_ctx_t *</code>'s it contains. Note
that if
-         * the caller wants to make sure its safe to clean up this op_ctx
-         * he should call is_complete() first. However, in cases like IN_OPTIONAL_OUT
-         * and OUT_OPTIONAL_IN, it is possibe this will get called without the MEP
-         * being complete due to the optional nature of the MEP.
+         * Cleans up the operation context. Clean up includes removing all 
+         * message context references recorded in operation context.
          * @param op_ctx pointer to operation context
          * @param env pointer to environment struct
+         * @return AXIS2_SUCCESS on success, else AXIS2_FAILURE
          */
         axis2_status_t (AXIS2_CALL *
                 cleanup)(
@@ -177,9 +187,12 @@
                     const axis2_env_t *env);
 
         /**
+         * Sets parent service context.
          * @param op_ctx pointer to operation context
          * @param env pointer to environment struct
-         * @param svc_ctx pointer to service context
+         * @param svc_ctx pointer to service context, message context does not
+         * assume the ownership of the struct
+         * @return AXIS2_SUCCESS on success, else AXIS2_FAILURE
          */
         axis2_status_t (AXIS2_CALL *
                 set_parent)(
@@ -188,8 +201,10 @@
                     struct axis2_svc_ctx *svc_ctx);
 
         /**
+         * Gets the message context map.
          * @param op_ctx pointer to operation context
          * @param env pointer to environment struct
+         * @return pointer to hash table containing message contexts
          */
         axis2_hash_t *(AXIS2_CALL *
                 get_msg_ctx_map)(
@@ -199,19 +214,21 @@
     };
 
     /**
-     * operation context struct
+     * operation context struct.
      */
     struct axis2_op_ctx
     {
-        /** operatoins of operation context struct */
+        /** operations of operation context struct */
         axis2_op_ctx_ops_t *ops;
     };
 
     /**
-     * Creates a operation context struct
+     * Creates an operation context struct instance.
      * @param env pointer to environment struct
-     * @param op pointer to operation
-     * @param svc_ctx pointer to service context
+     * @param op pointer to operation that is related to operation context. 
+     * operation context does not assume the ownership of the struct
+     * @param svc_ctx pointer to parent service context
+     * @return pointer to newly created operation context
      */
     AXIS2_EXTERN axis2_op_ctx_t *AXIS2_CALL
     axis2_op_ctx_create(
@@ -219,69 +236,66 @@
        struct axis2_op *op,
        struct axis2_svc_ctx *svc_ctx);
 
-/************************** Start of function macros **************************/
 
-/** Gets the base.
+/** Gets base context struct.
     @sa axis2_op_ctx_ops#get_base */
 #define AXIS2_OP_CTX_GET_BASE(op_ctx, env) \
       ((op_ctx)->ops->get_base(op_ctx, env))
 
-/** Frees teh operation context.
+/** Frees operation context.
     @sa axis2_op_ctx_ops#free */
 #define AXIS2_OP_CTX_FREE(op_ctx, env)\
       ((op_ctx)->ops->free(op_ctx, env))
 
-/** Initialize the operation context.
+/** Initializes operation context.
     @sa axis2_op_ctx_ops#init */
 #define AXIS2_OP_CTX_INIT(op_ctx, env, conf) \
       ((op_ctx)->ops->init(op_ctx, env, conf))
 
-/** Gets the operaton.
+/** Gets operating related to operation context.
     @sa axis2_op_ctx_ops#get_op */
 #define AXIS2_OP_CTX_GET_OP(op_ctx, env)\
       ((op_ctx)->ops->get_op(op_ctx, env))
 
-/** Gets the parent.
+/** Gets parent which is of type service context.
     @sa axis2_op_ctx_ops#get_parent */
 #define AXIS2_OP_CTX_GET_PARENT(op_ctx, env) \
       ((op_ctx)->ops->get_parent(op_ctx, env))
 
-/** Adds the message context.
+/** Adds message context.
     @sa axis2_op_ctx_ops#add_msg_ctx */
 #define AXIS2_OP_CTX_ADD_MSG_CTX(op_ctx, env, msg_ctx) \
       ((op_ctx)->ops->add_msg_ctx(op_ctx, env, msg_ctx))
 
-/** Gets the message context.
+/** Gets message context with given message ID.
     @sa axis2_op_ctx_ops#get_msg_ctx */
 #define AXIS2_OP_CTX_GET_MSG_CTX(op_ctx, env, message_id) \
       ((op_ctx)->ops->get_msg_ctx(op_ctx, env, message_id))
 
-/** Get is complete.
+/** Gets bool value indicating the complete status.
     @sa axis2_op_ctx_ops#get_is_complete */
 #define AXIS2_OP_CTX_GET_IS_COMPLETE(op_ctx, env) \
       ((op_ctx)->ops->get_is_complete(op_ctx, env))
 
-/** Set is complete.
+/** Sets bool value indicating the complete status.
     @sa axis2_op_ctx_ops#set_is_complete */
 #define AXIS2_OP_CTX_SET_IS_COMPLETE(op_ctx, env, is_complete) \
       ((op_ctx)->ops->set_complete(op_ctx, env, is_complete))
 
-/** Cleanup.
+/** Cleans up operation context.
     @sa axis2_op_ctx_ops#cleanup */
 #define AXIS2_OP_CTX_CLEANUP(op_ctx, env) \
       ((op_ctx)->ops->cleanup(op_ctx, env))
 
-/** Set parent.
+/** Sets parent service context.
     @sa axis2_op_ctx_ops#set_parent */
 #define AXIS2_OP_CTX_SET_PARENT(op_ctx, env, svc_ctx) \
       ((op_ctx)->ops->set_parent(op_ctx, env, svc_ctx))
 
-/** Gets the message context map.
+/** Gets message context map.
     @sa axis2_op_ctx_ops#get_msg_ctx */
 #define AXIS2_OP_CTX_GET_MSG_CTX_MAP(op_ctx, env) \
       ((op_ctx)->ops->get_msg_ctx_map(op_ctx, env))
-
-/************************** End of function macros ****************************/
 
 /** @} */
 #ifdef __cplusplus

Modified: webservices/axis2/trunk/c/modules/core/context/op_ctx.c
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/c/modules/core/context/op_ctx.c?rev=432655&r1=432654&r2=432655&view=diff
==============================================================================
--- webservices/axis2/trunk/c/modules/core/context/op_ctx.c (original)
+++ webservices/axis2/trunk/c/modules/core/context/op_ctx.c Fri Aug 18 10:25:03 2006
@@ -26,30 +26,30 @@
     axis2_op_ctx_t op_ctx;
     /** base context struct */
     axis2_ctx_t *base;
-    /** parent of op context is a service context instance */
+    /** parent of operation context is a service context instance */
     struct axis2_svc_ctx *parent;
     /** message context map */
     axis2_hash_t *msg_ctx_map;
-    /** the op of which this is a running instance. The MEP of this
-     * op must be one of the 8 predefined ones in WSDL 2.0.
+    /** 
+     * the operation of which this is a running instance. The MEP of this
+     * operation must be one of the 8 predefined ones in WSDL 2.0.
      */
     axis2_op_t *op;
-    /** op Message Exchange Pattern */
+    /** operation Message Exchange Pattern (MEP) */
     int op_mep;
     /** is complete? */
     axis2_bool_t is_complete;
     /** the global message_id -> op_ctx map which is stored in
-     * the axis2_conf_ctx. We're caching it here for faster acccess.
+     * the axis2_conf_ctx. We are caching it here for faster access.
      */
     axis2_hash_t *op_ctx_map;
     /** op qname */
     axis2_qname_t *op_qname;
     /** service qname */
     axis2_qname_t *svc_qname;
-   /* Mutex to syncronize the read/write operations */
+   /* mutex to synchronize the read/write operations */
    axis2_thread_mutex_t *mutex;
-}
-axis2_op_ctx_impl_t;
+} axis2_op_ctx_impl_t;
 
 /** Interface to implementation conversion macro */
 #define AXIS2_INTF_TO_IMPL(op_ctx) ((axis2_op_ctx_impl_t *)op_ctx)
@@ -69,27 +69,24 @@
 axis2_op_ctx_init(
     struct axis2_op_ctx *op_ctx, 
     const axis2_env_t *env, 
-                 struct axis2_conf *conf);
+    struct axis2_conf *conf);
                  
 axis2_op_t *AXIS2_CALL 
 axis2_op_ctx_getAxisOperation(
     struct axis2_op_ctx *op_ctx, 
     const axis2_env_t *env);
 
-                             
 struct axis2_svc_ctx *AXIS2_CALL 
 axis2_op_ctx_get_parent(
     const axis2_op_ctx_t *op_ctx, 
     const axis2_env_t *env);
 
-                        
 axis2_status_t AXIS2_CALL 
 axis2_op_ctx_add_msg_ctx(
     struct axis2_op_ctx *op_ctx, 
     const axis2_env_t *env, 
     axis2_msg_ctx_t *msg_ctx);
 
-                        
 axis2_msg_ctx_t *AXIS2_CALL 
 axis2_op_ctx_get_msg_ctx(
     const axis2_op_ctx_t *op_ctx, 
@@ -176,7 +173,6 @@
         op_ctx_impl->op = op;
     }
     
-    
     op_ctx_impl->msg_ctx_map = axis2_hash_make(env);
     if (!(op_ctx_impl->msg_ctx_map))
     {
@@ -203,41 +199,29 @@
 
     op_ctx_impl->op_ctx.ops->get_base = 
         axis2_op_ctx_get_base;
-        
     op_ctx_impl->op_ctx.ops->free = 
         axis2_op_ctx_free;
-        
     op_ctx_impl->op_ctx.ops->init = 
         axis2_op_ctx_init;
-        
     op_ctx_impl->op_ctx.ops->get_op = 
         axis2_op_ctx_get_op;
-        
     op_ctx_impl->op_ctx.ops->get_parent = 
         axis2_op_ctx_get_parent;
-        
     op_ctx_impl->op_ctx.ops->add_msg_ctx = 
         axis2_op_ctx_add_msg_ctx;
-        
     op_ctx_impl->op_ctx.ops->get_msg_ctx = 
         axis2_op_ctx_get_msg_ctx;
-        
     op_ctx_impl->op_ctx.ops->get_is_complete = 
         axis2_op_ctx_get_is_complete;
-        
     op_ctx_impl->op_ctx.ops->set_complete = 
         axis2_op_ctx_set_complete;
-        
     op_ctx_impl->op_ctx.ops->cleanup = 
         axis2_op_ctx_cleanup;
-        
     op_ctx_impl->op_ctx.ops->set_parent = 
         axis2_op_ctx_set_parent;
-        
     op_ctx_impl->op_ctx.ops->get_msg_ctx_map = 
         axis2_op_ctx_get_msg_ctx_map;
         
-
     return &(op_ctx_impl->op_ctx);
 }
 
@@ -291,9 +275,6 @@
     return AXIS2_SUCCESS;
 }
 
-/**
- * The method is used to do the intialization of the axis2_op_ctx
- */
 axis2_status_t AXIS2_CALL 
 axis2_op_ctx_init(
     struct axis2_op_ctx *op_ctx, 
@@ -344,9 +325,6 @@
     return AXIS2_SUCCESS;
 }
 
-/**
- * @return Returns the op.
- */
 axis2_op_t *AXIS2_CALL 
 axis2_op_ctx_get_op(
     const axis2_op_ctx_t *op_ctx, 
@@ -356,10 +334,6 @@
     return AXIS2_INTF_TO_IMPL(op_ctx)->op;
 }
 
-/**
- * Return the struct axis2_svc_ctx * in which this op_ctx lives.
- * @return parent struct axis2_svc_ctx *
- */
 struct axis2_svc_ctx *AXIS2_CALL 
 axis2_op_ctx_get_parent(
     const axis2_op_ctx_t *op_ctx, 
@@ -369,13 +343,6 @@
     return AXIS2_INTF_TO_IMPL(op_ctx)->parent;
 }
 
-/**
- * When a new message is added to the <code>MEPContext</code> the logic
- * should be included remove the MEPContext from the table in the
- * <code>axis2_conf_ctx</code>. Example: IN_IN_OUT At the second IN
- * message the MEPContext should be removed from the AxisOperation
- * @param msgContext
- */
 axis2_status_t AXIS2_CALL 
 axis2_op_ctx_add_msg_ctx(
     struct axis2_op_ctx *op_ctx, 
@@ -402,11 +369,6 @@
     return AXIS2_SUCCESS;
 }
 
-/**
- * @param messageLabel
- * @return
- */
-
 axis2_msg_ctx_t *AXIS2_CALL 
 axis2_op_ctx_get_msg_ctx(
     const axis2_op_ctx_t *op_ctx, 
@@ -419,7 +381,7 @@
     
     op_ctx_impl = AXIS2_INTF_TO_IMPL(op_ctx);
     
-   axis2_thread_mutex_lock(op_ctx_impl->mutex);
+    axis2_thread_mutex_lock(op_ctx_impl->mutex);
     if (op_ctx_impl->msg_ctx_map)
     {
       axis2_msg_ctx_t *rv = NULL;
@@ -432,10 +394,6 @@
     return NULL;
 }
 
-/**
- * Checks to see if the MEP is complete. i.e. whether all the messages that
- * are associated with the MEP has arrived and MEP is complete.
- */
 axis2_bool_t AXIS2_CALL 
 axis2_op_ctx_get_is_complete(
     const axis2_op_ctx_t *op_ctx, 
@@ -456,16 +414,6 @@
     return AXIS2_SUCCESS;
 }
 
-/**
- * Removes the pointers to this <code>op_ctx</code> in the
- * <code>axis2_conf_ctx</code>'s op_ctxaxis2_hash_t *so that this
- * <code>op_ctx</code> will eventually get garbage collected
- * along with the <code>axis2_msg_ctx_t *</code>'s it contains. Note that if
- * the caller wants to make sure its safe to clean up this op_ctx
- * he should call is_complete() first. However, in cases like IN_OPTIONAL_OUT
- * and OUT_OPTIONAL_IN, it is possibe this will get called without the MEP
- * being complete due to the optional nature of the MEP.
- */
 axis2_status_t AXIS2_CALL 
 axis2_op_ctx_cleanup(
     struct axis2_op_ctx *op_ctx, 



---------------------------------------------------------------------
To unsubscribe, e-mail: axis-cvs-unsubscribe@ws.apache.org
For additional commands, e-mail: axis-cvs-help@ws.apache.org


Mime
View raw message