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 du...@apache.org on 2007/04/20 07:55:06 UTC
svn commit: r530659 [2/2] -
/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=530659&r1=530658&r2=530659
==============================================================================
--- webservices/axis2/trunk/c/xdocs/docs/axis2c_manual.html (original)
+++ webservices/axis2/trunk/c/xdocs/docs/axis2c_manual.html Thu Apr 19 22:55:05 2007
@@ -1,2936 +1,2935 @@
-<html>
-<head>
- <title>Apache Axis2/C Manual</title>
- <meta http-equiv="content-type" content="text/html; charset=UTF-8">
-</head>
-
-<body lang="en-US" dir="ltr">
-<h2>Preamble</h2>
-
-<p style="margin-bottom: 0in">This document is intended to be a reference
-manual for <a href="http://ws.apache.org/axis2/c">Apache Axis2/C</a>. This
-manual details how Axis2/C can be used to provide and consume Web
-services.</p>
-
-<p style="margin-bottom: 0in">Please send your feedback to the Apache Axis2/C
-developer mailing list (<a
-href="mailto:axis-c-dev@apache.org">axis-c-dev@apache.org</a>). Subscription
-details are available on the <a
-href="http://ws.apache.org/axis2/c/mail-lists.html">Axis2 site</a>.</p>
-
-<p>This document uses the following conventions:</p>
-<ul>
- <li>The directory each package is installed in is given with an
- "_INSTALL_DIR" suffix to the package name. For example, the path in which
- Libxml2 is installed is referred to as LIBXML2_INSTALL_DIR</li>
-</ul>
-
-<h1 class="western"><a name="toc">Axis2/C Manual - Contents</a></h1>
-<ol>
- <li><a href="#quick_start">Quick Start Guide</a></li>
- <li><a href="#repo_folder">Repository Folder</a></li>
- <li><a href="#svc_api">Service API</a></li>
- <li><a href="#client_api">Client API</a></li>
- <li><a href="#rest">REST</a></li>
- <li><a href="#mtom">MTOM</a></li>
- <li><a href="#engaging_module">Engaging a Module</a></li>
- <li><a href="#ws_addressing">WS-Addressing</a></li>
- <li><a href="#writing_module">Writing a Module</a></li>
- <li><a href="#simple_axis_server">Simple Axis Server</a></li>
- <li><a href="#mod_axis2">Deploying with Apache2 HTTP Web Server</a></li>
- <li><a href="#ssl_client">Using SSL Client</a></li>
- <li><a href="#proxy">Using Proxy Support</a></li>
- <li><a href="#wsdl2c">WSDL2C Tool</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>
-<a name="quick_start"></a>
-
-<h1>1. Quick Start Guide</h1>
-
-<p>This section is aimed to help you get a Web service running in a short
-time using Axis2/C, and consume that service using an Axis2/C client.</p>
-
-<p>First, <a href="http://ws.apache.org/axis2/c/download.cgi">download</a>
-the latest binary release from Apache Axis2/C. 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, and set the AXIS2C_HOME
-environment variable to point to this extracted folder. For Linux, you may
-have to set the LD_LIBRARY_PATH environment variable to include the lib
-folder (e.g. add $AXIS2C_HOME/lib). For MS Windows, you will have to add the
-lib folder to your PATH variable to include the Axis2/C DLLs to your path.</p>
-
-<p>Now you should be able to change the directory to the bin folder of the
-extracted folder, and run the simple axis server in one command shell. Then
-change the directory 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">installation
-guide</a> for more details.</p>
-
-<p>Once you have Axis2/C up and running successfully, you can start writing
-your own services and clients. The following sections explain how to write
-your first service and client with Axis2/C.</p>
-
-<h2 class="western">1.1 Hello Service</h2>
-
-<p>Let's see how you can write your first Web service with Axis2/C and how to
-deploy it.</p>
-
-<p>The first service that we are going to write is named "hello" with a
-single operation named "greet" in the service. This "greet" operation, when
-invoked by the client, will expect the client to send a greeting in the
-request, and in turn send a greeting in the response. Following are examples
-of XML payloads exchanged between the client and the service:</p>
-
-<p>Request:</p>
-<pre> <greet>
- Hello Service!
- <greet></pre>
-
-<p>Response:</p>
-<pre> <greetResponse>
- Hello Client!
- <greetResponse></pre>
-<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>
- In our sample, we will have one function that implements the "greet"
- operation. <br>
- We will name that function <code>axis2_hello_greet</code>.</li>
- <li><b>Implement the functions defined by the
- <code>axis2_svc_skeleton</code> interface</b><br>
- <code>axis2_svc_skeleton</code> interface expects the functions
- <code>init</code>, <code>invoke</code>, <code>on_fault</code> and
- <code>free</code> to be implemented by our service.<br>
- In our sample, we would implement those and name them as
- <code>hello_init</code>, <code>hello_invoke</code>,
- <code>hello_on_fault</code> and <code>hello_free</code> respectively.<br>
- </li>
- <li><b>Implement the create function, that would create an instance of the
- service skeleton</b><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 the above step.<br>
- </li>
- <li><b>Implement axis2_get_instance and axis2_remove_instance
- functions</b><br>
- These functions are used to create and destroy service instances by the
- engine, and each service must define these functions.<br>
- </li>
- <li><b>Write the services.xml file for the service</b><br>
- The 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>
- As previously decided, we will name the service "hello", the operation
- "greet" and the shared library libhello.so on Linux and hello.dll on MS
- Windows.<br>
- </li>
-</ol>
-
-<h3 class="western">1.1.1 Operation Implementation</h3>
-
-<p>Look for the <code>axis2_hello_greet</code> function in the <a
-href="hello/service/hello_svc.c.html">hello_svc.c</a> source file.</p>
-
-<p>This function implements the business logic for the greet operation. We
-will be calling this function from our implementation of the invoke function.
-Basically, this function receives the request payload as an
-<code>axiom_node</code>, process it to understand the request logic, and
-prepares the response as an <code>axiom_node</code> and returns that.</p>
-
-<h3 class="western">1.1.2 Skeleton Create Method</h3>
-
-<p>Look for the <code>axis2_hello_create</code> function in the <a
-href="hello/service/hello_svc.c.html">hello_svc.c</a> source file.</p>
-
-<p>The create function creates and returns a new
-<code>axis2_svc_skeleton</code> instance. The most important aspect to note
-about this function is the function pointer assignments. They are used to map
-the interface operations to the corresponding functions of the
-implementation. This is done by assigning the ops member of the service
-skeleton to the address of the ops struct variable.</p>
-
-<h3>1.1.3 Invoking Operation Implementation</h3>
-
-<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>
-
-<p>Look for the <code>hello_invoke</code> function in the <a
-href="hello/service/hello_svc.c.html">hello_svc.c</a> source file.</p>
-
-<p>In our implementation of the <code>hello_invoke</code>, 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 will have to look into
-the information in the message context to map it to the exact operation. <br>
-The Axis2/C engine will call the invoke method with an
-<code>axiom_node</code>, containing the request payload, and
-<code>axis2_msg_ctx</code> instance, containing the message context
-information, in addition to the service skeleton and the environment
-pointers. We can use the message context to extract whatever information we
-deem necessary that is related to the incoming message. The Axis2/C engine
-expects the invoke method to return a pointer to an <code>axiom_node</code>,
-representing the response payload.</p>
-
-<h3>1.1.4 Full Source</h3>
-
-<p>Here is the complete source code for the service : <a
-href="hello/service/hello_svc.c.html">hello_svc.c</a></p>
-
-<h3>1.1.5 Service Descriptor</h3>
-
-<p>The services.xml file contains details on the service that would be read
-by the Axis2/C deployment engine during server start up time. The following
-shows the contents for the services.xml file for the hello service.</p>
-<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>
-
-<p>The service configuration shown above specifies that the name of the
-service is hello. <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 MS Windows. The description element contains a brief description
-of the service. <br>
-There can be one or more operation elements. For this sample, we only have
-one operation, with the name "greet".<br>
-</p>
-
-<h3>1.1.6 Compiling the Service</h3>
-
-<p>You can compile the service sample as shown below.</p>
-
-<p>On Linux:</p>
-<pre>gcc -shared -olibhello.so -I$AXIS2C_HOME/include/axis2-1.0/ -L$AXIS2C_HOME/lib -laxis2 hello_svc.c </pre>
-
-<p>On MS Windows:</p>
-
-<p>to compile,</p>
-<pre>cl.exe /D "WIN32" /D "_WINDOWS" /D "_MBCS" /D "AXIS2_DECLARE_EXPORT" /D "AXIS2_SVR_MULTI_THREADED" /w /nologo /I %AXIS2C_HOME%\include /c hello_svc.c</pre>
-
-<p>to link,</p>
-<pre>link.exe /nologo /LIBPATH:%AXIS2C_HOME%\lib axutil.lib axiom.lib axis2_parser.lib axis2_engine.lib /DLL /OUT:hello.dll *.obj</pre>
-
-<h3>1.1.7 Deploying the Service</h3>
-
-<p>To make the service available to be consumed by the clients, we have to
-deploy the service. To deploy the service, you have to create a folder named
-'hello' in the AXIS2C_HOME/services folder, and copy the services.xml file
-and the shared library file (libhello.so on Linux or hello.dll on MS 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 the 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">http://localhost:9090/axis2/services</a>.
-You should get an entry for the hello service on the page that is
-displayed.</p>
-
-<h2 class="western" style="margin-top: 0in; margin-bottom: 0in">1.2 Hello
-Client</h2>
-
-<p>Now that you know how to write a service with Axis2/C, let's see how to
-write a client to consume that service. The request payload that the client
-will 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:</p>
-<ol>
- <li><b>Create the environment to be used by the client.</b> <br>
- Each function in Axis2/C takes a pointer to the environment instance that
- encapsulates the memory allocator, error handler, and logging and
- threading mechanisms. The <code>axutil_env_create_all</code> method can
- be used to create a default, ready to use environment instance.<br>
- </li>
- <li><b>Create an options instance, and set options</b>.<br>
- The<code> axis2_options</code> struct can be used to set the client side
- options. For 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>
- The<code> axis2_svc_client</code> struct is meant to be used by the users
- to consume Web 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 <a href="#repo_folder">repository</a> is explained in
- detail in a later section.<br>
- </li>
- <li><b>Set options to service client instance</b><br>
- The options created in an earlier step have to be set on the service
- client, indicating the options that are meant to be used by the service
- client.<br>
- </li>
- <li><b>Send the request and receive the response</b><br>
- The service client's <code>axis2_svc_client_send_receive</code> method
- can be used to invoke the send receive operation on the service client
- instance.<br>
- The send receive operation takes the request payload as an
- <code>axiom_node</code> and returns the response payload as an
- <code>axiom_node</code>.</li>
- <li><b>Process the response</b><br>
- Process the response in line with the client business logic.</li>
-</ol>
-
-<h3>1.2.1 Creating and Setting Options</h3>
-<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>
-
-<p>In the above section of code, an <code>axis2_options</code> 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>
-
-<h3>1.2.2 Using Service Client</h3>
-<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>
-
-<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 can be set on top
-of the service client and how to invoke the send receive operation with a
-request payload. Once the response is received, the response payload will be
-stored in the <code>ret_node</code>, which is a pointer to an
-<code>axiom_node</code> that can be used to process the response further.</p>
-
-<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>
-
-<h3>1.2.4 Compiling the Client</h3>
-
-<p>You can compile the client sample as shown below.</p>
-
-<p>On Linux:</p>
-<pre>gcc -o hello -I$AXIS2C_HOME/include -L$AXIS2C_HOME/lib -laxis2 hello.c</pre>
-
-<p>On MS Windows:</p>
-
-<p>to compile,</p>
-<pre>cl.exe /nologo /D "WIN32" /D "_WINDOWS" /D "_MBCS" /I %AXIS2C_HOME%\include /c hello.c</pre>
-
-<p>to link,</p>
-<pre>link.exe /LIBPATH:%AXIS2C_HOME%\lib axutil.lib axiom.lib axis2_parser.lib axis2_engine.lib /OUT:hello.exe *.obj</pre>
-
-<h3>1.2.5 Running the Client</h3>
-
-<p>To run the client, make sure you start the simple axis server and then run
-the hello executable.</p>
-
-<p style="margin-bottom: 0in"><br>
-</p>
-<a name="repo_folder"></a>
-
-<h1>2. Repository Folder</h1>
-
-<p>Repository is a folder where all Axis2/C related configurations as well as
-services and modules are located. The following shows the folder structure of
-the repository:</p>
-<img src="images/axis2c_repo.gif">
-
-<p>Here the name of the repository folder is axis2c_repo. In your system, you
-can specify any folder name of your choice. There are three sub folders
-available in the repository. In addition to that, the axis2.xml configuration
-file is also located in the repository. The following table describes the
-purpose of the repository contents.</p>
-
-<table border="1">
- <caption>Axis2/C Repository Sub-folders</caption>
- <tbody>
- <tr>
- <th>Folder Name</th>
- <th>Description</th>
- </tr>
- <tr>
- <td><p>lib</p>
- </td>
- <td><p>The lib folder contains the libraries required to run the
- 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 in
- the repository lib folder. <br>
- It is mandatory that the lib folder is there in the repository.</p>
- </td>
- </tr>
- <tr>
- <td><p>modules</p>
- </td>
- <td><p>The modules folder contains the modules deployed with Axis2/C.
- Each module deployed will have its own sub folder inside the modules
- folder. For example, if the addressing module is deployed, then there
- will be a sub folder named addressing inside the modules folder of
- the repository.<br>
- At deployment, the Axis2/C deployment engine would traverse the
- modules folders to find out what modules are available.<br>
- The modules folder is optional. If it is empty or non-existent, that
- means that there are no deployed modules.</p>
- </td>
- </tr>
- <tr>
- <td><p>services</p>
- </td>
- <td><p>The services folder contains the services deployed with Axis2/C.
- Each service deployed will have its own sub folder inside the
- services folder, or live inside one of the sub folders.<br>
- At deployment, the Axis2/C deployment engine will traverse the
- services folders to find out what services are available.<br>
- The services folder is optional. If it is empty or non-existent, that
- means that there are no deployed services.</p>
- </td>
- </tr>
- <tr>
- <td><p>axis2.xml</p>
- </td>
- <td><p>The axis2.xml file is the configuration file of Axis2/C.<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 in
- which you have the axis2.xml file.</p>
- </td>
- </tr>
- </tbody>
-</table>
-
-<p>Both clients as well as the services written using Axis2/C can use the
-same repository. However you can use one repository for the server side and
-another one for the client side. The services folder is used only when the
-repository is used by the server side. When the repository is used by the
-client, the services folder, if present, will not be used.</p>
-
-<p>The Axis2/C binary distribution, when extracted, can be considered as
-ready for use as your repository folder. If you are building Axis2/C from the
-source distribution, when you build the source, including the samples, the
-installation destination will be ready for use as your repository folder.</p>
-
-<p>The simple axis server (that is axis2_http_server binary), the client
-samples, and the HTTPD module (Axis2 Apache2 module) require the repository
-folder to be specified in order to run correctly.</p>
-
-<p></p>
-
-<h2>2.1 Module Folders</h2>
-
-<p>As described earlier, all the modules are placed inside the modules folder
-of the repository, and each module will have its own sub folder within the
-modules folder.<br>
-The folder in which a module is placed must have the same name as the module
-name. For example, the addressing module will be placed in a sub folder named
-addressing.<br>
-</p>
-
-<p>Inside the folder corresponding to a module, the shared library
-implementing the module and the module configuration file, module.xml, is
-placed. It is a must that these two files are present inside each folder
-representing a module. The module.xml file will be processed by the
-deployment engine to find out module specific information such as the module
-name, set of handlers, the flows into which those handlers are to be added,
-etc.</p>
-
-<h2>2.1 Service Folders</h2>
-
-<p>All the services are placed inside the services folder of the repository,
-and each service will be in one of the sub folders within the services
-folder. Axis2/C has a concept called service groups, where there can be one
-or more services inside a service group. A single stand alone service is
-assigned a service group with the same name as that of the service by the
-Axis2/C engine for the purpose of easy handling. Therefore the sub folders in
-the services folder correspond to the service groups.</p>
-
-<p>A service, if deployed as a stand alone service, will reside inside a
-folder with the same name as that of the service. For example, the echo
-service will be placed in a sub folder named echo. The shared library
-implementing the service and the service configuration file, the
-services.xml, will be placed inside the folder corresponding to a service.
-Given 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, you can always place a single service inside a single folder, which
-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 will be multiple shared libs, yet there is only one services.xml
-file configuring all those services. The services.xml file is processed by
-the deployment engine to find out the service group and the service specific
-information such as the service group name, service name, the set of
-operations for each service, etc.</p>
-<a name="svc_api"></a>
-
-<h1>3. Service API</h1>
-
-<p>We have already seen how to write a service in the Quick Start Guide
-section of this manual. This section covers the service API of Axis2/C in
-more detail.</p>
-
-<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, you should implement the functions adhering to the function
-pointer signatures of the members of the <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 the members of the ops member of service skeleton.</p>
-
-<p>The following table details the signatures of the function pointer members
-of the <code>axis2_svc_skeleton</code> struct implemented by a service.</p>
-
-<table border="1">
- <caption></caption>
- <tbody>
- <tr>
- <th>Function Signature</th>
- <th>Description</th>
- </tr>
- <tr>
- <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. The Axis2/C
- engine initializes a service skeleton instance once per deployed
- service, during the first request made to the service.</td>
- </tr>
- <tr>
- <td width="410"><pre>axiom_node_t *(AXIS2_CALL*
- invoke )( axis2_svc_skeleton_t *svc_skeli,
- const axutil_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>
- <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 is 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>
-
-
-<p>There are two more methods that a service should implement. Once a service
-is deployed, the message receiver of the Axis2/C engine has to create a
-service instance at run time for the purpose of invoking it. For this, it
-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
-<code>axis2_remove_instance</code> in the shared library for clean up
-purposes.</p>
-
-<p>Note that service object instantiation happens once per service. When the
-first request is received by the service, a service skeleton instance is
-created and initialized. The same object instance will be re-used by the
-subsequent requests.</p>
-
-<p>You can find an example on how to implement the service skeleton interface
-in the <a href="hello/service/hello_svc.c.html">hello_svc.c</a> source file,
-which is the example used in the <a href="#quick_start">Quick Start
-Guide</a>. More advanced samples can be found in the samples folder of the
-Axis2/C distribution.</p>
-<a name="client_api"></a>
-
-<h1>4. Client API</h1>
-
-<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 <code>axis2_op_client</code>, the
-operation client API. For most of the use cases, the service client API is
-sufficient.</p>
-
-<p>The behavior of the service client can be fine tuned with the options
-passed to the service client. You can set the options by creating an
-<code>axis2_options</code> instance. The bare minimum that you need to set is
-the endpoint URI to which the request is to be sent. An example of this was
-given in the <a href="#quick_start">Quick Start Guide section</a>.</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 method of invoking an operation depends on
-3 things. They are,</p>
-<ol>
- <li>The Message Exchange Pattern (MEP)</li>
- <li>Synchronous/Asynchronous behavior (Blocking/Non-Blocking)</li>
- <li>Two-way or one-way transport</li>
-</ol>
-
-<p>Many service operation invocation scenarios can be obtained by combining
-the above three factors. The service client interface provides the necessary
-API calls to achieve this.</p>
-
-<p>Deciding the Message Exchange Pattern (MEP)</p>
-
-<p>There are 2 message exchange patterns.</p>
-<ol>
- <li>Out-Only</li>
- <li>Out-In</li>
-</ol>
-
-<p>In the Out-Only MEP, the client doesn't expect a reply from the server.
-The service client provides two methods of using the Out-Only MEP.</p>
-
-<p></p>
-
-<h3><code>axis2_svc_client_fire_and_forget</code></h3>
-
-<p>Sends a message and forgets about it. This method is used to interact with
-a service operation whose MEP is In-Only. There is no way of getting an error
-from the service using this method. However, you may still get client-side
-errors, such as host unknown.</p>
-
-<h3><code>axis2_svc_client_send_robust</code></h3>
-
-<p>This method too is used to interact with a service operation whose MEP is
-In-Only. However, unlike <code>axis2_svc_client_fire_and_forget</code>, this
-function reports an error back to the caller if a fault triggers on the
-server side.</p>
-
-<p>When using Out-In MEP, the client expects a reply from the server.
-<code>axis2_svc_client_send_receive</code> and
-<code>axis2_svc_client_send_receive_non_blocking<code>
-</code></code>functions support this MEP<code><code>.</code></code></p>
-
-<h3><code>axis2_svc_client_send_receive</code></h3>
-
-<p>This method is used to interact with a service operation whose MEP is
-In-Out. It sends an XML request and receives an XML response.</p>
-
-<p>Returns a pointer to the AXIOM node representing the XML response. This
-method blocks the client until the response arrives.</p>
-
-<h3><code>axis2_send_receive_non_blocking</code></h3>
-
-<p>This method too, is used to interact with a service operation whose MEP is
-In-Out. It sends an XML request and receives an XML response, but the client
-does not block for the response.</p>
-
-<p>In this method, the client does not block for the response, but instead it
-expects the user to set a call back to capture the response.<br>
-</p>
-
-<p>Please have a look at the <code>axis2_svc_client.h</code> header file for
-more information on function signatures of the above mentioned functions.</p>
-
-<h3>Synchronous vs. Asynchronous Behavior (Blocking/Non-Blocking)</h3>
-
-<p>This will determine whether the client would block for the response
-(synchronous) or return immediately expecting the response to be handled by a
-callback (asynchronous, in other words non-blocking) in an Out-In MEP
-scenario.<br>
-<code>axis2_svc_client_send_receive</code> operates in synchronous mode,
-whereas <code>axis2_svc_client_send_receive_non_blocking</code> operates in
-asynchronous mode.<br>
-</p>
-
-<h3>Two-Way or One-Way Transport</h3>
-
-<p>If the transport is two-way, then only one channel is used, which means
-the request is sent and the response is received on the same channel. If the
-transport is one-way, then the request is sent on one channel and the
-response is received on a separate channel.<br>
-If we want to use a separate channel for the response, a separate listener
-has to be started to receive the response, This can be done by setting the
-separate listener option to True using the
-<code>axis2_options_set_use_separate_listener</code> function above the
-options.</p>
-
-<p>Please have a look at the <code>echo_blocking_dual</code> sample to see
-how to set the separate channel option.</p>
-
-<p>Please see <a href="#appD">Appendix D</a> for further details on setting
-options.</p>
-<a name="rest"></a>
-
-<h1>5. REST</h1>
-
-<p>Axis2/C comes with plain old XML (POX) like REST support. A given service
-can be exposed both as a SOAP service as well as a REST service. If you want
-to consume Web services using REST style calls, you can use either the HTTP
-POST method or the HTTP GET method.</p>
-
-<p>The following example code fragment shows how to enable a REST style
-invocation.</p>
-<pre>axis2_options_set_enable_rest(options, env, AXIS2_TRUE);</pre>
-
-<p>You can use the same code that you use with a SOAP call, and do REST style
-invocation by just enabling REST using the option setting shown above.</p>
-
-<p>The default HTTP method used with REST is HTTP POST. If you need to change
-it to the HTTP GET method, the following needs to be done.</p>
-<pre>axis2_options_set_http_method(options, env, AXIS2_HTTP_GET);</pre>
-
-<p>Please have a look at the <code>echo_rest</code> sample for a complete
-source code on how to use REST.</p>
-<a name="mtom"></a>
-
-<h1>6. MTOM</h1>
-
-<p>Axis2/C allows you to send and receive binary data with SOAP messages
-using MTOM/XOP conventions. When sending and receiving attachments, you have
-to use the service client (<code>axis2_svc_client</code>) API to perform the
-send and receive operations, and provide or consume binary data in relation
-to the AXIOM payloads.</p>
-
-<p>In order to send a binary attachment, you need to build the AXIOM payload
-and attach the data handler with binary content to the payload.</p>
-<pre><soapenv:Body>
- <ns1:mtomSample xmlns:ns1="http://ws.apache.org/axis2/c/samples/mtom">
- <ns1:fileName>test.jpg</ns1:fileName>
- <ns1:image>
- <xop:Include xmlns:xop="http://www.w3.org/2004/08/xop/include"
- href="cid:1.f399248e-8b39-1db1-3124-0015c53de2e5@apache.org"></xop:Include>
- </ns1:image>
- </ns1:mtomSample>
-</soapenv:Body></pre>
-
-<p>In the above sample payload shown, we place our image file as text within
-an image element</p>
-<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>
-
-<p>When sending attachments, you can configure the client either to send the
-attachment in the optimized format or non-optimized format.</p>
-
-<p>To do this, set the option <code>axis2_options_set_enable_mtom(options,
-env, AXIS2_TRUE);</code>or the setting
-<code><enableMtom>true</enableMtom> </code>in axis2.xml</p>
-
-<p>If enableMTOM is set to True, the attachment is sent as it is, out of the
-SOAP body, using MIME headers. Also the payload will have an XOP:Include
-element, referring to the MIME part that contains the binary attachment.
-Sending the attachment as it is, in pure binary format, is called binary
-optimized format. In the case of binary non-optimized format, where
-enableMTOM is False, the attachment content is sent in the payload itself, as
-a base64 encoded string.</p>
-
-<p>Please have a look at the <code>mtom</code> sample for a complete example
-on how to use MTOM.</p>
-<a name="engaging_module"></a>
-
-<h1>7. Engaging a Module</h1>
-
-<p>A module is a set of handlers that helps to extend the message processing
-behavior of the Axis2/C engine. Modules have the concepts of being Available
-and Engaged associated with them. Available means modules are deployed in the
-system but not activated. They will be activated only after being engaged.
-Every module comes with its own module.xml file . This module.xml file
-specifies the module specific handlers and the phases into which the handlers
-are to be placed in the handler chain. Some of the module specific handlers
-may be put into system predefined phases. In that case, the module.xml file
-should specify where to put the handlers relative to the others in that
-phase. Sometimes a module may define its own phase. In that case, some of the
-module specific handlers may be put into that phase. The handlers added to
-the system predefined phases (global handlers) are invoked for every message
-that comes to or goes out from the system. The handlers in the module
-specific phase are invoked only for the messages invoking the operations that
-engage that module. Engaging a module means correctly adding the handlers of
-a particular module to one or more phases. Once the module is engaged, the
-handlers and the operations defined in the module are added to the entity
-that engaged them.</p>
-
-<p>Before engaging a module, the following steps have to be followed.</p>
-<ol>
- <li>Write the module.xml file</li>
- <li>Package the module libraries and the module.xml into a folder which has
- the same name as the module</li>
- <li>Deploy the folder in AXIS2C_INSTALL_DIR/modules</li>
- <li>Add the module specific phases in the axis2.xml file</li>
-</ol>
-
-<p>The following is an example of engaging a sample module called the logging
-module with Axis2/C:</p>
-
-<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 have to be specified. Below is the module.xml file of
-the sample logging module.</p>
-<pre> <module name="logging" class="axis2_mod_log">
- <inflow>
- <handler name="LoggingInHandler" class="axis2_mod_log">
- <order phase="PreDispatch"/>
- </handler>
- </inflow>
- <outflow>
- <handler name="LoggingOutHandler" class="axis2_mod_log">
- <order phase="MessageOut"/>
- </handler>
- </outflow>
- <Outfaultflow>
- <handler name="LoggingOutHandler" class="axis2_mod_log">
- <order phase="MessageOut"/>
- </handler>
- </Outfaultflow>
- </module></pre>
-
-<p>In the above shown module configuration file, the name of the module is
-logging. There are two handlers in this module, the LoggingInHandler and the
-LoggingOutHandler. The LoggingInHandler is placed into the PreDispatch phase
-of the in flow. The LoggingOutHandler is placed into the MessageOut phase of
-both the out flow and the fault out flow.</p>
-
-<h3>Packaging and Deploying the Module</h3>
-
-<p>The above module.xml file should be copied to a folder named "logging"
-(because the module name is "logging") inside the AXIS2C_INSTALL_DIR/modules
-folder. The module libraries containing the handler implementation should
-also be copied to the same folder. According to the module.xml file shown
-above, the name of the shared library file should be libaxis2_mod_log.so on
-Linux and axis2_mod_log.dll on MS Windows.</p>
-
-<h3>Adding Module Specific Phases to the axis2.xml File</h3>
-
-<p>Module specific phases have to be added after the system predefined
-phases. The following example shows where to add the module specific phases.
-Look for the <code>phaseOrder</code> elements in the axis2.xml file. Note the
-comment lines:</p>
-<pre> <!-- User defined phases could be added here --></pre>
-You can add user defined phases after the above comment line into any of the
-flows. The <code>type</code> attribute of the <code>phaseOrder</code> element
-indicates the flow.
-
-<p>For the logging module example, user defined phases are not required. All
-the module specific handlers are added to system predefined phases as
-specified in the module.xml file.</p>
-
-<h3>Engaging a Module to a Services</h3>
-
-<p>The following is an example of engaging the logging module to the echo
-service. This can be done by simply adding <code><module ref
-="logging"/></code> in the services.xml file of the echo service. This
-informs the Axis2/C engine that the module "logging" should be engaged for
-this service. The handlers inside the module will be executed in their
-respective phases as described by the module.xml.</p>
-<pre> <service name="echo">
- <module ref ="logging"/>
- <parameter name="ServiceClass" locked="xsd:false">echo</parameter>
- <description>
- This is a testing service, to test if the system is working or not.
- </description>
- <operation name="echoString">
- <!--messageReceiver class="axis2_receivers" /-->
- <parameter name="wsamapping" >
- http://ws.apache.org/axis2/c/samples/echoString
- </parameter>
- </operation>
- </service></pre>
-
-<p>One important thing to note here is that because the logging module's
-handlers are placed into the global phases, even though the logging module is
-engaged only to the echo service, the module will be engaged globally. This
-is a feature of the Axis2 architecture, not a bug. When invoked, the handlers
-in a module can check whether the module has been engaged to a particular
-service, and act accordingly.</p>
-
-<h3>Engaging a Module Globally</h3>
-
-<p>If we want to engage a module for every service deployed in the Axis2/C
-system, we can add the <code><module ref ="logging"/></code> entry in
-the axis2.xml file. This will inform the Axis2/C engine to invoke the
-handlers associated with the module for every message coming in or going out
-for all the services deployed.</p>
-
-<h3>Engaging a Module on the Client Side</h3>
-
-<p>On the client side, if <code><module ref ="logging"/></code> is
-added in the axis2.xml, the handlers specific to the logging module will be
-invoked for every request the client sends and every response the client
-receives. 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>
-<pre>axis2_svc_client_engage_module(svc_client, env, "module-name");</pre>
-
-<p>Remember to replace "module-name" with the name of the module you want to
-engage. For example to engage the logging module you can use:</p>
-<pre>axis2_svc_client_engage_module(svc_client, env, "logging");</pre>
-<a name="ws_addressing"></a>
-
-<h1>8. WS-Addressing</h1>
-
-<p><a href="http://www.w3.org/2002/ws/addr/">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/">version
-1.0</a> as well as the <a
-href="http://www.w3.org/Submission/ws-addressing/">submission version</a>.</p>
-
-<p>WS-Addressing is implemented as a module in Axis2/C. Hence as explained in
-the previous section, the addressing module can be engaged both on the client
-side as well as on the server side.</p>
-
-<p>The WS-Addressing module can be globally engaged by adding the
-<code><module ref="addressing"/></code> line to the axis2.xml file.</p>
-
-<p>The WS-Addressing module can also be programmatically engaged using the
-following line of code with the service client API <br>
-</p>
-<pre>axis2_svc_client_engage_module(svc_client, env, AXIS2_MODULE_ADDRESSING);</pre>
-
-<p>WS-Addressing related options can be set using the
-<code>axis2_options</code> struct instance on the client side. If the
-addressing module is engaged, there are no options to be set on the server
-side. The server will employ WS-Addressing if the incoming requests have
-WS-Addressing headers.</p>
-
-<p>There is a mandatory requirement for using WS-Addressing on the client
-side with Axis2/C. That is to set a WS-Addressing action that represents the
-operation to be invoked. Example:</p>
-<pre>axis2_options_set_action(options,env,"http://ws.apache.org/axis2/c/samples/echoString")</pre>
-
-<p>In addition to the action, which is mandatory, there are other
-WS-Addressing related headers that can be sent in a message. Axis2/C supports
-to set those headers as options at the client level. The following functions
-are used to set them.</p>
-<pre>axis2_options_set_reply_to(options, env, reply_to)</pre>
-
-<p>Sets the <code>wsa:ReplyTo</code> header. The ReplyTo header contains the
-endpoint to send reply messages. The ReplyTo header is required when the
-response comes in a separate channel (when using a dual channel).</p>
-<pre>axis2_options_set_fault_to(options, env, fault_to)</pre>
-
-<p>Sets the <code>wsa:FaultTo</code> header. This contains the endpoint to
-direct fault messages.</p>
-<pre>axis2_options_set_from(options, env, from)</pre>
-
-<p>Sometimes the receiving endpoint requires to know the original sender of
-the message. The <code>wsa:From</code> header is used in such cases. The
-above function sets the From header.</p>
-<pre>axis2_options_set_relates_to(options, env, relates_to)</pre>
-
-<p>Sets the <code>wsa:RelatesTo</code> header. This header contains a unique
-ID which is the message ID of a previously exchanged message. It helps to
-identify a previous message that relates to the current message.</p>
-<a name="writing_module"></a>
-
-<h1>9. Writing a Module</h1>
-
-<p>A module is an extension point in the Axis2/C engine. Modules are
-primarily used to WS-* specifications. In other words, quality of service
-aspects such as security and reliable messaging can be implemented as modules
-and deployed with the Axis2/C engine. <br>
-A SOAP message can 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. There are two interfaces that are important
-when writing a module. They are <code>axis2_module</code> and
-<code>axis2_handler<code>.</code></code></p>
-
-<p>Every module should have three basic functions that are defined as
-function pointer members of the <code>axis2_module_ops</code> struct. This
-struct is defined in the <code>axis2_module.h</code> header file.</p>
-<ol>
- <li><pre>axis2_status_t (AXIS2_CALL *
- init)(axis2_module_t *module, const
- axutil_env_t *env,
- axis2_conf_ctx_t *conf_ctx,
- axis2_module_desc_t *module_desc)</pre>
- <p>This function takes care of the module initialization.</p>
- </li>
- <li><pre>axis2_status_t (AXIS2_CALL *
- shutdown)(axis2_module_t *module,
- const axutil_env_t *env )</pre>
- <p>Shuts down and cleans up the module.</p>
- </li>
- <li><pre>axis2_status_t (AXIS2_CALL *
- fill_handler_create_func_map)(axis2_module_t *module,
- const axutil_env_t *env )</pre>
- <p>This function fills the hash map of the handler create functions for
- the module.</p>
- </li>
-</ol>
-
-<p>The module developer has to implement functions with the above signatures
-and assign them to the members of an <code>axis2_module_ops</code> struct
-instance. Then that struct instance has to be assigned to the ops member of
-an <code>axis2_module</code> struct instance.</p>
-
-<p><a href="mod_log/mod_log.c.html">mod_log.c</a> has the source for the
-logging module. Please have a look at the <code>axis2_mod_log_create</code>
-function in it to see how an <code>axis2_module</code> instance is allocated
-and how the ops are initialized.</p>
-
-<p>The<code> axis2_mod_log_fill_handler_create_func_map</code> function adds
-the handler create functions to the module's hash map, which stores the
-handler create functions. In the <a
-href="mod_log/mod_log.c.html">mod_log.c</a> example, the logging module adds
-two handlers. The in handler and the out handler that deals with logging
-along with the in-flow and out-flow respectively.</p>
-
-<h3>Writing Handlers</h3>
-
-<p>A handler is the smallest unit of execution in the Axis2/C engine's
-execution flow. The engine can 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 <code>axis2_handler</code>,
-which is to be implemented by all the handlers.</p>
-
-<p><a href="mod_log/log_in_handler.c.html">log_in_handler.c</a> contains the
-source code of the in-handler of the logging module. Please have a look at
-the <code>axutil_log_in_handler_create</code> function to see how an
-<code>axis2_handler</code> instance is created and how the invoke function
-implementation, <code>axis2_log_in_handler_invoke</code> is assigned to the
-<code>axis2_handler</code> invoke function pointer. The invoke is called to
-do the actual work assigned to the handler. The phase that owns the handler
-is responsible for calling the invoke function of the handler.</p>
-
-<p><a href="mod_log/log_out_handler.c.html">log_out_handler.c</a> contains
-the source code of the out handler of the logging module. The implementation
-is similar to the in handler, except that it is placed along the out-flow
-when deployed.</p>
-
-<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. Please see the sample <a href="mod_log/module.xml">module.xml</a>
-file for the logging module.</p>
-
-<p>Please see the <a href="#engaging_module">Engaging a Module</a> section
-for more details on how to package and deploy the module.</p>
-<a name="simple_axis_server"></a>
-
-<h1>10. Simple Axis Server</h1>
-
-<p>Simple axis server is the inbuilt HTTP server of Axis2/C.<br>
-</p>
-
-<p>Synopsis :</p>
-<pre> axis2_http_server [-p PORT] [-t TIMEOUT] [-r REPO_PATH][-l LOG_LEVEL] [-f LOG_FILE]</pre>
-
-<p>You can use the following options with simple axis server.</p>
-<pre> -p PORT port number to use, default port is 9090
- -r REPO_PATH repository path, default is ../
- -t TIMEOUT socket read timeout, default is 30 seconds
- -l LOG_LEVEL log level, available log levels:
- 0 - critical 1 - errors 2 - warnings
- 3 - information 4 - debug 5- trace
- Default log level is 4(debug).
- -f LOG_FILE log file, default is $AXIS2C_HOME/logs/axis2.log
- or axis2.log in current folder if AXIS2C_HOME not set
- -h display this help screen.</pre>
-
-<p>Example :</p>
-<pre> axis2_http_server -l 3 -p 8080 -r $AXIS2C_HOME -f /dev/stderr</pre>
-<a name="mod_axis2"></a>
-
-<h1>11. Deploying with Apache HTTP Server Version 2.x</h1>
-
-<h3>Linux Platform</h3>
-
-<p>To build Axis2/C with the Apache HTTP server module, also called
-mod_axis2, you need to provide the following configuration options on the
-Linux platform:</p>
-<pre>./configure --with-apache2=[path to Apache2 include directory] [other configure options]</pre>
-
-<p><font color="#666666">NOTE: Some Apache2 distributions, specially
-development versions, install APR (Apache Portable Run-time) include files in
-a separate location. In that case, to build mod_axis2, use:</font></p>
-<pre>./configure --with-apache2=[path to Apache2 include directory] --with-apr=[path to APR include directory]
- [other configure options]</pre>
-
-<p>Then build the source tree as usual using:</p>
-<pre> make
- make install</pre>
-
-<p>This will install mod_axis2.so into your AXIS2C_INSTALL_DIR/lib folder.</p>
-
-<h3>MS Windows Platform</h3>
-
-<p>On the MS Windows platform, you have to provide the Apache2 install
-location in the configure.in file with the setting APACHE_BIN_DIR.
-Example:</p>
-<pre>APACHE_BIN_DIR = "C:\Program Files\Apache Software Foundation\Apache2.2"</pre>
-
-<p>Based on the Apache HTTP server version you are using, you also need to
-set the setting APACHE_VERSION_IS_2_0_59 in the configure.in file. If you are
-using Apache version 2.0.59, this setting should be set to 1, if the version
-is above that, the setting should be 0. Example:</p>
-<pre>APACHE_VERSION_IS_2_0_59 = 0</pre>
-
-<p>To build the source, you have to run the command </p>
-<pre>nmake axis2_apache_module</pre>
-This will build mod_axis2.dll and copy it to AXIS2C_INSTALL_DIR\lib directory.
-
-<h3>Deploying mod_axis2</h3>
-
-<p><font color="#666666">NOTE: To execute some of the commands given below,
-you might require super user privileges on your machine.</font></p>
-
-<p>Copy the mod_axis2 shared library <font
-color="#4169E1">(libmod_axis2.so.0.0.0 on Linux and mod_axis2.dll on MS
-Windows)</font> to the Apache2 modules directory as mod_axis2.so</p>
-
-<p>On Linux</p>
-<pre> cp $AXIS2C_HOME/lib/libmod_axis2.so.0.0.0
- /usr/lib/apache2/modules/mod_axis2.so</pre>
-On MS Windows
-<pre> copy C:\axis2c\build\deploy\lib\mod_axis2.dll
- C:\Apache2\modules\mod_axis2.so</pre>
-
-<p>Edit the Apache2's configuration file (generally httpd.conf) and add the
-following directives at the end of the file.</p>
-<pre>LoadModule axis2_module MOD_AXIS2_INSTALL_DIR
-Axis2RepoPath AXIS2C_INSTALL_DIR
-Axis2LogFile PATH_TO_LOG_FILE
-Axis2LogLevel LOG_LEVEL
-<Location /axis2>
- SetHandler axis2_module
-</Location></pre>
-
-<p>Please note that you have to fine tune the above settings to mach your
-system.<br>
-<br>
-MOD_AXIS2_INSTALL_DIR has to be replaced with the full path to mod_axis2.so,
-for example, /usr/lib/apache2/modules/mod_axis2.so <br>
-<br>
-AXIS2C_INSTALL_DIR has to be replaced with the full path to Axis2/C
-repository, for example, /usr/local/axis2. Note that repository path should
-have read access to the daemon user account under which the Apache2 HTTPD
-process is run.<br>
-<br>
-PATH_TO_LOG_FILE has to be replaced with the full path to where you wish to
-have the Axis2/C log file, for example, /tmp/axis2.log. Note that the log
-file path should have write access to the daemon user account under which the
-Apache2 HTTPD process is run.<br>
-<br>
-LOG_LEVEL has to be replaced with one of the following values: crit, error,
-warn, info, debug, trace. These log levels have the following meanings:</p>
-<ul>
- <li>crit - log critical errors</li>
- <li>error - log errors and above</li>
- <li>warn - log warnings and above</li>
- <li>info - log information and above</li>
- <li>debug - log debug information and above, this is the default log level
- used</li>
- <li>trace - log trace messages and above</li>
-</ul>
-
-<p>To ensure that everything works fine, start Apache2 (restart if it is
-already running) and test whether the mod_axis2 module is loaded correctly by
-accessing the URL: <a
-href="http://localhost/axis2/services">http://localhost/axis2/services</a>.<br>
-</p>
-
-<p>This should show the list of services deployed with Axis2/C. Then you
-should be able to run clients against this endpoint. Example:</p>
-<pre>echo http://localhost/axis2/services/echo</pre>
-
-<p>In case things are not working as expected, here are some tips on how to
-troubleshoot:</p>
-<ul>
- <li>Double check the steps you followed in installing and configuring
- mod_axis2. Check if the locations given in httpd.conf are correct, and
- also check the folder permissions.</li>
- <li>Have a look at the axis2.log file for clues as to what is going wrong.
- You can set the log level to debug or trace to gather more
- information</li>
- <li>In case the axis2.log file is not written at all, there is a good
- chance that mod_axis2 is crashing. You can have a look at the error.log
- file of Apache2 to get an idea on what is going wrong. This file is
- usually placed in the AXIS2C_INSTALL_DIR/logs folder.</li>
-</ul>
-
-<h1><a name="ssl_client">12. How to Configure the IIS module for
-Axis2C</a></h1>
-
-<p><a name="ssl_client">Use the Axis2C vc project or makefile to buid the
-component.</a></p>
-
-<p><a name="ssl_client">In this document I assume that the mod_axis2_IIS.dll
-is in the directory </a><a name="ssl_client1"
-id="ssl_client1"><code>c:\axis2c\lib\mod_axis2_IIS.dll</code> and axis2c_home
-is <code>c:\axis2c</code></a></p>
-
-<p><a name="ssl_client2" id="ssl_client2">Add the following key to the
-registery.</a></p>
-
-<p><a name="ssl_client">HKEY_LOCAL_MACHINE\SOFTWARE\Apache Axis2c\IIS ISAPI
-Redirector</a></p>
-
-<p><a name="ssl_client">Add a string value with the name axis2c_home and a
-value of c:\axis2c</a></p>
-
-<p><a name="ssl_client">Add a string value with the name log_file and a value
-of c:\axis2c\logs\axis2.log</a></p>
-
-<p><a name="ssl_client">Add a string value with the name log_level. The value
-can be either trace, error, info, critical, debug, or warning.</a></p>
-
-<p><a name="ssl_client">Using the IIS management console, add a new virtual
-directory to your IIS/PWS web site. </a><a name="ssl_client3"
-id="ssl_client3">The name of the virtual directory must be axis2. Its
-physical path should be the directory </a><a name="ssl_client4"
-id="ssl_client4">in which you placed mod_axis2_IIS.dll (in our example it is
-c:\axis2c\lib). When creating this new </a><a name="ssl_client5"
-id="ssl_client5">virtual directory, assign execute access to it.</a></p>
-
-<p><a name="ssl_client">By using the IIS management console, add
-mod_axis2_IIS.dll as a filter in your IIS/PWS web site.</a></p>
-
-<p><a name="ssl_client"></a></p>
-
-<h1>13. Using SSL Client</h1>
-
-<h2>Building and Configuring the Client</h2>
-
-<p>In order to allow an Axis2/C client to communicate with an SSL enabled
-server, we need to compile Axis2/C with SSL support enabled.</p>
-
-<p>To build with SSL client support, first of all, make sure you have
-installed <a href="http://www.openssl.org/">OpenSSL</a> on your machine. Then
-you can start building with SSL client support. This can be achieved on Linux
-by configuring Axis2/C with the <code>--enable-openssl=yes</code> option.</p>
-
-<p>Example <code><br>
-%./configure --enable-openssl=yes --prefix=${AXIS2C_HOME}/deploy<br>
-%make<br>
-%make install<br>
-</code></p>
-
-<p>On MS Windows, set <code>ENABLE_SSL=1</code> in the
-<code>configure.in</code> file and run the 'nmake all' command.</p>
-<a name="client_chain"></a>
-
-<h3>Creating the Client Certificate Chain File</h3>
-
-<p>If you need SSL client authentication, Axis2/C requires you to provide the
-client certificate and the private key file in a single file. Such a file
-which contains both the certificate and relevant private key is called a
-certificate chain file. Creating such a file is very easy. Assume that the
-client certificate is stored in a file named <code>client.crt</code> and the
-private key is stored in a file named <code>client.key</code>. Then the
-certificate chain file can be created by concatenating the certificate file
-and the private key file in that order, in to another file, say
-<code>client.pem</code>.</p>
-
-<p>On Linux you can do this as follows: <code>%cat client.crt client.key >
-client.pem</code></p>
-
-<p>On MS Windows, you can do this by copying the contents of client.crt and
-client.key files and saving them in a file named client.pem using Notepad.</p>
-
-<h3>Configuration</h3>
-
-<p>Uncomment the following in the <code>axis2.xml</code> file. This will
-enable the SSL transport for Axis2/C, by recognizing "https" in an end point
-reference (EPR).</p>
-<pre><transportSender name="https" class="axis2_http_sender">
- <parameter name="PROTOCOL" locked="false">HTTP/1.1</parameter>
-</transportSender></pre>
-
-<p>For the SSL client to work, the file containing the CA certificate should
-be given as <code>SERVER_CERT</code> parameter in the axis2.xml file. If you
-need client authentication, you can also set the parameters in the axis2.xml
-file to specify the client certificate, private key, and the passphrase for
-the client private key. Parameter names for these are:</p>
-
-<p><code>KEY_FILE</code> - certificate chain file containing the client's
-certificate and the private key (Please refer to the <a
-href="#client_chain">creating the client certificate chain file</a>
-section)<br>
-<code>SSL_PASSPHRASE</code> - passphrase used to encrypt the private key
-file.</p>
-
-<p>Example:</p>
-
-<p><code><parameter
-name="SERVER_CERT">/path/to/ca/certificate</parameter></code><br>
-<code><parameter
-name="KEY_FILE">/path/to/client/certificate/chain/file</parameter></code><br>
-<code><</code><code><code>parameter
-name="SSL_</code>PASSPHRASE">passphrase</parameter></code></p>
-
-<p>For testing purposes, you can use the server's certificate instead of the
-CA certificate. You can obtain this by running the command <code>openssl
-s_client -connect <servername>:<port></code> and copying the
-portion of the output bounded by and including:</p>
-<pre>-----BEGIN CERTIFICATE-----
------END CERTIFICATE-----</pre>
-
-<p>On Linux, if you run the following piece of code, the server certificate
-will be saved to a file <code>cert.pem</code>:</p>
-<pre>echo |\
-openssl s_client -connect <servername>:<port> 2>&1 |\
-sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > cert.pem</pre>
-
-<p>NOTE: Instead of setting these parameters in the <code>axis2.xml</code>
-file, you can also set these parameters programmatically in your client
-code.</p>
-
-<h3>Configuring the Server</h3>
-
-<p>Here we will only look at the configuration of the Apache HTTP Web server.
-Refer to the Axis2/C <a
-href="http://ws.apache.org/axis2/c/docs/installationguide.html#installing-apache2">
-installation guide</a> for information on deploying Axis2/C as an Apache
-module.</p>
-
-<p>For more detailed information on SSL configuration, please refer to <a
-href="http://httpd.apache.org/docs/2.0/ssl/#documentation">Apache2 SSL/TLS
-documentation</a>.</p>
-
-<p>In the <code>httpd.conf</code> file, add the following configuration
-statements (in addition to other necessary configuration):</p>
-
-<p><code>SSLEngine on<br>
-SSLCertificateFile /path/to/server/certificate/file<br>
-SSLCertificateKeyFile /path/to/private/key/file<br>
-SSLCACertificateFile /path/to/CA/certificate/file<br>
-SSLVerifyClient require<br>
-SSLVerifyDepth 1</code></p>
-
-<p>NOTE: The last two lines, <code>SSLVerifyClient</code> and
-<code>SSLVerifyDepth</code> are only needed when you need client
-authentication.</p>
-<a name="proxy"></a>
-
-<h1>14. Using Proxy Support</h1>
-
-<p>When using a proxy, there are two methods for specifying proxy
-settings:</p>
-<ol>
- <li>Specify proxy settings in axis2.xml</li>
- <li>Provide proxy settings using service client API</il></li>
-</ol>
-
-<h3>Specifying Proxy Settings in axis2.xml</h3>
-<pre><transportSender name="http" class="axis2_http_sender">
- <parameter name="PROTOCOL" locked="false">HTTP/1.1</parameter>
- <parameter name="PROXY" proxy_host="127.0.0.1" proxy_port="8080" locked="true"/>
-</transportSender></pre>
-
-<h3>Providing Proxy Settings Using Service Client API</h3>
-
-<p>You can specify proxy settings using the following function with the
-service client:</p>
-<pre>axis2_svc_client_set_proxy(axis2_svc_client_t *svc_client,
- const axutil_env_t *env,
- axis2_char_t *proxy_host,
- axis2_char_t *proxy_port);</pre>
-<a name="wsdl2c"></a>
-
-<h1>15. WSDL2C Tool</h1>
-
-<p>WSDL2C tool that comes with Axis2/Java supports the generation of Axis2/C
-stubs and skeletons for WSDL files. This is a Java tool that can be used to
-generate C code that works with Axis2/C API. You should use <a
-href="http://svn.apache.org/viewvc/webservices/axis2/trunk/java">Axis2/Java
-SVN</a> revision 529533 or later revisions. You can download the <a
-href="http://people.apache.org/dist/axis2/nightly/">Axis2/Java nightly
-build</a> and use those binaries to generate code. Check out a <a
-href="http://ws.apache.org/axis2/1_2/reference.html#wsdl2java">basic
-guide</a> on the Java tool. </p>
-
-<p>Before you run the tool, make sure that all the .jar library files that
-come with Axis2/Java are added to the CLASSPATH environment variable.</p>
-
-<h2>Generating Service Skeletons</h2>
-
-<p>The tool can be run with the following parameters and generate the service
-skeleton and other required files with ADB (Axis Data Binding) support.</p>
-<pre>java org.apache.axis2.wsdl.WSDL2C -uri interoptestdoclitparameters.wsdl -ss -sd -d adb -u </pre>
-
-<p>To understand the meanings of the options used with the tool, please have
-a look at the <a
-href="http://ws.apache.org/axis2/1_2/reference.html#wsdl2java"> Java tool
-documentation</a>.</p>
-
-<p>If you need an XML in/out programming model, you can just ignore the data
-binding support. To generate code with no data binding support, just replace
-<code>-d adb -u</code>, that was used in a previous command, with <code>-d
-none</code>.</p>
-<pre>java org.apache.axis2.wsdl.WSDL2C -uri interoptestdoclitparameters.wsdl -ss -sd -d none</pre>
-
-<p>The WSDL file, <code>interoptestdoclitparameters.wsdl</code>, used in the
-above command examples can be found in <axis2_src_dir>/test/resources
-directory.</p>
-
-<p>Once the code is generated, you have to implement the business logic for
-the service. For this, locate the skeleton source file from the generated
-files. To identify the locations where you can place your business logic in
-line with the operations defined in the WSDL file that you used to generate
-code, look for the comment lines:</p>
-<pre>/* Todo fill this with the necessary business logic */</pre>
-You can also go through the generated header files and understand the API in
-line with the WSDL file that you used to generate the code.
-
-<h2>Generating Client Stubs</h2>
-
-<p>The WSDL2C code generator tool provides support for generating client
-stubs as well. You can generate the required stubs from a given WSDL with the
-other supporting files. Use following parameters to generate the Axis2/C
-client stub code with ADB support.</p>
-<pre>java WSDL2C -uri interoptestdoclitparameters.wsdl -d adb -u</pre>
-
-<p>In order to ignore the data binding support and use a raw XML in/out
-model, just use the following parameters.</p>
-<pre>java WSDL2C -uri interoptestdoclitparameters.wsdl -d none</pre>
-
-<p>Like in the case of service skeletons, you have to fill in the business
-logic as required in the client stubs as well. To do this, go through the
-header files generated and understand the API in line with the WSDL file that
-you used to generate the code.</p>
-<a name="appA"></a>
-
-<h1>Appendix A</h1>
-
-<h2 style="margin-bottom: 0in">axis2.xml</h2>
-
-<p>The axis2.xml file is the configuration file for Axis2/C. It has 6 top
-level elements. They are <em>parameter, transportReceiver, transportSender,
-module, phaseOrder</em> and <em>messageReceiver</em>. The following sections
-describe these elements, their sub elements, element attributes, possible
-values, and their purpose.</p>
-
-<p><em><strong>axisconfig</strong></em> is the root element of axis2.xml
-file.</p>
-
-<table border="1">
- <tbody>
- <tr>
- <th>Attribute</th>
- <th>Possible Values</th>
- </tr>
- <tr>
- <td>name</td>
- <td>Axis2/C</td>
- </tr>
- </tbody>
-</table>
-
-<h3><em>parameter</em></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 the root
-element) will be stored as parameters as <code>axis2_conf</code>. Therefore,
-the top level parameters set in the configuration file can be accessed via
-the <code>axis2_conf</code> instance in the running system.</p>
-
-<p>Sub elements :- none</p>
-
-<p>Attributes :- name, locked</p>
-
-<table border="1">
- <caption></caption>
- <tbody>
- <tr>
- <th>Attribute</th>
- <th>Description</th>
- </tr>
- <tr>
- <td>name</td>
- <td>Name of the parameter. The table below shows possible values of the
- name attribute and their description.
-
- <table border="1">
- <caption></caption>
- <tbody>
- <tr>
- <th>Value</th>
- <th>Description</th>
- <th>Possible Text of Parameter Element</th>
- </tr>
- <tr>
- <td>enableMTOM</td>
- <td>Enable MTOM support when sending binary attachments</td>
- <td>true or false</td>
- </tr>
- <tr>
- <td>enableREST</td>
- <td>Enable REST support</td>
- <td>true or false</td>
- </tr>
- </tbody>
- </table>
- </td>
- </tr>
- <tr>
- <td>locked</td>
- <td>Indicates whether the parameter can be changed from the code.
- Following are the possible values for the locked attribute.
-
- <table border="1">
- <caption></caption>
- <tbody>
- <tr>
- <th>Value</th>
- <th>Description</th>
- </tr>
- <tr>
- <td>true</td>
- <td>The parameter cannot be changed from the code</td>
- </tr>
- <tr>
- <td>false</td>
- <td>The parameter can be changed from the code.</td>
- </tr>
- </tbody>
- </table>
- </td>
- </tr>
- </tbody>
-</table>
-
-<h3><em>transportReceiver</em></h3>
-
-<p>This element specifies the transport receiver details in an IN-OUT message
-exchange scenario. The users can change the transport receiver port as they
-wish.</p>
-
-<p>Attributes :- name, class</p>
-
-<table border="1">
- <caption></caption>
- <tbody>
- <tr>
- <th>Attribute</th>
- <th>Description</th>
- <th>Possible Values</th>
- </tr>
- <tr>
- <td>name</td>
- <td>Specifies which transport protocol is used</td>
- <td>http (when using HTTP)</td>
- </tr>
- <tr>
- <td>class</td>
- <td>Specifies the shared library which implements the transport
- interface</td>
- <td>Name of the shared library.
-
- <p>Example:- On Linux if the value is given as <em>foo</em> then
- shared library is libfoo.so.</p>
-
- <p>On MS Windows, <em>foo.dll</em>.</p>
- </td>
- </tr>
- </tbody>
-</table>
-
-<p></p>
-
-<p>Sub elements :- can have zero or more parameter elements.</p>
-
-<p><br>
-The following table shows possible parameter values.</p>
-
-<table border="1">
- <caption></caption>
- <tbody>
- <tr>
- <th>Attribute</th>
- <th>Description</th>
- </tr>
- <tr>
- <td>name</td>
- <td>Name of the parameter.
-
- <table border="1">
- <caption></caption>
- <tbody>
- <tr>
- <th>Value</th>
- <th>Description</th>
- <th>Possible Text of Parameter Element</th>
- </tr>
- <tr>
- <td>port</td>
- <td>Transport listener port</td>
- <td>Integer specifying the port number</td>
- </tr>
- </tbody>
- </table>
- </td>
- </tr>
- <tr>
- <td>locked</td>
- <td>whether the parameter can be changed from the code
-
- <table border="1">
- <caption></caption>
- <tbody>
- <tr>
- <th>Value</th>
- <th>Description</th>
- </tr>
- <tr>
- <td>true</td>
- <td>Parameter cannot be changed from the code</td>
- </tr>
- <tr>
- <td>false</td>
- <td>The parameter can be changed from the code.</td>
- </tr>
- </tbody>
- </table>
- </td>
- </tr>
- </tbody>
-</table>
-
-<p></p>
-
-<p></p>
-
-<h3><em>transportSender</em></h3>
-
-<p>This element specifies the transport senders used to send messages.</p>
-
-<p>Attributes :- name, class</p>
-
-<table border="1">
- <caption></caption>
- <tbody>
- <tr>
- <th>Attribute</th>
- <th>Description</th>
- <th>Possible Values</th>
- </tr>
- <tr>
- <td>name</td>
- <td>Specifies which transport protocol is used when sending
- messages</td>
- <td>http(when using http)</td>
- </tr>
- <tr>
- <td>class</td>
- <td>Specifies the shared library which implements the transport
- interface</td>
- <td><p>Name of the shared library.</p>
-
- <p>Example:- On Linux if the value is given as <em>foo</em> then the
- shared library is libfoo.so.</p>
-
- <p>On MS Windows, <em>foo.dll</em>.</p>
- </td>
- </tr>
- </tbody>
-</table>
-
-<p></p>
-
-<p>Sub elements : can have zero or more parameter elements.</p>
-
-<p><br>
-The following table shows possible parameter values.</p>
-
-<table border="1">
- <caption></caption>
- <tbody>
- <tr>
- <th>Attribute</th>
- <th>Description</th>
- </tr>
- <tr>
- <td>name</td>
- <td>The name of the parameter.
-
- <table border="1">
- <caption></caption>
- <tbody>
- <tr>
- <th>Value</th>
- <th>Description</th>
- <th>Possible text of parameter element</th>
- </tr>
- <tr>
- <td>PROTOCOL</td>
- <td>Transport protocol used</td>
- <td>Protocol version. Example:- HTTP /1.1, HTTP/1.0</td>
- </tr>
- </tbody>
- </table>
- </td>
- </tr>
- <tr>
- <td>locked</td>
- <td>Indicates whether the parameter can be changed from the code.
-
- <table border="1">
- <caption></caption>
- <tbody>
- <tr>
- <th>Value</th>
- <th>Description</th>
- </tr>
- <tr>
- <td>true</td>
- <td>The parameter cannot be changed from the code</td>
- </tr>
- <tr>
- <td>false</td>
- <td>The parameter can be changed from the code.</td>
- </tr>
- </tbody>
- </table>
- </td>
- </tr>
- </tbody>
-</table>
-
-<p></p>
-
-<h3><em>module</em></h3>
-
-<p>This element is optional. It is used when a particular module needs to be
-engaged globally for every service deployed with Axis2/C.</p>
-
-<table border="1">
- <caption></caption>
- <tbody>
- <tr>
- <th>Attributes</th>
- <th>Description</th>
- <th>Possible Values</th>
- </tr>
- <tr>
- <td>ref</td>
- <td>The name of the module which is to be engaged globally.</td>
- <td>Name of the module.
-
- <p>Example : addressing</p>
- </td>
- </tr>
- </tbody>
-</table>
-
-<p></p>
-
-<h3><em>phaseOrder</em></h3>
-
-<p>The order of phases in a particular execution chain has to be configured
-using phaseOrder element.</p>
-
-<table border="1">
- <caption></caption>
- <tbody>
- <tr>
- <th>Attribute</th>
- <th>Description</th>
- <th>Possible Values</th>
- </tr>
- <tr>
- <td>type</td>
- <td>The flow to which the phase belongs </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 is invoked for a particular
-message. The types of flows are described below.</p>
-
-<table border="1">
- <caption></caption>
- <tbody>
- <tr>
- <th>Flow</th>
- <th>Description</th>
- </tr>
- <tr>
- <td>inflow</td>
- <td>Collection of handlers invoked for a message coming in to the
- system.</td>
- </tr>
- <tr>
- <td>outflow</td>
- <td>Collection of handlers invoked for a message going out of the
- system.</td>
- </tr>
- <tr>
- <td>INfaultflow</td>
- <td>Collection of handlers invoked for an incoming fault message.</td>
- </tr>
- <tr>
- <td>Outfaultflow</td>
- <td>Collection of handlers invoked for an outgoing fault message.</td>
- </tr>
- </tbody>
-</table>
-
-<p>Sub elements : <em>phase</em>: represents the available phases in the
-execution chain</p>
-
-<p>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 border="1">
- <caption></caption>
- <tbody>
- <tr>
- <th>Attribute</th>
- <th>Description</th>
- <th>Possible Values</th>
- </tr>
- <tr>
- <td>name</td>
- <td>Specifies the name of the phase</td>
- <td>TransportIn, Dispatch, PreDispatch, PostDispatch, MessageOut
-
- <p>User defined phases (can have a user defined name)</p>
- </td>
- </tr>
- </tbody>
-</table>
-
-<p>Sub elements of phase element: <em>handler</em></p>
-
-<table border="1">
- <caption></caption>
- <tbody>
- <tr>
- <th>Attribute</th>
- <th>Description</th>
- <th>Possible Values</th>
- </tr>
- <tr>
- <td>name</td>
- <td>Specifies the handler name. Phase may contain zero or more
- handlers.</td>
- <td>Based on the handler name.
-
- <p>Example: AddressingbasedDispatcher, RequestURIbaseddispatcher</p>
- </td>
- </tr>
- <tr>
- <td>class</td>
- <td>Specifies the shared library which implements the handler</td>
- <td><p>Name of the shared library.</p>
-
- <p>Example: On Linux, if the value is given as <em>foo,</em> then the
- shared library is libfoo.so.</p>
-
- <p>On MS Windows, <em>foo.dll</em>.</p>
- </td>
- </tr>
- </tbody>
-</table>
-
-<h3><em>messageReceiver</em></h3>
-
-<p></p>
-
-<table border="1">
- <caption></caption>
- <tbody>
- <tr>
- <th>Attribute</th>
- <th>Description</th>
- <th>Possible Values</th>
- </tr>
- <tr>
- <td>mep</td>
- <td>Message Exchange Pattern</td>
- <td>IN-OUT, IN-ONLY</td>
- </tr>
- <tr>
- <td>class</td>
- <td>Specify the shared library which implements the transport interface.
-
- <p>If not specified, the Axis2/C default message receiver is used.</p>
- </td>
- <td>Name of the shared library.
-
- <p>Example: On Linux, if the value is given as <em>foo,</em> then the
- shared library is libfoo.so.</p>
-
- <p>On MS Windows, <em>foo.dll</em>.</p>
- </td>
- </tr>
- </tbody>
-</table>
-<a name="appB"></a>
-
-<h1>Appendix B</h1>
-
-<h2 style="margin-bottom: 0in">services.xml</h2>
-
-<p>Configuration of a service is specified using a services.xml. Each service
-or service archive file needs to have a services.xml in order to be a valid
-service. The following sections describe the elements of the services.xml
-file.</p>
-
-<p>If services.xml describes a single service, the root element is
-<em>service</em>. If it is describing a service group, then the root element
-is <em>serviceGroup</em>. The<em> service</em> element will be a child
-element of serviceGroup if there are multiple services specified in
-services.xml.</p>
-
-<h3><em><strong>service / serviceGroup</strong></em></h3>
-
-<table border="1">
- <caption></caption>
- <tbody>
- <tr>
- <th>Attributes</th>
- <th>Description</th>
- <th>Possible Values</th>
- </tr>
- <tr>
- <td>name</td>
- <td>Name of the service or service group.</td>
- <td>Depends on the service or the service group.<br>
- Examples: echo, sg_math</td>
- </tr>
- </tbody>
-</table>
-
-<p></p>
-
-<h3><strong><em>description</em></strong></h3>
-
-<p>This is optional. This element can be used to describe the service in a
-human readable format.</p>
-
-<p></p>
-
-<h3><em><strong>module</strong></em></h3>
-
-<p>This is optional. Can be used to engage modules at service level.</p>
-
-<table border="1">
- <caption></caption>
- <tbody>
- <tr>
- <th>Attributes</th>
- <th>Description</th>
- <th>Possible Values</th>
- </tr>
- <tr>
- <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>
-
-<h3><em><strong>parameter</strong></em></h3>
-
-<p>The service element can have any number of parameters as sub elements.</p>
-
-<table border="1">
- <caption></caption>
- <tbody>
- <tr>
- <th>Attributes</th>
- <th>Description</th>
- <th>Possible Values</th>
- <th>Value of the Text in the Parameter Element</th>
- </tr>
- <tr>
- <td>name</td>
- <td>Specifies the name of the shared library that holds the service
- implementation</td>
- <td>serviceClass</td>
- <td>the service name. Example: echo</td>
- </tr>
- <tr>
- <td>locked</td>
- <td>Indicates whether the parameter can be changed from the code</td>
- <td>true / false</td>
- <td></td>
- </tr>
- </tbody>
-</table>
-
-<p></p>
-
-<h3><em><strong>operation</strong></em></h3>
-
-<p>The operations of the service are specified using operation elements.</p>
-
-<table border="1">
- <caption></caption>
- <tbody>
- <tr>
- <th>Attributes</th>
- <th>Description</th>
- <th>Possible Values</th>
- </tr>
- <tr>
- <td>name</td>
- <td>name of the operation</td>
- <td>Example: echoString</td>
- </tr>
- </tbody>
-</table>
-
-<p>Sub elements of <em>operation</em>: <em>parameter</em> elements can be
-present as sub elements. Zero or more parameters may be present.</p>
-
-<table border="1">
- <caption></caption>
- <tbody>
- <tr>
- <th>Attribute</th>
- <th>Description</th>
- <th>Possible Value</th>
- <th>Parameter Value</th>
- </tr>
- <tr>
- <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>
-
-<h3><em><strong>messageReceiver</strong></em></h3>
-
-<p>An operation specific message receiver is specified from this. This is
-optional.</p>
-
-<table border="1">
- <caption></caption>
- <tbody>
- <tr>
- <th>Attributes</th>
- <th>Description</th>
- <th>Possible Values</th>
- </tr>
- <tr>
- <td>class</td>
- <td>Shared library with the message receiver implementation</td>
- <td>Name of the shared library.
-
- <p>Example: On Linux, if the value is given as <em>foo</em>, then the
- shared library is libfoo.so.</p>
-
- <p>On MS Windows, <em>foo.dll</em>.</p>
- </td>
- </tr>
- </tbody>
-</table>
-<a name="appC"></a>
-
-<h1>Appendix C</h1>
-
-<h2 style="margin-bottom: 0in">module.xml</h2>
-
-<p>The module.xml file provides the configuration details for a particular
-module in Axis2/C. The top level element is <em>module</em>.</p>
-
-<h3><em>module</em></h3>
-
-<table border="1">
- <caption></caption>
- <tbody>
- <tr>
- <th>Attributes</th>
- <th>Description</th>
- <th>Possible Values</th>
- </tr>
- <tr>
- <td>name</td>
- <td>Name of the module</td>
- <td>Example- addressing</td>
- </tr>
- <tr>
- <td>class</td>
- <td>Specifies the shared library which implements the module.</td>
- <td>Name of the shared library.
-
- <p>Example- On Linux, if the value is given as <em>foo</em>, then the
- shared library is libfoo.so.</p>
-
- <p>On MS 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>
-
-<h3><em>parameter</em></h3>
-
-<p>Any number of parameters can be present, depending on the module.</p>
-
-<table border="1">
- <caption></caption>
- <tbody>
- <tr>
- <th>Attributes</th>
- <th>Description</th>
- <th>Possible Values</th>
- </tr>
- <tr>
- <td>name</td>
- <td>Name of the parameter</td>
- <td>Depends on the module</td>
- </tr>
- <tr>
- <td>locked</td>
- <td>Indicates 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>
-
-<h3><em>Description</em></h3>
-
-<p>Describes the behavior of the module. This element is optional and has no
-attributes or sub elements.</p>
-
-<h3><em>inflow</em></h3>
-
-<p>Encapsulates details added to the in-flow by the module. Zero or one
-element is possible and does not have any attributes.</p>
-
-<p>Sub elements of <em>inflow</em> : <em>handler</em>, contains details about
-the module specific handlers added to a particular flow. Zero or more
-handlers can be added.</p>
-
-<table border="1">
- <caption></caption>
- <tbody>
- <tr>
- <th>Attributes</th>
- <th>Description</th>
- <th>Possible Values</th>
- </tr>
- <tr>
- <td>name</td>
- <td>Name of the handler</td>
- <td>Depends on the handlers in the module.</td>
- </tr>
- <tr>
- <td>class</td>
- <td>Specifies the shared library which implements the handler</td>
- <td><p>Name of the shared library.</p>
-
- <p>Example: On Linux, if the value is given as <em>foo,</em> then the
- shared library is libfoo.so.</p>
-
- <p>On MS Windows, <em>foo.dll</em>.</p>
- </td>
- </tr>
- </tbody>
-</table>
-
-<p></p>
-
-<p>sub elements of <em>handler</em> : <em>order</em>, specifies where to put
-a handler in a particular phase.</p>
-
-<table border="1">
- <caption></caption>
- <tbody>
- <tr>
- <th>Attribute</th>
- <th>Description</th>
- <th>Possible Values</th>
- </tr>
- <tr>
- <td>phase</td>
- <td>The name of the phase the handler belongs to</td>
- <td>depends on the handler</td>
- </tr>
- <tr>
- <td>phaseLast</td>
- <td>Indicates that the handler is the last handler of the phase</td>
- <td>true</td>
- </tr>
- <tr>
- <td>phaseFirst</td>
- <td>Indicates that the handler is the first handler of the phase.</td>
- <td>true</td>
- </tr>
- <tr>
- <td>before</td>
- <td>Handler should be invoked before the handler, which is specified by
- the before handler</td>
- <td>handler name</td>
- </tr>
- <tr>
- <td>after</td>
- <td>Handler should be invoked after the handler, which is specified by
- the after handler</td>
- <td>handler name</td>
- </tr>
- </tbody>
-</table>
-
-<p>From the above attributes, phase is compulsory. Given below are
-combinations possible from the other four attributes.</p>
-
-<table border="1">
- <caption></caption>
- <tbody>
- <tr>
- <th>Combination</th>
- <th>Description</th>
- </tr>
- <tr>
- <td>phaseLast</td>
- <td>Indicates that the handler is the last handler of the phase</td>
- </tr>
- <tr>
- <td>phasefirst</td>
- <td>Indicates that the handler is the first handler of the phase.</td>
- </tr>
- <tr>
- <td>before</td>
- <td>Handler should be invoked before the handler, which is specified by
- the before handler</td>
- </tr>
- <tr>
- <td>after</td>
- <td>Handler should be invoked after the handler, which is specified by
- the after handler</td>
- </tr>
- <tr>
- <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><em>outflow</em>, <em>INfaultflow</em>, <em>OUTfaultflow</em> elements
-have the same syntax as that of <em>inflow</em>.</p>
-
-<h3><em>operation</em></h3>
-
-<p>This is used when a module wants to add operations to a service that
-engages the module.</p>
-
-<table border="1">
- <caption></caption>
- <tbody>
- <tr>
- <th>Attributes</th>
- <th>Description</th>
- <th>Possible Values</th>
- </tr>
- <tr>
- <td>name</td>
- <td>Name of the operation (compulsory)</td>
- <td>Depends on the module</td>
- </tr>
- <tr>
- <td>mep</td>
- <td>Message Exchange Pattern</td>
- <td>IN-OUT, IN-ONLY</td>
- </tr>
- </tbody>
-</table>
-
-<p>Sub elements of <em>operation</em> : Any number of parameters can be
-included as sub elements in the operation element.</p>
-
-<p>The <em>messageReceiver</em> parameter specifies the message receiver the
-message is intended for. If it is not set, the default message receiver is
-used.</p>
-
-<p></p>
-<a name="appD"></a>
-
-<h1>Appendix D</h1>
-
-<h2 style="margin-bottom: 0in">axis2_options</h2>
-
-<p>This section describes various types of options that can be set with
-<code>axis2_options</code>. These options are used by the service client
-before sending messages.</p>
-
-<p><strong>axis2_options_set_action(options, env, action)</strong></p>
-
-<p>Sets the WS-Addressing action that is to be set in the addressing SOAP
-headers.</p>
-
-<table border="1">
- <caption></caption>
- <tbody>
- <tr>
- <th>Parameter</th>
- <th>Description</th>
- </tr>
- <tr>
- <td>axis2_options_t *options</td>
- <td>Pointer to the options struct</td>
- </tr>
- <tr>
- <td>const axutil_env_t *env</td>
- <td>Pointer to the environment struct</td>
- </tr>
- <tr>
- <td>const axis2_char_t *action</td>
- <td>Pointer to the action string</td>
- </tr>
- </tbody>
-</table>
-
-<p></p>
-
-<p><strong>axis2_options_set_fault_to(options, env, fault_to)</strong></p>
-
-<p>Sets the end point reference which may receive the message in a case of a
-SOAP fault.</p>
-
-<table border="1">
- <caption></caption>
- <tbody>
- <tr>
- <th>Parameter</th>
- <th>Description</th>
- </tr>
- <tr>
- <td>axis2_options_t *options</td>
- <td>Pointer to the options struct.</td>
- </tr>
- <tr>
- <td>const axutil_env_t *env</td>
- <td>Pointer to the environment struct.</td>
- </tr>
- <tr>
- <td>axis2_endpoint_ref_t *fault_to</td>
- <td>Pointer to the endpoint reference struct representing the 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 message comes. This
-option sets the from endpoint</p>
-
-<table border="1">
[... 3499 lines stripped ...]
---------------------------------------------------------------------
To unsubscribe, e-mail: axis-cvs-unsubscribe@ws.apache.org
For additional commands, e-mail: axis-cvs-help@ws.apache.org