You are viewing a plain text version of this content. The canonical link for it is here.
Posted to axis-cvs@ws.apache.org by di...@apache.org on 2006/10/27 06:29:25 UTC
svn commit: r468268 [2/6] - in /webservices/axis2/site/c: ./ docs/
docs/hello/ docs/hello/client/ docs/hello/service/ docs/hello/service/hello/
Added: webservices/axis2/site/c/docs/axis2c_manual.html
URL: http://svn.apache.org/viewvc/webservices/axis2/site/c/docs/axis2c_manual.html?view=auto&rev=468268
==============================================================================
--- webservices/axis2/site/c/docs/axis2c_manual.html (added)
+++ webservices/axis2/site/c/docs/axis2c_manual.html Thu Oct 26 21:29:24 2006
@@ -0,0 +1,1691 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html><head><title>Axis2/C - Apache Axis2/C Manual</title><style type="text/css" media="all">
+ @import url("../style/maven-base.css");
+
+ @import url("../style/maven-classic.css");</style><link rel="stylesheet" href="../style/print.css" type="text/css" media="print"></link><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"></meta></head><body class="composite"><div id="banner"><a href="http://www.apache.org/" id="organizationLogo"><img alt="Apache Software Foundation" src="http://www.apache.org/images/asf-logo.gif"></img></a><a href="http://ws.apache.org/axis2/c" id="projectLogo"><img alt="Apache Axis2 C" src="http://ws.apache.org/axis2/images/axis.jpg"></img></a><div class="clear"><hr></hr></div></div><div id="breadcrumbs"><div class="xleft">
+ Last published: 27 October 2006
+ | Doc for 0.94</div><div class="xright"></div><div class="clear"><hr></hr></div></div><div id="leftColumn"><div id="navcolumn"><div id="menuAxis2_C"><h5>Axis2/C</h5><ul><li class="none"><a href="../index.html">Home</a></li><li class="expanded"><a href="../download.cgi">Download Axis2/C</a><ul><li class="none"><a href="../download.cgi">Releases</a></li><li class="none"><a href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/c/" class="externalLink" title="External Link">View Source Code Online</a></li><li class="none"><a href="../svn.html">Checkout Source Code</a></li></ul></li><li class="none"><a href="../docs/index.html">Documentation</a></li><li class="expanded"><a href="../mail-lists.html">Get Involved</a><ul><li class="none"><a href="../mail-lists.html">Mailing Lists</a></li></ul></li><li class="expanded"><a href="../team-list.html">Project Information</a><ul><li class="none"><a href="../team-list.html">Project Team</a></li><li class="none"><
a href="../issue-tracking.html">Issue Tracking</a></li></ul></li></ul></div><a href="http://maven.apache.org/" title="Built by Maven" id="poweredBy"><img alt="Built by Maven" src="../images/logos/maven-button-1.png"></img></a></div></div><div id="bodyColumn"><div class="contentBox"><div class="section"><p style="margin-bottom: 0in">This document is intended to be a reference
+manual on <a href="http://ws.apache.org/axis2/c" class="externalLink" title="External Link">Apache Axis2/C</a> and
+covers its features and how to use it. Please send your feedback to Apache
+Axis2/C developer mailing list (<a href="mailto:axis-c-dev@apache.org">axis-c-dev@apache.org</a>)</p><p><a name="toc"></a></p></div><div class="section"><a name="Axis2_C_Manual"></a><h2>Axis2/C Manual</h2><ol>
+<li><a href="#quick_start">Quick Start Guide</a></li>
+<li><a href="#repo_fold">Repository Folder</a></li>
+<li><a href="#svc_api">Service API</a></li>
+<li><a href="#cli_api">Client API</a></li>
+<li><a href="#rest">REST</a></li>
+<li><a href="#mtom">MTOM</a></li>
+<li><a href="#eng_mod">Engaging a Module</a></li>
+<li><a href="#ws_add">WS-Addressing</a></li>
+<li><a href="#wrt_mod">Writing a Module</a></li>
+<li><a href="#sim_ser">Simple Axis Server</a></li>
+<li><a href="#apa_mod">Apache2 Module</a></li>
+<li><a href="#appA">Appendix A - axis2.xml</a></li>
+<li><a href="#appB">Appendix B - services.xml</a></li>
+<li><a href="#appC">Appendix C - module.xml</a></li>
+<li><a href="#appD">Appendix D - service client options</a></li>
+</ol><p><a name="quick_start"></a></p></div><div class="section"><a name="1__Quick_Start_Guide"></a><h2>1. Quick Start Guide</h2><p>This sections is aimed to help you to get a Web service up in quick time
+using Axis2/C and consume that service using an Axis2/C client.</p><p>First download the latest binary release form Apache Axis2/C <a href="http://ws.apache.org/axis2/c/download.cgi" class="externalLink" title="External Link">download page </a>. Once you
+download the correct binary that suits your platform, all that you require to
+get it running is to extract the package to a folder of your choice, set
+AXIS2C_HOME environment variable to point to this extracted folder. On Linux,
+you may have to set the LD_LIBRARY_PATH environment variable to include the
+lib folder (e.g. add $AXIS2C_HOME/lib). On Windows, you would have to add the
+lib folder to your PATH variable to include the Axis2/C dlls to your path.
+Now you should be able to cd to bin folder of this extracted folder and run
+the simple axis server in one command line and cd to bin/samples in another
+command shell and run any of the samples there (you may have to set the
+environment variables in this new shell as well). Please see the <a href="http://ws.apache.org/axis2/c/docs/installationguide.html" class="externalLink" title="External Link">installation
+guide </a> for more details.</p><p><br></br>
+<br></br>
+</p><p>Once you have Axis2/C up and running successfully, you can start writing
+your own services and clients. The following sections detail how to write
+your first service and client with Axis2/C.</p><div class="subsection"><a name="1_1_Hello_Service"></a><h3>1.1 Hello Service</h3><p>Lets see how you could write your first Web service with Axis2/C and then
+how to deploy it.</p><p>The first service that we are going to write is named "hello" and would
+have a single operation named "greet" in the service. This "greet" operation,
+when invoked by client, would expect the client to send a greeting in the
+request, and would in turn send a greeting in the response. Following are
+example XML payloads exchanged between client and service:</p><p>Request:</p>
+ <div class="source"><pre><greet>
+ Hello Service!
+<greet>
+
+</pre></div>
+ <p>Response:</p>
+ <div class="source"><pre><greetResponse>
+ Hello Client!
+<greetResponse>
+</pre></div>
+ <br></br><p>The steps to be followed when implementing a service with Axis2/C
+include:</p><ol>
+ <li><b>Implement the functions corresponding to the operations of the
+ service.</b> <br></br>
+ In our sample, we will have one function that implements the "greet"
+ operation. <br></br>
+ We would name that function "axis2_hello_greet".</li>
+ <li><b>Implement the functions defined by the axis2_svc_skeleton
+ interface</b><br></br>
+ axis2_svc_skeleton interface expects the functions free and invoke to be
+ implemented by our service.<br></br>
+ In our sample, we would implement those and name them as hello_free, and
+ hello_invoke respectively.<br></br>
+ </li>
+ <li><b>Implement the create function, that would create an instance of
+ service skeleton</b><br></br>
+ The create function would create an axis2_svc_skeleton and assign the
+ respective function pointers to map the axis2_svc_skeleton interface to
+ our interface implementation methods explained in above step<br></br>
+ </li>
+ <li><b>Implement axis2_get_instance and axis2_remove_instance
+ functions</b><br></br>
+ Those functions are used to create and destroy service instances by the
+ engine, and each service must define those functions.<br></br>
+ </li>
+ <li><b>Write the services.xml file for the service</b><br></br>
+ services.xml file acts as the deployment descriptor file for the service.
+ As the bare minimum, we need to configure the service name, operations
+ and the shared library file name containing the service implementation in
+ this file.<br></br>
+ As we have already decided, we would name the service "hello", the
+ operation "greet" and the shared library libhello.so on Linux and
+ hello.dll on Windows.<br></br>
+ </li>
+</ol></div><div class="subsection"><a name="1_1_1_Operation_Implementation"></a><h3>1.1.1 Operation Implementation</h3><p>Following is the implementation of the greet operation:</p>
+ <div class="source"><pre>axiom_node_t *
+axis2_hello_greet(const axis2_env_t *env, axiom_node_t *node)
+{
+ axiom_node_t *client_greeting_node = NULL;
+ axiom_node_t *return_node = NULL;
+
+ AXIS2_ENV_CHECK(env, NULL);
+
+ if (node)
+ {
+ client_greeting_node = AXIOM_NODE_GET_FIRST_CHILD(node, env);
+ if (client_greeting_node &&
+ AXIOM_NODE_GET_NODE_TYPE(client_greeting_node, env) == AXIOM_TEXT)
+ {
+ axiom_text_t *greeting =
+ (axiom_text_t *)AXIOM_NODE_GET_DATA_ELEMENT(client_greeting_node, env);
+ if (greeting && AXIOM_TEXT_GET_VALUE(greeting , env))
+ {
+ axis2_char_t *greeting_str = AXIOM_TEXT_GET_VALUE(greeting, env);
+ printf("Client greeted saying \"%s\" \n", greeting_str);
+ return_node = build_greeting_response(env, "Hello Client!");
+ }
+ }
+ }
+ else
+ {
+ AXIS2_ERROR_SET(env->error,
+ AXIS2_ERROR_SVC_SKEL_INVALID_XML_FORMAT_IN_REQUEST, AXIS2_FAILURE);
+ printf("ERROR: invalid XML in request\n");
+ return_node = build_greeting_response(env, "Client! Who are you?");
+ }
+
+ return return_node;
+}
+</pre></div>
+ <br></br><p>This function implements the business logic for the greet operation. We
+would be calling this function from our implementation of the invoke
+function. Basically this function receives the request payload as an
+axiom_node, process it to understand the request logic and prepares the
+response as an axiom_node and returns that.</p></div><div class="subsection"><a name="1_1_2_Skeleton_Create_Method"></a><h3>1.1.2 Skeleton Create Method</h3><p>Service skeleton creation could be implemented like the following:</p>
+ <div class="source"><pre>axis2_svc_skeleton_t *
+axis2_hello_create(const axis2_env_t *env)
+{
+ axis2_svc_skeleton_t *svc_skeleton = NULL;
+ svc_skeleton = AXIS2_MALLOC(env->allocator,
+ sizeof(axis2_svc_skeleton_t));
+
+ svc_skeleton->ops = AXIS2_MALLOC(
+ env->allocator, sizeof(axis2_svc_skeleton_ops_t));
+
+ svc_skeleton->func_array = NULL;
+ svc_skeleton->ops->free = hello_free;
+ svc_skeleton->ops->invoke = hello_invoke;
+
+ return svc_skeleton;
+}
+</pre></div>
+ <br></br><p>The create function creates and returns a new axis2_svc_skeleton instance.
+The most important aspect to notice about this function is the function
+pointer assignments to map the interface operations to the corresponding
+functions of our implementation.</p><br></br></div><div class="subsection"><a name="1_1_3_Invoking_Operation_Implementation"></a><h3>1.1.3 Invoking Operation Implementation</h3></div><div class="subsection"><p>The invoke method of the service skeleton is the point of entry for
+invoking the operations. Hence in our implementation of the invoke function,
+we have to define how the operations are to be called.</p>
+ <div class="source"><pre>axiom_node_t* AXIS2_CALL
+hello_invoke(axis2_svc_skeleton_t *svc_skeleton,
+ const axis2_env_t *env,
+ axiom_node_t *node,
+ axis2_msg_ctx_t *msg_ctx)
+{
+ return axis2_hello_greet(env, node);
+}
+</pre></div>
+ <br></br><p>In our implementation of the hello_invoke, we call the function
+implementing the greet operation. As we have only one operation, the task is
+simple here. If we had multiple operations, we would have to look into the
+information in message context to map to the exact operation. <br></br>
+Axis2/C engine would call the invoke method with an axiom_node, containing
+the request payload and axis2_msg_ctx instance containing the message context
+information, in addition to service skeleton and environment pointers. We
+could use the message context to extract whatever information we deem
+necessary related to the incoming message. The Axis2/C engine expects the
+invoke method to return a pointer to an axiom_node, representing the response
+payload.</p></div><div class="subsection"><a name="1_1_4_Full_Source"></a><h3>1.1.4 Full Source</h3><p>Here is the complete source code for the service : <a href="hello/service/hello.c.html">hello.c</a></p><br></br></div><div class="subsection"><a name="1_1_5_Service_Descriptor"></a><h3>1.1.5 Service Descriptor</h3><p>services.xml file contains details on the service that would be read by
+the Axis2/C deployment engine during deployment time. Following shows the
+contents for the service.xml file for hello service.</p>
+ <div class="source"><pre><service name="hello">
+ <parameter name="ServiceClass" locked="xsd:false">hello</parameter>
+ <description>
+ Quick start guide hello service sample.
+ </description>
+ <operation name="greet"/>
+</service>
+
+</pre></div>
+ <p>The service configuration shown above specifies that the name of the
+service is hello. <br></br>
+The value of the "serviceclass" , "hello" in this case, will be mapped to the
+service implementation by the deployment engine as libhello.so on Linux or
+hello.dll on windows.<br></br>
+description element contains a brief description of the service. <br></br>
+There can be one or more operation elements. For this sample, we only have
+one operation, with the name "greet"<br></br>
+</p></div><div class="subsection"><a name="1_1_6_Compiling_the_Service"></a><h3>1.1.6 Compiling the Service</h3><p>You can compile the service sample as shown below.</p><p>On Linux:</p>
+ <div class="source"><pre>gcc -shared -olibhello.so -I$AXIS2C_HOME/include -L$AXIS2C_HOME/lib -laxis2 hello.c
+
+</pre></div>
+ <p>On Windows </p><p>to compile,</p>
+ <div class="source"><pre>cl.exe /D "WIN32" /D "_WINDOWS" /D "_MBCS"/D"AXIS2_DECLARE_EXPORT"
+/D "AXIS2_SVR_MULTI_THREADED" /w /nologo $(AXIS2_INCLUDE_PATH)
+$(APACHE_INCLUDE_PATH) /I hello.c
+
+</pre></div>
+ </div><div class="subsection"><a name="1_1_7_Deploying_the_Service"></a><h3>1.1.7 Deploying the Service</h3><p>In order to make the service available to be consumed by clients, we have
+to deploy the service. To deploy the service, you have to create a folder in
+AXIS2C_HOME/services folder named hello and copy the services.xml file and
+the shared library file (libhello.so on Linux or hello.dll on Windows) into
+that folder</p><p>To verify that your service has been correctly deployed, you can start the
+simple axis server and then browse the list of deployed services using a Web
+browser. To start the simple axis server you can go to AXIS2C_HOME/bin folder
+and run the executable axis2_http_server. The default url that you can test
+the service list with is <a href="http://localhost:9090/axis2/services" class="externalLink" title="External Link">http://localhost:9090/axis2/services</a>.
+You should get an entry for the hello service on the page that you get.</p><p><br></br>
+<br></br>
+</p></div><div class="subsection"><a name="1_2_Hello_Client"></a><h3>1.2 Hello Client</h3><p>Now that you know how to write a service with Axis2/C, lets see how you
+could write a client to consume that service. The request payload that the
+client would be sending to the service was described in the previous section.
+The client has to prepare the payload, send it to the service and then
+receive and process the response.</p><p>The steps to be followed when implementing a client with Axis2/C
+include:</p><ol>
+ <li><b>Create the environment to be used by the client.</b> <br></br>
+ Each function in Axis2/C takes a pointer to the environment instance that
+ encapsulates memory allocators, error handler, logging and threading
+ mechanisms. axis2_env_create_all method can be used to create a default,
+ ready to use environment instance.<br></br>
+ </li>
+ <li><b>Create an options instance, and set options</b><br></br>
+ axis2_options struct can be used to set the client side options. As an
+ example, we can use options to set the endpoint address of the service to
+ be consumed by the client.</li>
+ <li><b>Create a service client instance, giving the client repository
+ folder as a parameter.</b><br></br>
+ axis2_svc_client struct is meant to be used by users for consuming
+ services. It provides an easy to use API. Service client create method
+ takes the location of the repository as a parameter. For the purpose of
+ our sample, you can use the AXIS2C_HOME as the repository. The concept of
+ repository would be explained in detail in a later section.<br></br>
+ </li>
+ <li><b>Set options to service client instance</b><br></br>
+ The options created in earlier step needs to be set on the service
+ client, indicating that options are meant to be used by the service
+ client.<br></br>
+ </li>
+ <li><b>Send the request and receive the response</b><br></br>
+ Service client's AXIS2_SVC_CLIENT_SEND_RECEIVE macro could be used to
+ invoke the send receive operation on the service client instance.<br></br>
+ The send receive operation takes the request payload as an axiom_node and
+ returns the response payload as an axiom_node.</li>
+ <li><b>Process the response</b><br></br>
+ Process the response in line with the client business logic.</li>
+</ol></div><div class="subsection"><a name="1_2_1_Creating_and_Setting_Options"></a><h3>1.2.1 Creating and Setting Options</h3>
+ <div class="source"><pre> options = axis2_options_create(env);
+ address = "http://localhost:9090/axis2/services/hello";
+ endpoint_ref = axis2_endpoint_ref_create(env, address);
+ AXIS2_OPTIONS_SET_TO(options, env, endpoint_ref);
+
+</pre></div>
+ <p>In the above shown section of code, an axis2_options instance is created
+first. Then an endpoint reference instance is created with the address of the
+location of the service. Finally, the created endpoint is set as the "to"
+address of the options. The "to" address indicates where the request should
+be sent to.</p><br></br></div><div class="subsection"><a name="1_2_2_Using_Service_Client"></a><h3>1.2.2 Using Service Client</h3>
+ <div class="source"><pre> svc_client = axis2_svc_client_create(env, client_home);
+ AXIS2_SVC_CLIENT_SET_OPTIONS(svc_client, env, options);
+ payload = build_om_request(env);
+ ret_node = AXIS2_SVC_CLIENT_SEND_RECEIVE(svc_client, env, payload);
+
+</pre></div>
+ <p>After creating and preparing the options, the next step is to create a
+service client instance and use it to send the request and receive the
+response. The code fragment given above shows how options could be set on top
+of service client and how to invoke the send receive operation with request
+payload. Once the response is received, the response payload would be stored
+in the ret_node, which is a pointer to an axiom_node and that could be used
+to further process the response.</p><br></br></div><div class="subsection"><a name="1_2_3_Full_Source"></a><h3>1.2.3 Full Source</h3><p>Here is the complete source code for the client : <a href="hello/client/hello.c.html">hello.c</a></p><br></br></div><div class="subsection"><a name="1_2_4_Compiling_the_Client"></a><h3>1.2.4 Compiling the Client</h3><p>You can compile the client sample as shown below.</p><p>On Linux:</p>
+ <div class="source"><pre>gcc -o hello -I$AXIS2C_HOME/include -L$AXIS2C_HOME/lib -laxis2 hello.c
+
+</pre></div>
+ <p>On Windows</p><p>to compile,</p>
+ <div class="source"><pre>cl.exe /nologo /D "WIN32" /D "_WINDOWS" /D "_MBCS" $(AXIS2_INCLUDE_PATH) hello.c /c
+
+</pre></div>
+ <p>to link,</p>
+ <div class="source"><pre>link.exe /nologo /LIBPATH:$(AXIS2_LIBS)
+/LIBPATH:$(LIBXML2_INSTALL_DIR)\lib
+/LIBPATH:$(APACHE_INSTALL_DIR)\lib
+/LIBPATH:$(ZLIB_INSTALL_DIR)\lib *.obj $(AXIS2_UTIL).lib $(AXIOM).lib
+$(AXIS2_PARSER).lib $(LIBS) $(AXIS2_ENGINE).lib /OUT:hello.exe
+
+</pre></div>
+ </div><div class="subsection"><a name="1_2_5_Running_the_Client"></a><h3>1.2.5 Running the Client</h3><p>To run the client, make sure you have started the simple axis server and
+run the hello executable.</p><p style="margin-bottom: 0in"><br></br>
+</p><p><a name="repo_fold"></a></p></div></div><div class="section"><a name="2__Repository_Folder"></a><h2>2. Repository Folder</h2><p>Repository is a folder where all Axis2/C related configuration as well as
+services and modules are located. The following shows the folder structure of
+the repository:</p><img src="images/axis2c_repo.gif" alt=""></img><p>Here the name of the repository folder is axis2c_repo. On your system, you
+can choose this to be any folder name of your choice. There are three sub
+folders possible in the repository. In addition to that, the axis2.xml
+configuration file is also located in the repository. Following table
+describes the purpose of repository contents.</p><table class="bodyTable"><caption>Axis2/C Repository Subfolders</caption><tbody>
+ <tr class="b"><th>Folder Name</th><th>Description</th></tr>
+ <tr class="a"><td><p>lib</p>
+ </td><td><p>lib folder contains the libraries required to run Axis2/C
+ engine. While you can afford to have the shared libs of Axis2/C in a
+ location of your choice, the dynamically loaded shared libs, parser,
+ transport receiver and transport sender has to be there in the
+ repository lib folder. <br></br>
+ It is mandatory that the lib folder is there in the repository.</p>
+ </td></tr>
+ <tr class="b"><td><p>modules</p>
+ </td><td><p>modules folder contains the modules deployed with Axis2/C. Each
+ module deployed would have its own sub folder inside modules folder.
+ As an example, if addressing module is deployed, then there would be
+ a sub folder named addressing inside the modules folder of the
+ repository.<br></br>
+ In deployment time, Axis2/C deployment engine would traverse this
+ modules folders to find out what modules are available.<br></br>
+ modules folder is optional. If it is empty or non-existent, that
+ means that there are no deployed modules.</p>
+ </td></tr>
+ <tr class="a"><td><p>services</p>
+ </td><td><p>services folder contains the services deployed with Axis2/C.
+ Each service deployed would have its own sub folder inside services
+ folder, or would live inside one of the sub folders.<br></br>
+ In deployment time, Axis2/C deployment engine would traverse this
+ services folders to find out what services are available.<br></br>
+ services folder is optional. If it is empty or non-existent, that
+ means that there are no deployed services.</p>
+ </td></tr>
+ <tr class="b"><td><p>axis2.xml</p>
+ </td><td><p>axis2.xml file is the configuration file of Axis2/C.<br></br>
+ The configuration file is mandatory and must have the name axis2.xml.
+ It is safe to consider your Axis2/C repository to be the folder where
+ you have the axis2.xml file.</p>
+ </td></tr>
+ </tbody></table><p>Both clients as well as services written using Axis2/C could use the same
+repository. However one can use one repository for the server side and
+another one for the client side. The services folder makes sense, only when
+the repository is used by the server side. When the repository is used by the
+client, services folder, if present, would not be useful.</p><p>The Axis2/C binary distribution, when extracted, could be considered ready
+to be used as your repository folder. If you are building Axis2/C from source
+distribution, when you build the source, including the samples, the
+installation destination would be ready to be used as your repository
+folder.</p><p>The simple axis server (that is axis2_http_server binary), the client
+samples as well as the httpd module (Axis2 Apache2 module) requires the
+repository folder to be specified in order to run correctly.</p><p></p><div class="subsection"><a name="2_1_Module_Folders"></a><h3>2.1 Module Folders</h3><p>As described earlier, all modules are placed inside modules folder of the
+repository and each module would have its own sub folder within modules
+folder.<br></br>
+The folder in which a module is placed must have the same name as the module
+name. As an example, the addressing module would be placed in a sub folder
+named addressing.<br></br>
+</p><p>Inside the folder corresponding to a module, the shared library
+implementing the module and the module configuration file, module.xml, would
+be placed. It is a must that inside each folder representing a module that
+these two files are present. module.xml file would be processed by the
+deployment engine to find out module specific information such as module
+name, set of handlers and the flows into which those handlers are to be added
+etc.</p></div><div class="subsection"><a name="2_1_Service_Folders"></a><h3>2.1 Service Folders</h3><p>All services are placed inside services folder of the repository and each
+service would be in one of the sub folders within services folder. Axis2/C
+has a concept called service groups, where there could be one or more
+services inside a service group. A single stand alone service would be
+assigned a service group with the same name as that of the service by the
+Axis2/C engine for the purpose of easy handling. For this reason, sub folders
+in services folder correspond to service groups.</p><p>A service, if deployed as a stand alone service, would live inside a
+folder with the same name as that of the service. As an example, the echo
+service would be placed in a sub folder named echo. Inside the folder
+corresponding to a service, the shared library implementing the service and
+the service configuration file, services.xml, would be placed. It is because
+of the fact that the engine treats the folders to represent service groups
+and not a single service, the configuration file is called services.xml.
+However, it is alway possible to place a single service inside a single
+folder, as that is the most common use case.</p><p>Each sub folder within the services folder should have at least one shared
+lib implementing a service and a services.xml file. If it is a real service
+group, there could be multiple shared libs, yet only one services.xml file
+configuring all those services. services.xml file would be processed by the
+deployment engine to find out service group and service specific information
+such as service group name, service name, set of operations for each service
+etc.</p><p><a name="svc_api"></a></p></div></div><div class="section"><a name="3__Service_API"></a><h2>3. Service API</h2><p>We have already seen how to write a service in quick start guide section
+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
+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
+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><table class="bodyTable"><caption></caption><tbody>
+ <tr class="a"><th>Function Signature</th><th>Description</th></tr>
+ <tr class="b"><td><pre>int (AXIS2_CALL *
+ free )( axis2_svc_skeleton_t *svc_skeli,
+ const axis2_env_t *env);</pre>
+ </td><td>Frees the service implementation instance.</td></tr>
+ <tr class="a"><td><pre>axiom_node_t *(AXIS2_CALL*
+ invoke )( axis2_svc_skeleton_t *svc_skeli,
+ const axis2_env_t *env,
+ axiom_node_t *node,
+ axis2_msg_ctx_t *msg_ctx);</pre>
+ </td><td>Invokes the service implementation. You have to implement the logic
+ to call the correct functions in this method based on the name of the
+ operation being invoked.</td></tr>
+ </tbody></table><br></br>
+ <div class="source"><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></div>
+ <p>The above code shows the free method implementation of the math sample.</p>
+ <div class="source"><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)
+{
+ (node)
+ {
+ (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);
+ (element)
+ {
+ axis2_char_t *op_name = AXIOM_ELEMENT_GET_LOCALNAME(element, env);
+ (op_name)
+ {
+ (AXIS2_STRCMP(op_name, "add") == 0)
+ axis2_math_add(env, node);
+ (AXIS2_STRCMP(op_name, "sub") == 0)
+ axis2_math_sub(env, node);
+ (AXIS2_STRCMP(op_name, "mul") == 0)
+ axis2_math_mul(env, node);
+ (AXIS2_STRCMP(op_name, "div") == 0)
+ axis2_math_div(env, node);
+ }
+ }
+ }
+ }
+ printf("Math service ERROR: invalid operation invoked\n");
+ node;
+}
+
+</pre></div>
+ <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 runtime for the purpose of invoking it. For this, it
+looks for a method named axis2_create_instance and calls it on the service
+shared library. The engine also looks to a function named
+axis2_remove_instance for clean up purposes in the shared library.</p>
+ <div class="source"><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;
+ }
+
+ return AXIS2_SUCCESS;
+}
+
+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></div>
+ <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><p><a name="cli_api"></a></p></div><div class="section"><a name="4__Client_API"></a><h2>4. Client API</h2><p>The primary client API to be used with Axis2/C is axis2_svc_client, 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><p>Behaviour of the service client could be fine tuned with the options
+passed to service client. You can set the options by creating axis2_options
+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 quick start
+guide section.</p><p>The service client interface serves as the primary client interface for
+consuming services. You can set the options to be used by the service client
+and then invoke an operation on a given service. There are several ways of
+invoking a service operation. The way of invoking an operation depends on 3
+things. Those are,</p><ol>
+ <li>The Message Exchange Pattern (MEP)</li>
+ <li>Synchronous/Asynchronous behaviour (Blocking/Non-Blocking)</li>
+ <li>Two-way or one-way transport</li>
+</ol><p>Many ways of service operation invoking scenarios can be obtained by
+combining these 3 factors. Service client interface provides the necessary
+parameters for above 3 tasks.</p><p></p><p>Deciding the Message Exchange Pattern (MEP)</p><p>There are 2 message exchange patterns.</p><ol>
+ <li>out_only</li>
+ <li>in_out</li>
+</ol><p>In out_only MEP the client doesn't expect a reply from the server. Service
+client provides 2 methods for executing out_only operations.</p><p></p><div class="subsection"><a name="axis2_svc_client_fire_and_forget"></a><h3>axis2_svc_client_fire_and_forget</h3><p>Sends a message and forget about it. This method is used to interact with
+a service operation whose MEP is In-Only. That is, there is no opportunity to
+get an error from the service via this method; one may still get client-side
+errors, such as host unknown etc.</p><table class="bodyTable"><caption></caption><tbody>
+ <tr class="b"><th>Parameter</th><th>Description</th></tr>
+ <tr class="a"><td>axis2_svc_client_t *svc_client</td><td>svc_client pointer to service client struct</td></tr>
+ <tr class="b"><td>const axis2_env_t *env</td><td>env pointer to environment struct</td></tr>
+ <tr class="a"><td>const axis2_qname_t *op_qname</td><td>qname of the service operation which is going to be execute</td></tr>
+ <tr class="b"><td>const axiom_node_t *payload</td><td>payload pointer to OM node representing the XML payload to be
+ sent</td></tr>
+ </tbody></table><p>return type :- void</p><p></p></div><div class="subsection"><a name="axis2_svc_client_send_robust"></a><h3>axis2_svc_client_send_robust</h3><p>If a fault triggers on server side, this method would report an error back
+to the caller.</p><table class="bodyTable"><caption></caption><tbody>
+ <tr class="a"><th>Parameter</th><th>Description</th></tr>
+ <tr class="b"><td>axis2_svc_client_t *svc_client</td><td>svc_client pointer to service client struct</td></tr>
+ <tr class="a"><td>const axis2_env_t *env</td><td>env pointer to environment struct</td></tr>
+ <tr class="b"><td>const axis2_qname_t *op_qname</td><td>qname of the service operation which is going to be execute</td></tr>
+ <tr class="a"><td>const axiom_node_t *payload</td><td>payload pointer to OM node representing the XML payload to be
+ sent</td></tr>
+ </tbody></table><p>return type:- axis2_status_t</p><p>return AXIS2_SUCCESS on success, else AXIS2_FAILURE.</p><p></p><p>Both these methods call AXIS2_OP_CLIENT_EXECUTE inside. But
+fire_and_forget method set the blocking parameter FALSE and send_robust set
+the blocking parameter TRUE. Hence it will block for the fault trigger.</p><p></p><p>In in_out MEP, the client expect a reply from the server. The
+axis2_svc_client_send_recieve and axis2_send_receive_non_blocking supports
+this MEP pattern.</p><p></p></div><div class="subsection"><a name="axis2_svc_client_send_receive"></a><h3>axis2_svc_client_send_receive</h3><p>Sends XML request and receives XML response.</p><table class="bodyTable"><caption></caption><tbody>
+ <tr class="b"><th>Parameter</th><th>Description</th></tr>
+ <tr class="a"><td>axis2_svc_client_t *svc_client</td><td>svc_client pointer to service client struct</td></tr>
+ <tr class="b"><td>const axis2_env_t *env</td><td>env pointer to environment struct</td></tr>
+ <tr class="a"><td>const axis2_qname_t *op_qname</td><td>qname of the service operation which is going to be execute</td></tr>
+ <tr class="b"><td>const axiom_node_t *payload</td><td>payload pointer to OM node representing the XML payload to be
+ sent</td></tr>
+ </tbody></table><p>Return pointer to OM node representing the XML response. The caller owns
+the returned node. This method blocks until the response arrives.</p><p></p></div><div class="subsection"><a name="axis2_send_receive_non_blocking"></a><h3>axis2_send_receive_non_blocking</h3><p>Sends XML request and receives XML response, but does not block for
+response.</p><table class="bodyTable"><caption></caption><tbody>
+ <tr class="a"><th>Parameter</th><th>Description</th></tr>
+ <tr class="b"><td>axis2_svc_client_t *svc_client</td><td>svc_client pointer to service client struct</td></tr>
+ <tr class="a"><td>const axis2_env_t *env</td><td>env pointer to environment struct</td></tr>
+ <tr class="b"><td>const axis2_qname_t *op_qname</td><td>qname of the service operation which is going to be execute</td></tr>
+ <tr class="a"><td>const axiom_node_t *payload</td><td>payload pointer to OM node representing the XML payload to be
+ sent</td></tr>
+ <tr class="b"><td>axis2_callback_t *callback</td><td>callback pointer to callback struct used to capture response</td></tr>
+ </tbody></table><p></p><p>Return type :- void<br></br>
+This method will not block for the response. Instead it sets a call back to
+capture the response.<br></br>
+</p><p><strong>Synchronous/Asynchronous behaviour
+(Blocking/Non-Blocking)</strong></p><p>This will determine whether the client will block (Sysnchronous) or
+non-block (asynchronous) for the response in a in-out MEP scenario. This can
+be decided by using<br></br>
+<em>axis2_svc_client_send_receive</em> or
+<em>axis2_svc_client_send_receive_non_blocking</em> methods.<br></br>
+</p><p></p><p><strong>Two-way or One-way transport</strong></p><p>If the transport is Two-way transport then only one channel is used .If
+the Transport is One-way then the response will come from a seperate
+chanel.<br></br>
+If we want to set a seperate channel for the response the following
+<em>set_use_seperate_listener</em> option has to be set.</p><p>See ApendixD for further details.</p><p><a name="rest"></a></p></div></div><div class="section"><a name="5__REST"></a><h2>5. REST</h2><p>If you want to consume Web services using REST style calls you can use
+either the HTTP POST method or HTTP GET method.</p><p>The following example shows how to enable a REST style invocation using
+different HTTP methods.</p>
+ <div class="source"><pre>AXIS2_OPTIONS_SET_PROPERTY(options, env, AXIS2_ENABLE_REST,AXIS2_VALUE_TRUE);
+if (AXIS2_TRUE == method_get )
+{
+AXIS2_OPTIONS_SET_PROPERTY(options, env, AXIS2_HTTP_METHOD, AXIS2_HTTP_HEADER_GET);
+}
+
+</pre></div>
+ <p>Default value of REST is set to HTTP POST Method. If someone need to
+change it to HTTP GET method.</p>
+ <div class="source"><pre>AXIS2_OPTIONS_SET_PROPERTY(options, env, AXIS2_HTTP_METHOD, AXIS2_HTTP_HEADER_GET);
+
+</pre></div>
+ <p>can be used.</p><p><a name="mtom"></a></p></div><div class="section"><a name="6__MTOM"></a><h2>6. MTOM</h2><p>Axis2/C allows you to send and receive binary data with SOAP messages
+using MTOM/XOP conventions. When sending attachments, you have to use service
+client (svc_client) to perform the send and receive operation, and give the
+binary data as an array.</p><p>In order to send the attachment you need to build om node including that
+attachment as a node. We need to give our built om structure to service
+client to perform send and receive operations.</p><p>In the above sample payload shown, we place our image file as text within
+an image element</p>
+ <div class="source"><pre>image_om_ele = axiom_element_create(env,mtom_om_node, "image", ns1,&image_om_node);
+data_handler = axiom_data_handler_create(env, image_name, "image/jpeg");
+data_text = axiom_text_create_with_data_handler(env, image_om_node,data_handler, &data_om_node);
+
+</pre></div>
+ <p>When sending attachments, you can configure the client either to send the
+attachment in the optimised format or in non optimised format. By setting an
+option</p>
+ <div class="source"><pre>AXIS2_OPTIONS_SET_ENABLE_MTOM(options,env,AXIS2_TRUE);</pre></div>
+ <p>
+or setting</p><br></br>
+ <div class="source"><pre><enableMtom>true</enableMtom></pre></div>
+ <p>
+in axis2.xml
+
+</p><p>If the attachment is sent in binary optimised format, the file content
+would be sent as it is, out of the SOAP body, using MIME headers and the
+payload would have an XOP:Include element, referring to the MIME part that
+contains the binary attachment. In case of binary non optimised format, the
+attachment content would be sent in the payload itself, as a base64 encoded
+string.</p><p><a name="eng_mod"></a></p></div><div class="section"><a name="7__Engaging_a_Module"></a><h2>7. Engaging a Module</h2><p>Modules have the concept of being available and engaged. Available means
+modules are deployed in the system but not activated. They will be activated
+only after being engaged. Normally a module is a set of handlers. Every
+module should come with its own module.xml file . This module.xml file
+specifies the module specific handlers and to what phases they are to be
+deployed in the axis2 handler chain. Some of the module specific handlers may
+be put in to system predefined phases.In that case, module.xml file should
+specify where to put the handlers relative to the others in that phase. Some
+times module may define its own phase. In that case some of the module specie
+handlers may be put in to that phase. The handlers which are added to the
+system predefined phases (global handlers) are invoked for every message
+which comes in/out to the system. The handlers in the module specific phase
+are invoked only for the messages aiming at the operations which engaged that
+module. Engaging a module means correctly adding the handlers of a particular
+module to a phase. A service, operations or the system may engage a module.
+Once the module is engaged the handlers and the operations defined in the
+module are added to the entity that engaged them.</p><p></p><p>Before engaging a module following steps has to be followed.</p><ol>
+ <li>Writing the module.xml file</li>
+ <li>Packaging the module libraries and the module.xml in to a folder which
+ has the name of the module.</li>
+ <li>Deploy the folder in AXIS2C_INSTALL_DIR/modules</li>
+ <li>Adding the module specific phases in the axis2.xml file.</li>
+</ol><p>The following is an example of engaging a sample module called logging
+module to the axis2c system.</p><p></p><div class="subsection"><a name="Writing_the_module_xml_file"></a><h3>Writing the module.xml file</h3><p>In the module.xml file, the handlers of the module and the phases to which
+they are to be added has to be specified. Below is the module.xml file of the
+sample logging module.</p><table class="bodyTable"><caption></caption><tbody>
+ <tr class="a"><td><module name="logging" class="axis2_mod_log">
+
+ <p><inflow></p>
+
+ <p><handler name="LoggingInHandler" class="axis2_mod_log"></p>
+
+ <p><order phase="PreDispatch"/></p>
+
+ <p></handler></p>
+
+ <p></inflow></p>
+
+ <p></p>
+
+ <p><outflow></p>
+
+ <p><handler name="LoggingOutHandler" class="axis2_mod_log"></p>
+
+ <p><order phase="MessageOut"/></p>
+
+ <p></handler></p>
+
+ <p></outflow></p>
+
+ <p></p>
+
+ <p><Outfaultflow></p>
+
+ <p><handler name="LoggingOutHandler" class="axis2_mod_log"></p>
+
+ <p><order phase="MessageOut"/></p>
+
+ <p></handler></p>
+
+ <p></Outfaultflow></p>
+
+ <p></module></p>
+
+ <p></p>
+ </td></tr>
+ </tbody></table><p></p></div><div class="subsection"><a name="Adding_the_module_specific_phases_in_the_axis2_xml_file"></a><h3>Adding the module specific phases in the axis2.xml file</h3><p>The module specific phase has to de added after the system predefined
+phases. The following example shows where to add the module specific
+phases.</p><table class="bodyTable"><caption></caption><tbody>
+ <tr class="b"><td><phaseOrder type="inflow">
+
+ <p><!-- System pre defined phases --></p>
+
+ <p><phase name="TransportIn"/></p>
+
+ <p><phase name="PreDispatch"/></p>
+
+ <p><phase name="Dispatch"
+ class="org.apache.axis2.engine.DispatchPhase"></p>
+
+ <p><handler name="AddressingBasedDispatcher"</p>
+
+ <p>class="axis2_engine"></p>
+
+ <p><order phase="Dispatch"/></p>
+
+ <p></handler></p>
+
+ <p></p>
+
+ <p><handler name="RequestURIBasedDispatcher"</p>
+
+ <p>class="axis2_engine"></p>
+
+ <p><order phase="Dispatch"/></p>
+
+ <p></handler></p>
+
+ <p></p>
+
+ <p><handler name="SOAPActionBasedDispatcher"</p>
+
+ <p>class="axis2_engine"></p>
+
+ <p><order phase="Dispatch"/></p>
+
+ <p></handler></p>
+
+ <p></p>
+
+ <p><handler name="SOAPMessageBodyBasedDispatcher"</p>
+
+ <p>class="axis2_engine"></p>
+
+ <p><order phase="Dispatch"/></p>
+
+ <p></handler></p>
+
+ <p><handler name="InstanceDispatcher"</p>
+
+ <p>class="org.apache.axis2.engine.InstanceDispatcher"></p>
+
+ <p><order phase="PostDispatch"/></p>
+
+ <p></handler></p>
+
+ <p></phase></p>
+
+ <p><!-- System pre defined phases --></p>
+
+ <p><span style="color: #0000FF"><!-- After Postdispatch phase
+ module author or or service author can add any phase he want
+ --></span></p>
+
+ <p><phase name="OperationInPhase"/></p>
+
+ <p><phase name=""/></p>
+
+ <p></phaseOrder></p>
+
+ <p><phaseOrder type="outflow"></p>
+
+ <p><span style="color: #0000FF"><!-- user can add his own phases
+ to this area --></span></p>
+
+ <p><phase name="OperationOutPhase"/></p>
+
+ <p><phase name=""/></p>
+
+ <p><!--system predefined phase--></p>
+
+ <p><!--these phase will run irrespective of the service--></p>
+
+ <p><phase name="MessageOut"/></p>
+
+ <p></phaseOrder/></p>
+
+ <p><phaseOrder type="INfaultflow"></p>
+
+ <p><span style="color: #0000FF"><!-- user can add his own phases
+ to this area --></span></p>
+
+ <p><phase name="OperationInFaultPhase"/></p>
+
+ <p><phase name=""/></p>
+
+ <p></phaseOrder></p>
+
+ <p><phaseOrder type="Outfaultflow"></p>
+
+ <p><span style="color: #0000FF"><!-- user can add his own phases
+ to this area --></span></p>
+
+ <p><phase name="OperationOutFaultPhase"/></p>
+
+ <p><phase name=""/></p>
+
+ <p><phase name="PolicyDetermination"/></p>
+
+ <p><phase name="MessageOut"/></p>
+
+ <p></phaseOrder></p>
+ </td></tr>
+ </tbody></table><p>As mentioned in the above example, the user or module author can handle
+his own phases after system predefined phases.In the above example there are
+no specific phases for the logging module. That is all the module specific
+handlers are added to the system predefined phases as mentioned in the
+module.xml file.</p><p></p></div><div class="subsection"><a name="Engaging_the_module_for_services"></a><h3>Engaging the module for services</h3><p>Following is an example of engaging the logging module to the echo
+service.This can be done by simply adding <module ref ="logging"/> in
+the service.xml file. This informs the Axis2 engine that the module "logging"
+should be engaged for this service. The handler inside the module will be
+executed in their respective phases as described by the "module.xml".</p><table class="bodyTable"><tbody>
+ <tr class="a"><td><service name="echo">
+
+ <p><span style="color: #0000FF"><module ref
+ ="logging"/></span></p>
+
+ <p><parameter name="ServiceClass"
+ locked="xsd:false">echo</parameter></p>
+
+ <p><description></p>
+
+ <p>This is a testing service , to test the system is working or
+ not</p>
+
+ <p></description></p>
+
+ <p><operation name="echoString"></p>
+
+ <p><!--messageReceiver class="axis2_receivers" /--></p>
+
+ <p><parameter name="wsamapping"
+ >http://ws.apache.org/axis2/c/samples/echoString</parameter></p>
+
+ <p></operation></p>
+
+ <p></service></p>
+
+ <p></p>
+ </td></tr>
+ </tbody></table></div><div class="subsection"><a name="Engaging_the_module_globally"></a><h3>Engaging the module globally</h3><p>If we want to engage the module for every service deployed in the axis2c
+system, we can add the above entry in the axis2.xml file. This will inform
+the Axis2/C system to invoke the handler inside the module specific phases
+for every message coming to any service deployed within the system.</p><p></p></div><div class="subsection"><a name="Engaging_the_module_at_the_client_side"></a><h3>Engaging the module at the client side</h3><p>In the client side if the above <module ref ="logging"/> is added in
+the axis2.xml the module specific handlers will invoke for every request the
+client sends.If only a particular client wants to engage the module it can be
+done by engaging the module programmatically. This can be done by adding the
+following line in the client code after setting the options.</p><p>AXIS2_SVC_CLIENT_SET_OPTIONS(svc_client, env, options);</p><p><em>AXIS2_SVC_CLIENT_ENGAGE_MODULE(svc_client, env, "module
+name");</em></p><p></p><p>So it is very easy engaging modules in Axis2/c and it also gives a higher
+flexibility.</p><p><a name="ws_add"></a></p></div></div><div class="section"><a name="8__WS-Addressing"></a><h2>8. WS-Addressing</h2><p><a href="http://www.w3.org/2002/ws/addr/" class="externalLink" title="External Link">WS-Addressing</a> provides
+mechanisms to address Web services and messages. With Axis2/C, you can use
+both WS-Addressing <a href="http://www.w3.org/TR/ws-addr-core/" class="externalLink" title="External Link">version
+1.0</a> as well as the <a href="http://www.w3.org/Submission/ws-addressing/" class="externalLink" title="External Link">submission version</a>.</p><p>WS-Addressing can be enabled in the client side using 2 different methods
+in Axis2/C.</p><ul>
+ <li>Engaging Addressing module globally in the axis2.xml file
+ <p>Adding <span style="color: #0000FF"><module
+ ref="addressing"/></span> in the client side axis2.xml file will add
+ addressing capability to every message the Axis2/C clients send.</p>
+ </li>
+ <li>If we need to add addressing for a specific client , we should do it
+ programmetically by adding the following function call in the client
+ implementation file.
+ <pre>AXIS2_SVC_CLIENT_ENGAGE_MODULE(svc_client, env,AXIS2_MODULE_ADDRESSING);</pre>
+ </li>
+</ul><p>There are two basic requirements for using WS-Addressing on client side
+with Axis2/C. One is that you have to provide a WS-Addressing action at
+message level. The other is that you have to enable the use of WS-Addressing
+at client level.</p>
+ <div class="source"><pre> address = "http://localh ost:9090/axis2/services/echo";
+ endpoint_ref = axis2_endpoint_ref_create(env, address);
+ /* Setup options */
+ options = axis2_options_create(env);
+ AXIS2_OPTIONS_SET_TO(options, env, endpoint_ref);
+
+</pre></div>
+ <p>In the above code segment the message destination endpoint(wsa:To) is set
+using the AXIS2_OPTIONS_SET_TO(options, env, endpoint_ref) macro.
+endpoint_ref is created using the address string. Another important parameter
+in addressing is the wsa:action parameter. This is set from the function
+shown below.</p>
+ <div class="source"><pre>AXIS2_OPTIONS_SET_ACTION(options,env,"http://ws.apache.org/axis2/c/samples/echoString")
+
+</pre></div>
+ <p>In addition to the action and to there are other WS-Addressing related
+SOAP headers that could be sent in a message. Axis2/C has support to set
+those headers as options at client level. The following functions are used to
+set them.</p>
+ <div class="source"><pre>AXIS2_OPTIONS_SET_REPLY_TO(options, env, reply_to)
+
+</pre></div>
+ <p>Sets the wsa:Replyto header. The "ReplyTo" header contains the endpoint to
+send reply messages The Replyto header is required when the response comes in
+a seperate channel. (when using dual chanel)</p>
+ <div class="source"><pre>AXIS2_OPTIONS_SET_FAULT_TO(options, env, fault_to)
+
+</pre></div>
+ <p>Sets the wsa:FaultTo header.This contains the endpoint to direct fault
+messages. If "FaultTo" is absent one may use "ReplyTo" endpoint instead.</p>
+ <div class="source"><pre>AXIS2_OPTIONS_SET_FROM(options, env, from)
+
+</pre></div>
+ <p>Some times receiving endpoint requires to know the original sender of the
+message.wsa:From header is used in those cases.The above function sets the
+wsa:From header.</p>
+ <div class="source"><pre>AXIS2_OPTIONS_SET_RELATES_TO(options, env, relates_to)
+
+</pre></div>
+ <p>sets the wsa:RelatesTo header.This header contains a uri value that must
+be the message ID of a previously exchanged message.It defines the current
+message relationship to the message being identified.</p><p><a name="wrt_mod"></a></p></div><div class="section"><a name="9__Writing_a_Module"></a><h2>9. Writing a Module</h2><p>A module is an extension point in the Axis2/C engine. Modules are used to
+improve the quality of service in the Axis2/C engine.A SOAP message may
+contain any number of header blocks. These header blocks provide various
+processing information. In Axis2/C, these various header blocks are processed
+by modules. Some times modules may add header blocks to a SOAP message.</p><p>Normally a module is a collection of handlers. So writing a module mainly
+consists of writing handlers. Axis2/C provides two basic interfaces for
+writing a module. They are axis2_module and axis2_handler.</p><p></p><p>Every module should have 3 basic functions as defined in the
+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
+ *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>
+ <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>
+ <p>This function fills the hash map of handler create functions for the
+ module.</p>
+ </li>
+</ol><p>The module developer implements these functions in its implementation
+file. When creating a module, the base struct functions will be assigned
+these implemented functions.</p><p>The following example shows the creation of logging module.</p>
+ <div class="source"><pre>
+{
+ axis2_module_t *module = NULL;
+ module = AXIS2_MALLOC(env->allocator,
+ (axis2_module_t));
+
+
+ module->ops = AXIS2_MALLOC(
+ env->allocator, (axis2_module_ops_t));
+
+ module->ops->shutdown = axis2_mod_log_shutdown;
+ module->ops->init = axis2_mod_log_init;
+ module->ops->fill_handler_create_func_map =
+ axis2_mod_log_fill_handler_create_func_map;
+
+ module;
+}
+
+</pre></div>
+ <p>The following code segmement shows the adding of handler create functions
+to the module hash map.</p>
+ <div class="source"><pre>
+{
+ AXIS2_ENV_CHECK(env, AXIS2_FAILURE);
+
+ module->handler_create_func_map = axis2_hash_make(env);
+ (!module->handler_create_func_map)
+ {
+ AXIS2_ERROR_SET(env->error, AXIS2_ERROR_NO_MEMORY,
+ AXIS2_FAILURE);
+ AXIS2_FAILURE;
+ }
+ axis2_hash_set(module->handler_create_func_map, ,
+ AXIS2_HASH_KEY_STRING, axis2_log_in_handler_create);
+
+
+ axis2_hash_set(module->handler_create_func_map, ,
+ AXIS2_HASH_KEY_STRING, axis2_log_out_handler_create);
+
+ AXIS2_SUCCESS;
+
+</pre></div>
+ <p>In the above example the "logging" module adds two handlers. So these
+handler creation functions are added to the hash map.</p><p></p><div class="subsection"><a name="Writing_handlers"></a><h3>Writing handlers</h3><p>Handler is the smallest unit of execution in the Axis2/C engine's
+execution flow. The engine could have two flows, the in-flow and the
+out-flow. A flow is a collection of phases and a phase in turn is a
+collection of handlers. A handler is invoked when the phase within which it
+lives is invoked. Axis2/C defines an interface called axis2_handler , which
+is used to create handlers.</p><p>The following example shows the creation of the in handler in the logging
+module.</p>
+ <div class="source"><pre>AXIS2_EXTERN axis2_handler_t* AXIS2_CALL
+axis2_log_in_handler_create(const axis2_env_t *env,
+ axis2_qname_t *qname)
+{
+ axis2_handler_t *handler = NULL;
+ AXIS2_ENV_CHECK(env, NULL);
+ handler = axis2_handler_create(env);
+ if (!handler)
+ {
+ return NULL;
+ }
+
+ /* handler init is handled by conf loading, so no need to do it here */
+
+/* set the base struct's invoke op */
+
+ if (handler->ops)
+ handler->ops->invoke = axis2_log_in_handler_invoke;
+
+ return handler;
+}
+
+</pre></div>
+ <p>In the above example the axis2_log_in_handler_invoke function is assigned
+to axis2_handler invoke function pointer. Invoke is called to do the actual
+work assigned to the handler. The phase that owns the handler is responsible
+for calling invoke of the handler. Those structs that implement the interface
+of the handler should implement the logic for invoke and assign the
+respective function pointer to invoke operation of the ops struct.</p><p>The following code segment shows the "logging" module in handler invoke
+function.</p>
+ <div class="source"><pre>axis2_status_t AXIS2_CALL
+axis2_log_in_handler_invoke(struct axis2_handler *handler,
+ const axis2_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);
+ AXIS2_PARAM_CHECK(env->error, msg_ctx, AXIS2_FAILURE);
+
+ AXIS2_LOG_INFO(env->log, "Starting logging in handler .........");
+ printf("\n\nStarting logging in handler .........\n\n");
+
+ soap_envelope = AXIS2_MSG_CTX_GET_SOAP_ENVELOPE(msg_ctx, env);
+
+ if(soap_envelope)
+ {
+ AXIOM_SOAP_ENVELOPE_GET_BODY(soap_envelope, env);
+
+ ret_node = AXIOM_SOAP_ENVELOPE_GET_BASE_NODE(soap_envelope, env);
+
+ if(ret_node)
+ {
+ axis2_char_t *om_str = NULL;
+ om_str = AXIOM_NODE_TO_STRING(ret_node, env);
+ if (om_str)
+ {
+ AXIS2_LOG_INFO(env->log, "Input msg: %s", om_str);
+ printf("Input msg: %s", om_str);
+ }
+ }
+ }
+
+ return AXIS2_SUCCESS;
+}
+
+</pre></div>
+ </div><div class="subsection"><a name="Writing_the_module_xml_file"></a><h3>Writing the module.xml file</h3><p>After writing the module, the module.xml file should be written. The
+module.xml file contains all the configuration details for a particular
+module.See Enging a module part for more details. Some of the important
+details in the module.xml file can be summerized as follows.</p><ul>
+ <li>The names of the module specific handlers and the phases they are to be
+ added in Axis2/C flows.</li>
+ <li>The relative places of handlers with respect to the other handlers in a
+ given phase.</li>
+ <li>The operations the module is adding to the engaged services.</li>
+ <li>The module specific message receivers.</li>
+</ul><p>The handlers defined in a module can be added to Axis2/C system global
+phases or the module specific phases.</p><p><a name="sim_ser"></a></p></div></div><div class="section"><a name="11__Simple_Axis_Server"></a><h2>11. Simple Axis Server</h2><p>simple axis server is the inbuilt server of the Axis2/C.<br></br>
+</p>
+ <div class="source"><pre>./axis2_http_server [-p PORT] [-t TIMEOUT] [-r REPO_PATH][-l LOG_LEVEL] [-f LOG_FILE]
+</pre></div>
+ <br></br><p>
+There are some options that we could give to the server. One can start simple
+axis server without any options.
+
+ <div class="source"><pre>$./axis2_http_server </pre></div>
+
+Then it takes
+</p><p> port -> 9090<br></br>
+ repo path -> ../<br></br>
+ time_out -> AXIS2_HTTP_DEFAULT_SO_TIMEOUT (30000 s)<br></br>
+ log_level -> AXIS2_LOG_LEVEL_DEBUG<br></br>
+ log_file -> axis2.log</p><br></br><p>
+as default values.
+
+ <div class="source"><pre>[-p PORT]
+This option specifies the port that server should start.
+Once started the server listen for requests that will come to this port.
+
+[-t TIMEOUT]
+Timeout gives time period that the server should listen without any
+requests. After that it quits.
+
+[-r REPO_PATH]
+This is the repository path to pick up the services and axis2.xml
+
+[-l LOG_LEVEL]
+There are several log levels available. One could specify the log level we needed.
+LOG_LEVEL can be one of following<
+ AXIS2_LOG_LEVEL_CRITICAL - Log critical errors only
+ AXIS2_LOG_LEVEL_ERROR - Log errors critical errors
+ AXIS2_LOG_LEVEL_WARNING - Log warnings and above
+ AXIS2_LOG_LEVEL_INFO - Log info and above
+ AXIS2_LOG_LEVEL_DEBUG - Log debug and above (default)
+ AXIS2_LOG_LEVEL_TRACE - Log trace messages
+
+[-f LOG_FILE]
+One could specify a log file , when need to use a file other that
+default file (axis2.log).
+</pre></div>
+
+<a name="apa_mod"></a></p></div><div class="section"><a name="12__Apache2_Module"></a><h2>12. Apache2 Module</h2><p>To build Axis2/C with apache module, One need to give configuration
+options as</p><p>On Linux platform</p><p>./configure --with-apache2=[path to apache directory]</p><p><font color="#666666">NOTE: Some apache2 distributions install APR (Apache
+Portable Run-time) include files in a separate location which is required to
+build mod_axis2. In that case use: ./configure --with-apache2="<apache2
+directory>" --with-apr="<apr include files location>" [other
+configure options]</font></p><p>Then build the source tree</p>
+ <div class="source"><pre>
+ make
+ make install
+
+</pre></div>
+ <p>This will install mod_axis2.so into your "<your_path_to_axis2c>/lib"<br></br>
+On Win32 platform<br></br>
+Provide the apache2 location in configure.in file in APACHE_INSTALL_DIR</p>
+ <div class="source"><pre>
+ Example
+ APACHE_INSTALL_DIR = E:\Apache
+
+</pre></div>
+ <p>After compiling the sources build the mod_axis2.dll by issuing the command
+"nmake axis2_apache_module". This will build the mod_axis2.dll and copy it to
+%AXIS2C_HOME%\lib directory.</p>
+ <div class="source"><pre>
+Example
+ C:\axis2c\build\deploy\lib
+
+</pre></div>
+ <p>Deploying in Apache2 Web Server</p><p><font color="#666666">NOTE: To do the following tasks, you might need
+super user privileges in your machine.</font></p><p>Copy the mod_axis2 <font color="#4169E1">(libmod_axis2.so.0.0.0 on Linux
+and mod_axis2.dll in Windows)</font> to "<apache2 modules directory>"
+as mod_axis2.so</p>
+ <div class="source"><pre>
+ Example
+In Linux
+ cp $AXIS2C_HOME/lib/libmod_axis2.so.0.0.0
+ /usr/lib/apache2/modules/mod_axis2.so
+
+In Windows
+ copy C:\axis2c\build\deploy\lib\mod_axis2.dll
+ C:\Apache2\modules\mod_axis2.so
+
+
+</pre></div>
+ <p>Edit the Apache2's configuration file (generally httpd.conf) and add the
+following directives<br></br>
+</p>
+ <div class="source"><pre>LoadModule axis2_module<apache2 modules directory>/mod_axis2.so
+<Location /axis2>
+ SetHandler axis2_module
+ RepoPath <axis2 repository path>
+ LogFile <axis2 log file path>
+ Axis2LogLevel LOG_LEVEL
+</Location>
+
+</pre></div>
+ <p><font color="#666666">NOTE: Axis2 log file path should have write access
+to all users because by </font>default Apache Web Server runs as nobody.</p>
+ <div class="source"><pre>LOG_LEVEL can be one of following
+ AXIS2_LOG_LEVEL_CRITICAL - Log critical errors only
+ AXIS2_LOG_LEVEL_ERROR - Log errors critical errors
+ AXIS2_LOG_LEVEL_WARNING - Log warnings and above
+ AXIS2_LOG_LEVEL_INFO - Log info and above
+ AXIS2_LOG_LEVEL_DEBUG - Log debug and above (default)
+ AXIS2_LOG_LEVEL_TRACE - Log trace messages
+
+</pre></div>
+ <p><font color="#B22222">NOTE: Use forward slashes "/" for path separators in
+<apache2 modules directory>,<axis2 repository path> and <axis2
+log file path></font></p><p>Make sure that the apache2 user has the correct permissions to above
+paths</p><ul>
+ <li>Read permission to the repository</li>
+ <li>Write permission to the log file</li>
+</ul><p>Restart apache2 and test whether mod_axis2 module is loaded by typing the
+URL</p><p><a href="http://localhost/axis2/services" class="externalLink" title="External Link">http://localhost/axis2/services</a></p><p><a name="appA"></a></p></div><div class="section"><a name="Appendix_A"></a><h2>Appendix A</h2><div class="subsection"><a name="axis2_xml"></a><h3>axis2.xml</h3><p>The axis2.xml file is the configuration file for Axis2/C. It has 6 top
+level elements. They are <em>parameter, transportReciever,
+transportSender,module,phaseOrder</em> and <em>messageReciever</em>. Given
+below is a description about these elements, their sub elements , element
+atributes, possible valuses and their purpose.</p><p></p><p><em><strong>axisconfig</strong></em> is the root element</p><table class="bodyTable"><tbody>
+ <tr class="b"><th>Attribute</th><th>Possible Values</th></tr>
+ <tr class="a"><td>name</td><td>Axis2/C</td></tr>
+ </tbody></table><p></p><p>The description of the 6 top level elements is given below.</p><p></p></div><div class="subsection"><a name="parameter"></a><h3>parameter</h3><p>In Axis2/C a parameter is a name value pair. Each and every top level
+parameter available in the axis2.xml (direct sub elements of root element)
+will be transformed into properties in axisConfiguration. Therefore the top
+level parameters in configuration document can be accessed via
+axisConfiguration in the running system.</p><p>sub elements :- none</p><p>attributes:- name , locked</p><p></p><table class="bodyTable"><caption></caption><tbody>
+ <tr class="b"><th>Attribute</th><th>Description</th></tr>
+ <tr class="a"><td>name</td><td>Name of the parameter. The table below shows possible values of the
+ name attribute and their description.
+
+ <table class="bodyTable"><caption></caption><tbody>
+ <tr class="b"><th>Value</th><th>Description</th><th>Possibe text of parameter element</th></tr>
+ <tr class="a"><td>enableMTOM</td><td>Enable MTOM support when sending binary attachments</td><td>true or false</td></tr>
+ <tr class="b"><td>enableREST</td><td>Enable REST support</td><td>true or false</td></tr>
+ </tbody></table>
+ </td></tr>
+ <tr class="a"><td>locked</td><td>whether the parameter can be changed from the code. Following are
+ the possible values for the locked attribute.
+
+ <table class="bodyTable"><caption></caption><tbody>
+ <tr class="b"><th>Value</th><th>Description</th></tr>
+ <tr class="a"><td>true</td><td>The parameter cannot be changed from the code</td></tr>
+ <tr class="b"><td>false</td><td>The parmeter can be changed from the code.</td></tr>
+ </tbody></table>
+ </td></tr>
+ </tbody></table><p></p></div><div class="subsection"><a name="transportReciever"></a><h3>transportReciever</h3><p>This element spsecifies the transport Reciever details in an INOUT
+messange exchange scenario. The users can change the transport reciever port
+as they wishes.</p><p>attributes :- name, class</p><table class="bodyTable"><caption></caption><tbody>
+ <tr class="a"><th>Attribute</th><th>Description</th><th>Possible values</th></tr>
+ <tr class="b"><td>Name</td><td>Specify which transport protocol is used</td><td>http(when using http)</td></tr>
+ <tr class="a"><td>Class</td><td>Specify shared library which implements the transport interface</td><td>Name of the shared library.
+
+ <p>eg:-On Linux if the value is given as <em>foo</em> then shared
+ library is libfoo.so.</p>
+
+ <p>On Windows <em>foo.dll</em>.</p>
+ </td></tr>
+ </tbody></table><p></p><p>Sub elements of <em>transportReciever</em></p><p><em>transportReciever</em> can have zero or more parameters.(prameter
+elements) . An example element is shown below.</p><table class="bodyTable"><caption></caption><tbody>
+ <tr class="b"><th>Attribute</th><th>Description</th></tr>
+ <tr class="a"><td>name</td><td>Name of the parameter.
+
+ <table class="bodyTable"><caption></caption><tbody>
+ <tr class="b"><th>Value</th><th>Description</th><th>Possible text of parameter element</th></tr>
+ <tr class="a"><td>port</td><td>Transport listener port</td><td>Integer specifying the port number</td></tr>
+ </tbody></table>
+ </td></tr>
+ <tr class="b"><td>locked</td><td>whether the parameter can be changed from the code
+
+ <table class="bodyTable"><caption></caption><tbody>
+ <tr class="a"><th>Value</th><th>Description</th></tr>
+ <tr class="b"><td>true</td><td>Parameter cannot be changed from the code</td></tr>
+ <tr class="a"><td>false</td><td>The parmeter can be changed from the code.</td></tr>
+ </tbody></table>
+ </td></tr>
+ </tbody></table><p></p><p></p></div><div class="subsection"><a name="transportSender"></a><h3>transportSender</h3><p>This element specifies the transport senders used to send messages</p><p>attributes :- name, class</p><table class="bodyTable"><caption></caption><tbody>
+ <tr class="b"><th>Attribute</th><th>Description</th><th>Possible Values</th></tr>
+ <tr class="a"><td>name</td><td>Specify which transport protocol is used when sending messages</td><td>http(when using http)</td></tr>
+ <tr class="b"><td>class</td><td>Specify shared library which implements the transport interface</td><td><p>Name of the shared library.</p>
+
+ <p>eg:-On Linux if the value is given as <em>foo</em> then shared
+ library is libfoo.so.</p>
+
+ <p>On Windows <em>foo.dll</em>.</p>
+ </td></tr>
+ </tbody></table><p></p><p>Sub elements of <em>transportSender</em></p><p><em>transportSender</em> can have zero or more parameters.(prameter
+elements) . An example element is shown below.</p><table class="bodyTable"><caption></caption><tbody>
+ <tr class="a"><th>Attribute</th><th>Description</th></tr>
+ <tr class="b"><td>name</td><td>The name of the parameter.
+
+ <table class="bodyTable"><caption></caption><tbody>
+ <tr class="a"><th>Value</th><th>Description</th><th>Possible text of parameter element</th></tr>
+ <tr class="b"><td>PROTOCOL</td><td>Transport protocol used</td><td>Prtocol version. eg:- HTTP /1.1, HTTP/1.0</td></tr>
+ </tbody></table>
+ </td></tr>
+ <tr class="a"><td>locked</td><td>whether the parameter can be changed from the code
+
+ <table class="bodyTable"><caption></caption><tbody>
+ <tr class="b"><th>Value</th><th>Description</th></tr>
+ <tr class="a"><td>true</td><td>The parameter cannot be changed from the code</td></tr>
+ <tr class="b"><td>false</td><td>The parmeter can be changed from the code.</td></tr>
+ </tbody></table>
+ </td></tr>
+ </tbody></table><p></p></div><div class="subsection"><a name="module"></a><h3>module</h3><p>This element is optional. It is used when a particular module needs to be
+engaged for every service in the system.</p><table class="bodyTable"><caption></caption><tbody>
+ <tr class="a"><th>Attributes</th><th>Description</th><th>Possible Values</th></tr>
+ <tr class="b"><td>ref</td><td>the name of the module which is to be engaged globally</td><td>Name of the module.
+
+ <p>eg:- addressing</p>
+ </td></tr>
+ </tbody></table><p></p></div><div class="subsection"><a name="phaseOrder"></a><h3>phaseOrder</h3><p>The order of phases in execution chain has to be configured using phase
+order element.</p><table class="bodyTable"><caption></caption><tbody>
+ <tr class="a"><th>Attribute</th><th>Description</th><th>Possible Values</th></tr>
+ <tr class="b"><td>type</td><td>Flow to which the phase belongs to</td><td>inflow
+
+ <p>outflow</p>
+
+ <p>INfaultflow</p>
+
+ <p>Outfaultflow</p>
+ </td></tr>
+ </tbody></table><p>A flow is a collection of handlers which are invoked for a particular
+message.The types of flows are described below.</p><table class="bodyTable"><caption></caption><tbody>
+ <tr class="a"><th>Flow</th><th>Description</th></tr>
+ <tr class="b"><td>inflow</td><td>Collection of handlers invoked for a message coming in to the
+ system.</td></tr>
+ <tr class="a"><td>outflow</td><td>Collection of handles invoked for a message going out of the
+ system.</td></tr>
+ <tr class="b"><td>INfaultflow</td><td>Collection of handlers invoked for a incoming fault message.</td></tr>
+ <tr class="a"><td>Outfaultflow</td><td>Collection of handlers invoked for a outgoing fault message.</td></tr>
+ </tbody></table><p></p><p>sub elements of <em>phaseOrder</em></p><p><em>phase</em>:- represents available phases in the execution chain. The
+system predefined phases cannot be changed.</p><p>The system predefined phases are,</p><ul>
+ <li>Transport</li>
+ <li>PreDispatch</li>
+ <li>Dispatch</li>
+ <li>PostDispatch</li>
+ <li>MessageOut</li>
+</ul><table class="bodyTable"><caption></caption><tbody>
+ <tr class="b"><th>Attribute</th><th>Description</th><th>Possible Values</th></tr>
+ <tr class="a"><td>name</td><td>Specifies the name of the phase</td><td>TransportIn,Dispatch,PreDispatch,PostDispatch,MessageOut,
+
+ <p>User defined phases (can have user defined name)</p>
+ </td></tr>
+ </tbody></table><p></p><p>sub elements of phase</p><p><em>handler</em></p><table class="bodyTable"><caption></caption><tbody>
+ <tr class="b"><th>Attribute</th><th>Description</th><th>Possible Values</th></tr>
+ <tr class="a"><td>name</td><td>Specifies the handler name. Phase may contain zero or more
+ handlers.</td><td>Based on handler name.
+
+ <p>eg:- AddressingbasedDispatcher, RequestURIbaseddispatcher</p>
+ </td></tr>
+ <tr class="b"><td>class</td><td>Specify shared library which implements the handler</td><td><p>Name of the shared library.</p>
+
+ <p>eg:-On Linux if the value is given as <em>foo</em> then shared
+ library is libfoo.so.</p>
+
+ <p>On Windows <em>foo.dll</em>.</p>
+ </td></tr>
+ </tbody></table><p></p></div><div class="subsection"><a name="messageReciever"></a><h3>messageReciever</h3><p></p><table class="bodyTable"><caption></caption><tbody>
+ <tr class="a"><th>Attribute</th><th>Description</th><th>Possible Values</th></tr>
+ <tr class="b"><td>mep</td><td>Message Exchange Pattern</td><td>INOUT, INONLY</td></tr>
+ <tr class="a"><td>class</td><td>Specify the shared library which implements the transport interface
+
+ <p>If not specified Axis2/C default message reciever is used.</p>
+ </td><td>Name of the shared library.
+
+ <p>eg:-On Linux if the value is given as <em>foo</em> then shared
+ library is libfoo.so.</p>
+
+ <p>On Windows <em>foo.dll</em>.</p>
+ </td></tr>
+ </tbody></table><p><a name="appB"></a></p></div></div><div class="section"><a name="Appendix_B"></a><h2>Appendix B</h2><div class="subsection"><a name="services_xml"></a><h3>services.xml</h3><p>Configuration of a service is specified using services.xml.Each service or
+service archive file need to have a services.xml in order to be a valid
+service. The given below is a description of each element.</p><p></p><p>If services.xml describes a single service the root elemnt is
+<em>service</em>. If it is describing a service group, then the root element
+is <em>serviceGroup</em>. <em>service</em> will be a child element of
+serviceGroup, if there are multiple services specified in service.xml.</p></div><div class="subsection"><table class="bodyTable"><caption></caption><tbody>
+ <tr class="b"><th>Attributes</th><th>Description</th><th>Possible Values</th></tr>
+ <tr class="a"><td>name</td><td>Name of the service. This will be the name of the archive
+
+ <p>file for the service.</p>
+ </td><td>Depend on the service or the
+
+ <p>serviceGroup. eg:- echo,sg_math</p>
+ </td></tr>
+ </tbody></table><p></p></div><div class="subsection"><p>This is optional. This element can be used to describe the service in a
+human readable format.</p><p></p></div><div class="subsection"><p>This is optional. Can be used to engage modules at service level.</p><table class="bodyTable"><caption></caption><tbody>
+ <tr class="b"><th>Attributes</th><th>Description</th><th>Possible Values</th></tr>
+ <tr class="a"><td>ref</td><td>Name of the module which is to be engaged for the service</td><td>Name of the module which is to be engaged at service level.</td></tr>
+ </tbody></table><p></p><p></p></div><div class="subsection"><p>The service element can have any number of parameters as sub elemnts.</p><table class="bodyTable"><caption></caption><tbody>
+ <tr class="b"><th>Attributes</th><th>Description</th><th>Possible Values</th><th>Value of the text in parameter element</th></tr>
+ <tr class="a"><td>name</td><td>Specify the shared library the service is implemented</td><td>serviceClass</td><td>the service name. eg:- echo</td></tr>
+ <tr class="b"><td>locked</td><td>Specify whether the parameter can be changed from the code</td><td>true/false</td><td></td></tr>
+ </tbody></table><p></p></div><div class="subsection"><p>The operations which the service provide are specified here.</p><table class="bodyTable"><caption></caption><tbody>
+ <tr class="a"><th>Attributes</th><th>Description</th><th>Possible Values</th></tr>
+ <tr class="b"><td>name</td><td>name of the operation</td><td>eg:- echoString</td></tr>
+ </tbody></table><p>sub elements of <em>operation</em></p><p><em>parameter</em> elements can be present as sub elements. Zero or more
+parameters may be present.</p><table class="bodyTable"><caption></caption><tbody>
+ <tr class="a"><th>Attribute</th><th>Description</th><th>Possible Value</th><th>Parameter Vlue</th></tr>
+ <tr class="b"><td>name</td><td>ws-Addressing action mapping to the operation.</td><td>wsamapping</td><td>A URL representing the ws-Addressing action corresponding to the
+ operation</td></tr>
+ </tbody></table><p></p></div><div class="subsection"><p>An operation specific messageReciver is specified from this. This is
+optional.</p><table class="bodyTable"><caption></caption><tbody>
+ <tr class="a"><th>Attributes</th><th>Description</th><th>Possible Values</th></tr>
+ <tr class="b"><td>class</td><td>Shared library with the message reciever implementation</td><td>Name of the shared library.
+
+ <p>eg:-On Linux if the value is given as <em>foo</em> then shared
+ library is libfoo.so.</p>
+
+ <p>On Windows <em>foo.dll</em>.</p>
+ </td></tr>
+ </tbody></table><p><a name="appC"></a></p></div></div><div class="section"><a name="Appendix_C"></a><h2>Appendix C</h2><div class="subsection"><a name="module_xml"></a><h3>module.xml</h3><p>The module.xml provides the configuration details for a particular module
+in Axis2/C. The top level element is <em>module</em>.</p><p></p></div><div class="subsection"><a name="module"></a><h3>module</h3><table class="bodyTable"><caption></caption><tbody>
+ <tr class="a"><th>Attributes</th><th>Description</th><th>Possible Values</th></tr>
+ <tr class="b"><td>name</td><td>Name of the module</td><td>eg:- addressing</td></tr>
+ <tr class="a"><td>class</td><td>Specify shared library which implements the module.</td><td>Name of the shared library.
+
+ <p>eg:-On Linux if the value is given as <em>foo</em> then shared
+ library is libfoo.so.</p>
+
+ <p>On Windows <em>foo.dll</em>.</p>
+ </td></tr>
+ </tbody></table><p></p><p>Other elements are child elements of <em>module</em>.</p><p></p></div><div class="subsection"><a name="parameter"></a><h3>parameter</h3><p>Any number of parameters can be present.It depends on the module.</p><table class="bodyTable"><caption></caption><tbody>
+ <tr class="b"><th>Attributes</th><th>Description</th><th>Possible Values</th></tr>
+ <tr class="a"><td>name</td><td>Name of the parameter</td><td>depends on the module</td></tr>
+ <tr class="b"><td>locked</td><td>Whether the parameter can be changed from the code</td><td>true- cannot be changed
+
+ <p>false- can be changed</p>
+ </td></tr>
+ </tbody></table><p></p></div><div class="subsection"><a name="Description"></a><h3>Description</h3><p>No attributes or sub elements. Describes the behaviour of the module. This
+element is optional.</p><p></p></div><div class="subsection"><a name="inflow"></a><h3>inflow</h3><p>Encapsulate details added to the inflow by the module. Zero or one element
+is possible.No attributes.</p><p>sub elements of <em>inflow</em></p><p><em>handler</em>:- Contains details about the module specific handlers
+added to a particular flow. Zero or more handlers can be added.</p><table class="bodyTable"><caption></caption><tbody>
+ <tr class="a"><th>Attributes</th><th>Description</th><th>Possible Values</th></tr>
+ <tr class="b"><td>name</td><td>Name of the handler</td><td>Depends on the handlers in the module.</td></tr>
+ <tr class="a"><td>class</td><td>Specify shared library which implements the handler</td><td><p>Name of the shared library.</p>
+
+ <p>eg:-On Linux if the value is given as <em>foo</em> then shared
+ library is libfoo.so.</p>
+
+ <p>On Windows <em>foo.dll</em>.</p>
+ </td></tr>
+ </tbody></table><p></p><p>sub elemnts of <em>handler</em></p><p><em>order:</em>- Specify where to put a handler in a particular phase.</p><table class="bodyTable"><caption></caption><tbody>
+ <tr class="b"><th>Attribute</th><th>Description</th><th>Possible Values</th></tr>
+ <tr class="a"><td>phase</td><td>the name of the phase the handler belongs to</td><td>depends on the handler</td></tr>
+ <tr class="b"><td>phaseLast</td><td>Indicate the handler is last handler of the phase</td><td>true</td></tr>
+ <tr class="a"><td>phaseFirst</td><td>Indicate the handler is first handler of the phase.</td><td>true</td></tr>
+ <tr class="b"><td>before</td><td>Handler should be invoked before the handler specified by before
+ handler</td><td>handler name</td></tr>
+ <tr class="a"><td>after</td><td>Handler should be invoked after the handler specified by after
+ handler</td><td>hadler name</td></tr>
+ </tbody></table><p>phase is compulsory. Given below is combinations possible from the other 4
+attributes.</p><table class="bodyTable"><caption></caption><tbody>
+ <tr class="b"><th>Combination</th><th>Description</th></tr>
+ <tr class="a"><td>phaseLast</td><td>Indicate the handler is last handler of the phase</td></tr>
+ <tr class="b"><td>phasefirst</td><td>Indicate the handler is first handler of the phase.</td></tr>
+ <tr class="a"><td>before</td><td>Handler should be invoked before the handler specified by before
+ handler</td></tr>
+ <tr class="b"><td>after</td><td>Handler should be invoked after the handler specified by after
+ handler</td></tr>
+ <tr class="a"><td>before & after</td><td>Handler should be invoked before the handler specified by the
+ before handler and
+
+ <p>after the handler specified by the after handler.</p>
+ </td></tr>
+ </tbody></table><p></p><p><em>outflow</em>,<em>INfaultflow</em>,<em>OUTfaultflow</em> elements have
+the same syntax as that of <em>inflow</em>.</p><p></p></div><div class="subsection"><a name="operation"></a><h3>operation</h3><p>This is used when a module wants to add an operation to an engaged
+service.</p><table class="bodyTable"><caption></caption><tbody>
+ <tr class="b"><th>Attributes</th><th>Description</th><th>Possible Values</th></tr>
+ <tr class="a"><td>name</td><td>Name of the operation(compulsory)</td><td>Depends on the module</td></tr>
+ <tr class="b"><td>mep</td><td>Message Exchange Pattern</td><td>INOUT,INONLY</td></tr>
+ </tbody></table><p>sub elements of <em>operatio</em><em>n</em></p><p>Any number of parameters can be included as sub elements in the operation
+element.</p><p>The <em>messageReciever</em> parameter specifies the message reciever the
+message is intended to. If it is not set, the default message reciever is
+used.</p><p></p><p><a name="appD"></a></p></div></div><div class="section"><a name="Appendix_D"></a><h2>Appendix D</h2><p>This document describes about various types of options in the
+axis2_options.h. These options are used by the service client before sending
+messages.</p><p><strong>AXIS2_OPTIONS_SET_ACTION(options, env, action)</strong></p><p>Set the ws-addressing action in the addressing header.</p><table class="bodyTable"><caption></caption><tbody>
+ <tr class="a"><th>Parameter</th><th>Description</th></tr>
+ <tr class="b"><td>axis2_options_t *options</td><td>options pointer to options struct</td></tr>
+ <tr class="a"><td>const axis2_env_t *env</td><td>env pointer to environment struct</td></tr>
+ <tr class="b"><td>const axis2_char_t *action</td><td>action pointer to action string</td></tr>
+ </tbody></table><p></p><p><strong>AXIS2_OPTIONS_SET_FAULT_TO(options, env, fault_to)</strong></p><p>Set the end point reference which may recieve the message in a case of
+fault.</p><table class="bodyTable"><caption></caption><tbody>
+ <tr class="a"><th>Parameter</th><th>Description</th></tr>
+ <tr class="b"><td>axis2_options_t *options</td><td>options pointer to options struct</td></tr>
+ <tr class="a"><td>const axis2_env_t *env</td><td>env pointer to environment struct</td></tr>
+ <tr class="b"><td>axis2_endpoint_ref_t *fault_to</td><td>fault_to pointer to endpoint reference struct representing fault to
+ address.</td></tr>
+ </tbody></table><p></p><p><strong>AXIS2_OPTIONS_SET_FROM(options, env, from)</strong></p><p>Some services need to know the source from which the messgae comes. This
+option set the from enfdpoint</p><table class="bodyTable"><caption></caption><tbody>
+ <tr class="a"><th>Parameter</th><th>Description</th></tr>
+ <tr class="b"><td>axis2_options_t *options</td><td>options pointer to options struct</td></tr>
+ <tr class="a"><td>const axis2_env_t *env</td><td>env pointer to environment struct</td></tr>
+ <tr class="b"><td>axis2_endpoint_ref_t *from</td><td>from pointer to endpoint reference struct representing from to
+ address</td></tr>
+ </tbody></table><p><strong>AXIS2_OPTIONS_SET_TO(options, env, to)</strong></p><p>Sets the endpoint reference the message is destined to.</p><table class="bodyTable"><caption></caption><tbody>
+ <tr class="a"><th>Parameter</th><th>Description</th></tr>
+ <tr class="b"><td>axis2_options_t *options</td><td>options pointer to options struct</td></tr>
+ <tr class="a"><td>const axis2_env_t *env</td><td>env pointer to environment struct</td></tr>
+ <tr class="b"><td>axis2_endpoint_ref_t *to</td><td>to pointer to endpoint reference struct representing to address</td></tr>
+ </tbody></table><p><strong>AXIS2_OPTIONS_SET_TRANSPORT_RECEIVER(options, env,
+receiver)</strong></p><p>Set the transport reciever in a IN-OUT message exchange scenario.</p><table class="bodyTable"><caption></caption><tbody>
+ <tr class="a"><th>Parameter</th><th>Description</th></tr>
[... 238 lines stripped ...]
---------------------------------------------------------------------
To unsubscribe, e-mail: axis-cvs-unsubscribe@ws.apache.org
For additional commands, e-mail: axis-cvs-help@ws.apache.org