You are viewing a plain text version of this content. The canonical link for it is here.
Posted to java-dev@axis.apache.org by sa...@apache.org on 2007/04/08 14:04:39 UTC
svn commit: r526540 -
/webservices/axis2/trunk/c/xdocs/docs/axis2c_manual.html
Author: samisa
Date: Sun Apr 8 05:04:38 2007
New Revision: 526540
URL: http://svn.apache.org/viewvc?view=rev&rev=526540
Log:
Fixed upto section 3 - service API
Modified:
webservices/axis2/trunk/c/xdocs/docs/axis2c_manual.html
Modified: webservices/axis2/trunk/c/xdocs/docs/axis2c_manual.html
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/c/xdocs/docs/axis2c_manual.html?view=diff&rev=526540&r1=526539&r2=526540
==============================================================================
--- webservices/axis2/trunk/c/xdocs/docs/axis2c_manual.html (original)
+++ webservices/axis2/trunk/c/xdocs/docs/axis2c_manual.html Sun Apr 8 05:04:38 2007
@@ -484,16 +484,17 @@
of this manual. This section would cover the service API of Axis2/C in a bit
more detail.</p>
-<p>The axis2_svc_skeleton is an interface. Axis2/C does not provide any
+<p><code>axis2_svc_skeleton</code> is an interface. Axis2/C does not provide any
concrete implementation of this interface. It is the responsibility of the
service implementer to implement this interface. To implement the interface,
one should implement functions adhering to the function pointer signatures of
-the members of axis2_svc_skeleton_ops struct. Then, a create function should
-be written, to create an axis2_svc_skeleton instance, and assign the
+the members of <code>axis2_svc_skeleton_ops</code> struct. Then, a create function should
+be written, to create an <code>axis2_svc_skeleton</code> instance, and assign the
implementing functions to members of the ops member of service skeleton.</p>
-<p>The following table details the function signatures to be implemented by a
-service.</p>
+<p>The following table details the signatures of the
+function pointer members of <code>axis2_svc_skeleton</code> struct
+to be implemented by a service.</p>
<table border="1">
<caption></caption>
@@ -503,16 +504,19 @@
<th>Description</th>
</tr>
<tr>
- <td><pre>axis2_status_t (AXIS2_CALL *
- free )( axis2_svc_skeleton_t *svc_skeli,
- const axis2_env_t *env);</pre>
+ <td><pre>int (AXIS2_CALL *
+ init)(axis2_svc_skeleton_t *svc_skeleton,
+ const axutil_env_t *env);</pre>
+ </td>
+ <td>Initializes the service skeleton object instance. Axis2/C engine
+ initializes a service skeleon instance once per a deployed service,
+ during the first request to the service.
</td>
- <td>Frees the service implementation instance.</td>
</tr>
<tr>
<td><pre>axiom_node_t *(AXIS2_CALL*
invoke )( axis2_svc_skeleton_t *svc_skeli,
- const axis2_env_t *env,
+ const axutil_env_t *env,
axiom_node_t *node,
axis2_msg_ctx_t *msg_ctx);</pre>
</td>
@@ -520,106 +524,60 @@
to call the correct functions in this method based on the name of the
operation being invoked.</td>
</tr>
+ <tr>
+ <td><pre>axiom_node_t *(AXIS2_CALL*
+ on_fault)(
+ axis2_svc_skeleton_t *svc_skeli,
+ const axutil_env_t *env,
+ axiom_node_t *node); </pre>
+ </td>
+ <td>This method would be called by the engine if a fault is detected.</td>
+ </tr>
+ <tr>
+ <td><pre>axis2_status_t (AXIS2_CALL *
+ free )( axis2_svc_skeleton_t *svc_skeli,
+ const axutil_env_t *env);</pre>
+ </td>
+ <td>Frees the service implementation instance.</td>
+ </tr>
</tbody>
</table>
<br>
-<pre>int AXIS2_CALL
-math_free (axis2_svc_skeleton_t *svc_skeleton, const axis2_env_t *env
-{
-    if (svc_skeleton->ops)
-Â Â Â Â {
-        AXIS2_FREE(env->allocator, svc_skeleton->ops);
-        svc_skeleton-> ops = NULL;
-Â Â Â Â }
-Â Â Â Â if(svc_skeleton)
-Â Â Â Â {
-Â Â Â Â Â Â AXIS2_FREE (env->allocator, svc_skeleton ->ops);
- svc_skeleton -> NULL;
-Â Â Â Â }
-Â Â Â Â return AXIS2_SUCCESS;
-}</pre>
-
-<p>The above code shows the free method implementation of the math sample.</p>
-<pre>axiom_node_t* AXIS2_CALL
-math_invoke(axis2_svc_skeleton_t *svc_skeleton,
-        const axis2_env_t *env,
-        axiom_node_t *node,
-        axis2_msg_ctx_t *msg_ctx)
-{
-Â Â Â Â if(node)
-Â Â Â Â {
-        if(axiom_node_get_node_type(node, env) == AXIOM_ELEMENT)
-Â Â Â Â Â Â Â Â {
-            axiom_element_t *element = NULL;
-            element = (axiom_element_t *)axiom_node_get_data_element(node, env);
-Â Â Â Â Â Â Â Â Â Â Â Â if(element)
-Â Â Â Â Â Â Â Â Â Â Â Â {
-                axis2_char_t *op_name = axiom_element_get_localname(element, env);
-Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â if(op_name)
-Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â {
-                    if(AXIS2_STRCMP(op_name, "add") == 0)
-                        return axis2_math_add(env, node);
-                    if(AXIS2_STRCMP(op_name, "sub") == 0)
-                        return axis2_math_sub(env, node);
-                    if(AXIS2_STRCMP(op_name, "mul") == 0)
-                        return axis2_math_mul(env, node);
-                    if(AXIS2_STRCMP(op_name, "div") == 0)
-                        return axis2_math_div(env, node);
-           vice ERROR: invalid operation invoked\n");
-Â Â Â Â return node;
-}</pre>
-
-<p>The above code fragment from math sample shows how the correct method to
-be invoked could be picked from the operation name that comes in the message
-context.</p>
<p>There are two more methods that a service should implement. Once a service
is deployed, the message receiver of the Axis2/C engine would need to create
a service instance at run-time for the purpose of invoking it. For this, it
-looks for a method named axis2_create_instance and calls it on the service
+looks for a method named <code>axis2_create_instance</code> and calls it on the service
shared library. The engine also looks for a function named
-axis2_remove_instance in the shared library for clean up purposes.</p>
-<pre>AXIS2_EXPORT int axis2_get_instance(struct axis2_svc_skeleton **inst,
-        const axis2_env_t *env)
-{
-    *inst = axis2_math_create(env);
-Â Â Â Â if(!(*inst))
-Â Â Â Â {
-        return AXIS2_FAILURE;
-Â Â Â Â }
+<code>axis2_remove_instance</code> in the shared library for clean up purposes.</p>
-    return AXIS2_SUCCESS;
-}
+<p>Note that service object instantiation happens once per service. When the first request
+comes to the service, a service skeleton instance would be created and initialized.
+The same object instance would be re-used by subsequent requests.
+</p>
-AXIS2_EXPORT int axis2_remove_instance(axis2_svc_skeleton_t *inst,
-        const axis2_env_t *env)
-{
-    axis2_status_t status = AXIS2_FAILURE;
-    if (inst)
-Â Â Â Â {
-        status = axis2_svc_skeleton_free(inst, env);
-Â Â Â Â }
-    return status;
-}</pre>
+<p>
+You can find an example on how to implement the service skeleton interface
+in <a href="hello/service/hello_svc.c.html">hello_svc.c</a> source file, the
+example used in the <a href="#quick_start">quick start guide</a>. More advanced samples could be found
+in the samples folder of Axis2/C distribution.
+</p>
-<p>Note that service instantiation happens per request. That means for each
-request, the create method would be called and a new axis2_svc_skeleton
-instance would be created.</p>
<a name="cli_api"></a>
<h1>4. Client API</h1>
-<p>The primary client API to be used with Axis2/C is axis2_svc_client, the
+<p>The primary client API to be used with Axis2/C is <code>axis2_svc_client</code>, the
service client API. This is meant to be an easy to use API for consuming
services. If you want to do more complex tasks, such as invoking a client
inside a module, or wrap the client API with another interface, you may need
-to use the axis2_op_client, operation client, API. However for general
-purposes, service client is sufficient.</p>
+to use <code>axis2_op_client</code>, the operation client API. For most of the
+use cases, service client API is sufficient.</p>
<p>Behavior of the service client could be fine tuned with the options
passed to service client. You can set the options by creating an
-axis2_options instance. The bare minimum that you need to set is the endpoint
+<code>axis2_options</code> instance. The bare minimum that you need to set is the endpoint
URI where the request is to be sent to. An example of this was given in the
<a href="#quick_start">quick start guide section</a>.</p>
@@ -672,7 +630,7 @@
<td>pointer to service client struct</td>
</tr>
<tr>
- <td>const axis2_env_t *env</td>
+ <td>const axutil_env_t *env</td>
<td>pointer to environment struct</td>
</tr>
<tr>
@@ -707,7 +665,7 @@
<td>pointer to service client struct</td>
</tr>
<tr>
- <td>const axis2_env_t *env</td>
+ <td>const axutil_env_t *env</td>
<td>pointer to environment struct</td>
</tr>
<tr>
@@ -749,7 +707,7 @@
<td>pointer to service client struct</td>
</tr>
<tr>
- <td>const axis2_env_t *env</td>
+ <td>const axutil_env_t *env</td>
<td>pointer to environment struct</td>
</tr>
<tr>
@@ -785,7 +743,7 @@
<td>pointer to service client struct</td>
</tr>
<tr>
- <td>const axis2_env_t *env</td>
+ <td>const axutil_env_t *env</td>
<td>pointer to environment struct</td>
</tr>
<tr>
@@ -1135,17 +1093,17 @@
axis2_modules_ops.</p>
<ol>
<li><pre><font color="#4169E1">axis2_status_t (AXIS2_CALL * init ) (axis2_module_t *module, const
- axis2_env_t *env , axis2_conf_ctx_t *conf_ctx , axis2_module_desc_t
+ axutil_env_t *env , axis2_conf_ctx_t *conf_ctx , axis2_module_desc_t
*module_desc)</font></pre>
<p>The module initialisation is done here.</p>
</li>
<li><pre><font color="#4169E1">axis2_status_t (AXIS2_CALL * shut_down ) (axis2_module_t *module, const
- axis2_env_t *env )</font></pre>
+ axutil_env_t *env )</font></pre>
<p>Handler created function are stored in a hash map. This function will
remove them from the hash map.</p>
</li>
<li><pre><font color="#4169E1">axis2_status_t (AXIS2_CALL *fill_handler_create_func_map )
- (axis2_module_t *module, const axis2_env_t *env )</font></pre>
+ (axis2_module_t *module, const axutil_env_t *env )</font></pre>
<p>This function fills the hash map of handler create functions for the
module.</p>
</li>
@@ -1157,7 +1115,7 @@
<p>The following example shows the create function of logging module.</p>
<pre><strong><font color="#4169E1"><a name="axis2_mod_log_create"></a>axis2_module_t *
-axis2_mod_log_create(const axis2_env_t *env)</font></strong>
+axis2_mod_log_create(const axutil_env_t *env)</font></strong>
{
axis2_module_t *module = NULL;
module = AXIS2_MALLOC(env->allocator,
@@ -1180,9 +1138,9 @@
<pre><strong><font color="#4169E1"><a name="axis2_mod_log_fill_handler_create_func_map"></a>
axis2_status_t AXIS2_CALL
axis2_mod_log_fill_handler_create_func_map(axis2_module_t *module,
- const axis2_env_t *env)</font></strong>
+ const axutil_env_t *env)</font></strong>
{
- AXIS2_ENV_CHECK(env, AXIS2_FAILURE);
+ axutil_env_CHECK(env, AXIS2_FAILURE);
module->handler_create_func_map = axis2_hash_make(env);
<font color="#4169E1">if</font>(!module->handler_create_func_map)
@@ -1219,11 +1177,11 @@
<p>The following example shows the creation of the in handler in the logging
module.</p>
<pre>AXIS2_EXTERN axis2_handler_t* AXIS2_CALL
-axis2_log_in_handler_create(const axis2_env_t *env,
+axis2_log_in_handler_create(const axutil_env_t *env,
axis2_qname_t *qname)
{
axis2_handler_t *handler = NULL;
- AXIS2_ENV_CHECK(env, NULL);
+ axutil_env_CHECK(env, NULL);
handler = axis2_handler_create(env);
if (!handler)
{
@@ -1251,13 +1209,13 @@
function.</p>
<pre>axis2_status_t AXIS2_CALL
axis2_log_in_handler_invoke(struct axis2_handler *handler,
- const axis2_env_t *env,
+ const axutil_env_t *env,
struct axis2_msg_ctx *msg_ctx)
{
axiom_soap_envelope_t *soap_envelope = NULL;
axiom_node_t *ret_node = NULL;
- AXIS2_ENV_CHECK( env, AXIS2_FAILURE);
+ axutil_env_CHECK( env, AXIS2_FAILURE);
AXIS2_PARAM_CHECK(env->error, msg_ctx, AXIS2_FAILURE);
AXIS2_LOG_INFO(env->log, "Starting logging in handler .........");
@@ -2507,7 +2465,7 @@
<td>options pointer to options struct</td>
</tr>
<tr>
- <td>const axis2_env_t *env</td>
+ <td>const axutil_env_t *env</td>
<td>env pointer to environment struct</td>
</tr>
<tr>
@@ -2536,7 +2494,7 @@
<td>options pointer to options struct</td>
</tr>
<tr>
- <td>const axis2_env_t *env</td>
+ <td>const axutil_env_t *env</td>
<td>env pointer to environment struct</td>
</tr>
<tr>
@@ -2566,7 +2524,7 @@
<td>options pointer to options struct</td>
</tr>
<tr>
- <td>const axis2_env_t *env</td>
+ <td>const axutil_env_t *env</td>
<td>env pointer to environment struct</td>
</tr>
<tr>
@@ -2593,7 +2551,7 @@
<td>options pointer to options struct</td>
</tr>
<tr>
- <td>const axis2_env_t *env</td>
+ <td>const axutil_env_t *env</td>
<td>env pointer to environment struct</td>
</tr>
<tr>
@@ -2620,7 +2578,7 @@
<td>options pointer to options struct</td>
</tr>
<tr>
- <td>const axis2_env_t *env</td>
+ <td>const axutil_env_t *env</td>
<td>env pointer to environment struct</td>
</tr>
<tr>
@@ -2647,7 +2605,7 @@
<td>options pointer to options struct</td>
</tr>
<tr>
- <td>const axis2_env_t *env</td>
+ <td>const axutil_env_t *env</td>
<td>env pointer to environment struct</td>
</tr>
<tr>
@@ -2676,7 +2634,7 @@
<td>options pointer to options struct</td>
</tr>
<tr>
- <td>const axis2_env_t *env</td>
+ <td>const axutil_env_t *env</td>
<td>env pointer to environment struct</td>
</tr>
<tr>
@@ -2704,7 +2662,7 @@
<td>options pointer to options struct</td>
</tr>
<tr>
- <td>const axis2_env_t *env</td>
+ <td>const axutil_env_t *env</td>
<td>env pointer to environment struct</td>
</tr>
<tr>
@@ -2732,7 +2690,7 @@
<td>options pointer to options struct</td>
</tr>
<tr>
- <td>const axis2_env_t *env</td>
+ <td>const axutil_env_t *env</td>
<td>env pointer to environment struct</td>
</tr>
<tr>
@@ -2761,7 +2719,7 @@
<td>options pointer to options struct</td>
</tr>
<tr>
- <td>const axis2_env_t *env</td>
+ <td>const axutil_env_t *env</td>
<td>env pointer to environment struct</td>
</tr>
<tr>
@@ -2794,7 +2752,7 @@
<td>options pointer to options struct</td>
</tr>
<tr>
- <td>const axis2_env_t *env</td>
+ <td>const axutil_env_t *env</td>
<td>env pointer to environment struct</td>
</tr>
<tr>
@@ -2823,7 +2781,7 @@
<td>options pointer to options struct</td>
</tr>
<tr>
- <td>const axis2_env_t *env</td>
+ <td>const axutil_env_t *env</td>
<td>env pointer to environment struct</td>
</tr>
<tr>
@@ -2853,7 +2811,7 @@
<td>options pointer to options struct</td>
</tr>
<tr>
- <td>const axis2_env_t *env</td>
+ <td>const axutil_env_t *env</td>
<td>env pointer to environment struct</td>
</tr>
<tr>
@@ -2882,7 +2840,7 @@
<td>options pointer to options struct</td>
</tr>
<tr>
- <td>const axis2_env_t *env</td>
+ <td>const axutil_env_t *env</td>
<td>env pointer to environment struct</td>
</tr>
<tr>
@@ -2916,7 +2874,7 @@
<td>options pointer to options struct</td>
</tr>
<tr>
- <td>const axis2_env_t *env</td>
+ <td>const axutil_env_t *env</td>
<td>env pointer to environment struct</td>
</tr>
<tr>
@@ -2946,7 +2904,7 @@
<td>options pointer to options struct</td>
</tr>
<tr>
- <td>const axis2_env_t *env</td>
+ <td>const axutil_env_t *env</td>
<td>env pointer to environment struct</td>
</tr>
<tr>
@@ -2977,7 +2935,7 @@
<td>options pointer to options struct</td>
</tr>
<tr>
- <td>const axis2_env_t *env</td>
+ <td>const axutil_env_t *env</td>
<td>env pointer to environment struct</td>
</tr>
<tr>
@@ -3016,7 +2974,7 @@
<td>options pointer to options struct</td>
</tr>
<tr>
- <td>const axis2_env_t *env</td>
+ <td>const axutil_env_t *env</td>
<td>env pointer to environment struct</td>
</tr>
<tr>
@@ -3046,7 +3004,7 @@
<td>options pointer to options struct</td>
</tr>
<tr>
- <td>const axis2_env_t *env</td>
+ <td>const axutil_env_t *env</td>
<td>env pointer to environment struct</td>
</tr>
<tr>
@@ -3075,7 +3033,7 @@
<td>options pointer to options struct</td>
</tr>
<tr>
- <td>const axis2_env_t *env</td>
+ <td>const axutil_env_t *env</td>
<td>env pointer to environment struct</td>
</tr>
<tr>
---------------------------------------------------------------------
To unsubscribe, e-mail: axis-cvs-unsubscribe@ws.apache.org
For additional commands, e-mail: axis-cvs-help@ws.apache.org