diff options
| author |  gmcdonald | 2010-02-13 01:32:03 +0000 |
|---|---|---|
| committer | gmcdonald | 2010-02-13 01:32:03 +0000 |
| commit | 0425aadc78680e53000fd0108b540d6eca048516 (patch) | |
| tree | 8ec7ab8e015d454c5ec586dfc91e05a2dce1cfc0 /xdocs/docs/axis2c_manual.html | |
| download | axis2c-0425aadc78680e53000fd0108b540d6eca048516.tar.gz axis2c-0425aadc78680e53000fd0108b540d6eca048516.tar.bz2 | |
Moving axis svn, part of TLP move INFRA-2441
git-svn-id: http://svn.apache.org/repos/asf/axis/axis2/c/core/trunk@909681 13f79535-47bb-0310-9956-ffa450edef68
Diffstat (limited to 'xdocs/docs/axis2c_manual.html')
| -rw-r--r-- | xdocs/docs/axis2c_manual.html | 3951 |
1 files changed, 3951 insertions, 0 deletions
diff --git a/xdocs/docs/axis2c_manual.html b/xdocs/docs/axis2c_manual.html new file mode 100644 index 0000000..2b26e55 --- /dev/null +++ b/xdocs/docs/axis2c_manual.html @@ -0,0 +1,3951 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html><head><title>Apache Axis2/C - Manual</title></head> +<body> +<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" class="externalLink" title="External Link">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" class="externalLink" title="External Link">Apache +Axis2/C website</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> +<p style="margin-bottom: 0in;"><br /> +</p> +<div class="section"><a name="Axis2_C_Manual_-_Contents"></a> +<h2>Axis2/C Manual - Contents</h2> +<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="#IIS">Deploying with Microsoft IIS +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="#proxy_auth">Using Proxy +Authentication Support</a></li> +<li><a href="#http_auth">Using HTTP Authentication +Support</a></li> +<li><a href="#wsdl2c">WSDL2C Tool</a></li> +<li><a href="#tcptrans">TCP Transport</a></li> +<li><a href="#amqptrans">AMQP Transport</a></li> +<li><a href="#archive">Archive Based Deployment</a></li> +<li><a href="#tcpmon">TCPMon 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> +<p style="margin-bottom: 0in;"><br /> +</p> +<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 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" class="externalLink" title="External Link">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 samples/bin 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>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> +<div class="subsection"><a name="1_1_Hello_Service"></a> +<h3>1.1 Hello Service</h3> +<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> +<div class="source"> +<pre> <greet><br /> Hello Service!<br /> <greet><br /><br /></pre> +</div> +<p>Response:</p> +<div class="source"> +<pre> <greetResponse><br /> Hello Client!<br /> <greetResponse><br /></pre> +</div> +<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> +</div> +<div class="subsection"><a name="1_1_1_Operation_Implementation"></a> +<h3>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> +</div> +<div class="subsection"><a name="1_1_2_Skeleton_Create_Method"></a> +<h3>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> +</div> +<div class="subsection"><a name="1_1_3_Invoking_Operation_Implementation"></a> +<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> +</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_svc.c.html">hello_svc.c</a></p> +</div> +<div class="subsection"><a name="1_1_5_Service_Descriptor"></a> +<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> +<div class="source"> +<pre><service name="hello"><br /> <parameter name="ServiceClass" locked="xsd:false">hello</parameter><br /> <description><br /> Quick start guide hello service sample.<br /> </description><br /> <operation name="greet"/><br /></service><br /><br /></pre> +</div> +<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> +</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/axis2-1.6.0/ -L$AXIS2C_HOME/lib -laxutil -laxis2_axiom -laxis2_parser -laxis2_engine -lpthread -laxis2_http_sender -laxis2_http_receiver hello_svc.c<br /><br /></pre> +</div> +<p>On MS 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 /I %AXIS2C_HOME%\include /c hello_svc.c<br /><br /></pre> +</div> +<p>to link,</p> +<div class="source"> +<pre>link.exe /nologo /LIBPATH:%AXIS2C_HOME%\lib axutil.lib axiom.lib axis2_parser.lib axis2_engine.lib /DLL /OUT:hello.dll *.obj<br /><br /></pre> +</div> +</div> +<div class="subsection"><a name="1_1_7_Deploying_the_Service"></a> +<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" class="externalLink" title="External Link">http://localhost:9090/axis2/services</a>. +You should get an entry for the hello service on the page that is +displayed.</p> +</div> +<div class="subsection"><a name="1_1_8_Providing_a_WSDL_for_the_Service"></a> +<h3>1.1.8 Providing a WSDL for the Service</h3> +<p>Axis2/C does not support dynamic WSDL generation. However, it +is possible to attach the contract you used to generate the service +skeleton, to the respective service. This can be done in two ways.</p> +<ol> +<li>Adding the WSDL file to the folder in which the service DLL +is found. +</li> +<li>Providing the path of the WSDL file in the services.xml. +</li> +</ol> +<p>If you choose the first option, you will have to copy the WSDL +file to the folder in which the service DLL is found. The name of the +WSDL file should be the name of the service. And, if you choose the +second option, you will have to make use of the <b><code>wsdl_path</code></b> +parameter in the services.xml file. More info on how this can be done +is found under the <a href="#appB">services.xml</a> +section.</p> +<p>An example of the second option can be found the services.xml +of the <b>echo</b> sample service, which is commented. An +example of the first option in use is seen in the <b>Calculator</b> +sample service.</p> +<p>The static WSDL file can be accessed by appending <code>?wsdl</code> +to the service end-point. You can view the WSDL provided for the +Calculator sample, by pointing to <a href="http://localhost:9090/axis2/services/Calculator?wsdl" class="externalLink" title="External Link">http://localhost:9090/axis2/services/Calculator?wsdl</a>.</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, 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> +</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);<br /> address = "http://localhost:9090/axis2/services/hello";<br /> endpoint_ref = axis2_endpoint_ref_create(env, address);<br /> axis2_options_set_to(options, env, endpoint_ref);<br /><br /></pre> +</div> +<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> +</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);<br /> axis2_svc_client_set_options(svc_client, env, options);<br /> payload = build_om_request(env);<br /> ret_node = axis2_svc_client_send_receive(svc_client, env, payload);<br /><br /></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 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> +</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> +</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/axis2-1.6.0/ -L$AXIS2C_HOME/lib -laxutil -laxis2_axiom -laxis2_parser -laxis2_engine -lpthread -laxis2_http_sender -laxis2_http_receiver hello.c -ldl -Wl,--rpath -Wl,$AXIS2C_HOME/lib<br /><br /></pre> +</div> +<p>On MS Windows:</p> +<p>to compile,</p> +<div class="source"> +<pre>cl.exe /nologo /D "WIN32" /D "_WINDOWS" /D "_MBCS" /I %AXIS2C_HOME%\include /c hello.c<br /><br /></pre> +</div> +<p>to link,</p> +<div class="source"> +<pre>link.exe /LIBPATH:%AXIS2C_HOME%\lib axutil.lib axiom.lib axis2_parser.lib axis2_engine.lib /OUT:hello.exe *.obj<br /><br /></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 start the simple axis server +and then run +the hello executable.</p> +<p style="margin-bottom: 0in;"><br /> +</p> +<p><a name="repo_folder"></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 +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" alt="" /> +<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 class="bodyTable"> +<caption>Axis2/C Repository Contents</caption><tbody> +<tr class="b"> +<th>Folder/File Name</th> +<th>Description</th> +</tr> +<tr class="a"> +<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 class="b"> +<td> +<p>modules [optional]</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 class="a"> +<td> +<p>services [optional]</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 class="b"> +<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> +<div class="subsection"><a name="2_1_Module_Folders"></a> +<h3>2.1 Module Folders</h3> +<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> +</div> +<div class="subsection"><a name="2_2_Service_Folders"></a> +<h3>2.2 Service Folders</h3> +<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> +<p style="margin-bottom: 0in;"><br /> +</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 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 class="bodyTable"> +<caption></caption><tbody> +<tr class="a"> +<th>Function Signature</th> +<th>Description</th> +</tr> +<tr class="b"> +<td> +<pre>int (AXIS2_CALL *<br /> init)(axis2_svc_skeleton_t *svc_skeleton,<br /> 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 class="a"> +<td width="410"> +<pre>axiom_node_t *(AXIS2_CALL*<br /> invoke )( axis2_svc_skeleton_t *svc_skeli,<br /> const axutil_env_t *env,<br /> axiom_node_t *node,<br /> 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 class="b"> +<td> +<pre>axiom_node_t *(AXIS2_CALL*<br /> on_fault)(<br /> axis2_svc_skeleton_t *svc_skeli,<br /> const axutil_env_t *env,<br /> axiom_node_t *node);</pre> +</td> +<td>This method is called by the engine if a fault is +detected.</td> +</tr> +<tr class="a"> +<td> +<pre>axis2_status_t (AXIS2_CALL *<br /> free )( axis2_svc_skeleton_t *svc_skeli,<br /> 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> +<table class="bodyTable"> +<caption></caption><tbody> +<tr class="b"> +<th>Function Signature</th> +<th>Description</th> +</tr> +<tr class="a"> +<td> +<pre>AXIS2_EXPORT int<br />axis2_get_instance(<br /> axis2_svc_skeleton_t ** inst,<br /> const axutil_env_t * env);</pre> +</td> +<td>Creates an instance of the service. You have to +implement the logic of creating the service object, allocating memory +etc. in this method.</td> +</tr> +<tr class="b"> +<td width="410"> +<pre>AXIS2_EXPORT int<br />axis2_remove_instance(<br /> axis2_svc_skeleton_t * inst,<br /> const axutil_env_t * env);</pre> +</td> +<td>Removes the instance of the service. Do any cleaning-up +and deallocations here.</td> +</tr> +</tbody> +</table> +<br /> +<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> +<p style="margin-bottom: 0in;"><br /> +</p> +<p><a name="client_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 +<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> +<table class="bodyTable"> +<caption></caption><tbody> +<tr class="a"> +<th>Function Signature</th> +<th>Description</th> +</tr> +<tr class="b"> +<td> +<pre>AXIS2_EXTERN void AXIS2_CALL<br /> axis2_svc_client_fire_and_forget(<br /> axis2_svc_client_t * svc_client,<br /> const axutil_env_t * env,<br /> const axiom_node_t * payload);</pre> +</td> +<td>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.</td> +</tr> +<tr class="a"> +<td width="410"> +<pre>AXIS2_EXTERN axis2_status_t AXIS2_CALL<br /> axis2_svc_client_send_robust(<br /> axis2_svc_client_t * svc_client,<br /> const axutil_env_t * env,<br /> const axiom_node_t * payload);</pre> +</td> +<td>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.<br /> +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>functions +support this MEP</td> +</tr> +<tr class="b"> +<td> +<pre> AXIS2_EXTERN axiom_node_t *AXIS2_CALL<br /> axis2_svc_client_send_receive(<br /> axis2_svc_client_t * svc_client,<br /> const axutil_env_t * env,<br /> const axiom_node_t * payload);</pre> +</td> +<td>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.<br /> +Returns a pointer to the AXIOM node representing the XML response. This +method blocks the client until the response arrives.</td> +</tr> +<tr class="a"> +<td> +<pre>AXIS2_EXTERN void AXIS2_CALL<br /> axis2_svc_client_send_receive_non_blocking(<br /> axis2_svc_client_t * svc_client,<br /> const axutil_env_t * env,<br /> const axiom_node_t * payload,<br /> axis2_callback_t * callback);</pre> +</td> +<td>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.<br /> +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.</td> +</tr> +</tbody> +</table> +<br /> +<p>Please have a look at the <code>axis2_svc_client.h</code> +header file for +more information on the above mentioned functions, as well as their +synonyms +that accept an operation's qualified name.</p> +<div class="subsection"><a name="4_1_Synchronous_vs__Asynchronous_Behavior__Blocking_Non-Blocking_"></a> +<h3>4.1 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> +</div> +<div class="subsection"><a name="4_2_Two-Way_or_One-Way_Transport"></a> +<h3>4.2 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> +<p style="margin-bottom: 0in;"><br /> +</p> +<p><a name="rest"></a></p> +</div> +</div> +<div class="section"><a name="5__REST"></a> +<h2>5. REST</h2> +<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. By +default, +your service will support SOAP as well as REST, however, your service +operations +will only be available for SOAP. In order to enable REST for your +operations you +need to add one or more parameters under your operation, in the <a href="#appB">services.xml</a>. +If you want to consume Web services using REST style calls, you can use +the HTTP +POST method, the HTTP GET method, the HTTP HEAD method, the HTTP PUT +method or +the HTTP DELETE method.<br /> +</p> +</div> +<div class="subsection"><a name="5_1_REST_client"></a> +<h3>5.1 REST on Client Side</h3> +<p>The following example code fragment shows how to set up a +client enabling a REST style +invocation.</p> +<div class="source"> +<pre>axis2_options_set_enable_rest(options, env, AXIS2_TRUE);<br /><br /></pre> +</div> +<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> +<div class="source"> +<pre>axis2_options_set_http_method(options, env, AXIS2_HTTP_GET);<br /><br /></pre> +</div> +<p>Similarly you can use AXIX2_HTTP_HEAD to change it to the HTTP +HEAD method, +or AXIX2_HTTP_PUT to change it to the HTTP PUT method, or +AXIX2_HTTP_DELETE to change it +to the HTTP DELETE method. </p> +<p>Please have a look at the <code>echo_rest</code> +sample for a complete +source code on how to use REST.<br /> +</p> +</div> +<div class="subsection"><a name="5_2_REST_server"></a> +<h3>5.2 REST on Server Side</h3> +<p>You basically need to add the REST Location, and the REST +Method parameters to the <a href="#appB">services.xml</a> +to enable REST in a service operation. The REST location is the +template that needs to be matched +to find your operation, and the REST Method is the HTTP Method +associated with the service. +Note that the REST Method is optional for each operation. If no REST +Method is specified, POST, +will be assumed. Optionally you may specify the default REST Method for +all operations at the service +level. Then, if you haven't specified a REST Method for your operation, +the default REST Method +specified will be assumed instead of POST. Please have a look at the <code>echo</code> +sample +service for a complete source code on how to set up REST. Shown below +is an example, on how to +configure the <code>locate</code> operation to work with +HTTP GET on REST.<br /> +</p> +<div class="source"> +<pre><operation name="locate"><br /> <parameter name="RESTMethod">GET</parameter><br /> <parameter name="RESTLocation">location/{lat}/{long}</parameter><br /></operation><br /><br /></pre> +</div> +<p>The corresponding request would look like, <code>http://www.sample.org/service/location/34N/118W</code>, +which would return Los Angeles, California. In here, the portion <code>location</code> +is fixed and <code>lat</code> and <code>long</code> +are optional parameters which will be captured to the payload. +<br /> +</p> +</div> +<div class="subsection"><a name="5_3_REST_and_SOAP_for_same_operation"></a> +<h3>5.3 REST and SOAP for Same Operation</h3> +<p>It is also possible to enable a single service operation for +SOAP as well as REST. This can be done by specifying a REST Location +that does not contain the operation name. The <code>locate</code> +operation is an example to such a case. Thus, for a SOAP invocation, +you need to use <code>http://www.sample.org/service/locate</code>, +as the end point or WS-Addressing Action.</p> +<p style="margin-bottom: 0in;"><br /> +</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 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> +<div class="source"> +<pre><soapenv:Body><br /> <ns1:mtomSample xmlns:ns1="http://ws.apache.org/axis2/c/samples/mtom"><br /> <ns1:fileName>test.jpg</ns1:fileName><br /> <ns1:image><br /> <xop:Include xmlns:xop="http://www.w3.org/2004/08/xop/include" <br /> href="cid:1.f399248e-8b39-1db1-3124-0015c53de2e5@apache.org"></xop:Include><br /> </ns1:image><br /> </ns1:mtomSample><br /></soapenv:Body><br /><br /></pre> +</div> +<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);<br />data_handler = axiom_data_handler_create(env, image_name, "image/jpeg");<br />data_text = axiom_text_create_with_data_handler(env, image_om_node, data_handler, &data_om_node);<br /><br /></pre> +</div> +<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><h3><span style="font-weight: bold;">6.1 Using MTOM Callbacks</span></h3>Axis2/C +Can send and receive very large attachments with a very low memory foot +print. User can specify callbacks to load attachments before sending +and store attachments while recieving.<br /><h4>6.1.1 Sender side Callback</h4>The attachment can be loaded from any data source. User need to implement the callback using <a href="http://svn.apache.org/repos/asf/webservices/axis2/trunk/c/axiom/include/axiom_mtom_sending_callback.h">axiom_mtom_sending_callback.h</a>. A sample Callback can be found <a href="http://svn.apache.org/repos/asf/webservices/axis2/trunk/c/samples/mtom_sending_callback/mtom_sending_callback.c">here</a>. Following is what need to be done with data_handler in the case of a callback.<br /> <br /><span style="font-family: monospace;">data_handler = axiom_data_handler_create(env, NULL, content-type);</span><br style="font-family: monospace;" /><span style="font-family: monospace;">axiom_data_handler_set_data_handler_type(data_handler, env, AXIOM_DATA_HANDLER_TYPE_CALLBACK);</span><br style="font-family: monospace;" /><span style="font-family: monospace;">axiom_data_handler_set_user_param(data_handler, env, (void *)user_param);</span><p>user_param +is of any type which the user should know how to handle from the +callback. The path to the implemented callback should be specified in +the axis2.xml as follows.</p><p><span style="font-family: monospace;"><parameter name="MTOMSendingCallback" locked="false">/path/to/the/attachment_sending_callback</parameter></span></p><h4><span style="font-family: monospace;"></span><span style="font-weight: bold;">6.1.2 Receiver side callback</span></h4><p>For +large attachments users can specify them to be cached either to a file +or to a any storage. In order to enable caching user should set either "attachmentDir" or "MTOMCachingCallback<span style="font-family: monospace;"></span>" +parameters in the axis2.xml. If both are set the callback will be used. +If nothing is set attachment will reside in memory. </p><p>Following is an example of specifying the attachmentDir.</p><p style="font-family: monospace;"><parameter name="attachmentDIR" locked="false">/path/to/the/dir/</parameter></p><p>So the attachments will be saved +in the specified directory using the attachment content id as the file +name.</p><p>In the callback case the callback should be implemented using <a href="http://svn.apache.org/repos/asf/webservices/axis2/trunk/c/axiom/include/axiom_mtom_caching_callback.h">axiom_mtom_caching_callback.h</a>. The following paramter will enbale the caching callback.</p><p><span style="font-family: monospace;"><parameter name="MTOMCachingCallback" locked="false">/path/to/the/attachment_caching_callback</parameter></span></p>A sample callback implementation can be found <a href="http://svn.apache.org/repos/asf/webservices/axis2/trunk/c/samples/mtom_caching_callback/mtom_caching_callback.c">here</a>.<p>Axis2/C +allows to set the caching threshold. The default is 1MB. For +example to cache attachments which are greater than 10MB in size user +need to add the following directive in axis2.xml.</p><p> <span style="font-family: monospace;"><parameter name="MTOMBufferSize" locked="false">10</parameter></span></p><p><span style="font-family: monospace;"></span>This will give the control to the users to use the availbale memory even with larger attachments.</p><p>When the attachment is cached the ultimate receiver can always identify it by calling ,</p><p style="font-family: monospace;">if (axiom_data_handler_get_cached(data_handler, env))<br />{<br /> /* logic for attachment handling */<br />}</p> +<p>The logic on how to handle the attachment will depend on the mechanism which is used to cached the attachment.</p><p>Please have a look at the MTOM related samples in the Axis2/C samples directory.</p><br /> + +<p><a name="engaging_module"></a></p> +</div> +<div class="section"><a name="7__Engaging_a_Module"></a> +<h2>7. Engaging a Module</h2> +<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> +<div class="subsection"><a name="7_1_Writing_the_module_xml_File"></a> +<h3>7.1 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> +<div class="source"> +<pre> <module name="logging" class="axis2_mod_log"><br /> <inflow><br /> <handler name="LoggingInHandler" class="axis2_mod_log"><br /> <order phase="PreDispatch"/><br /> </handler><br /> </inflow><br /> <outflow><br /> <handler name="LoggingOutHandler" class="axis2_mod_log"><br /> <order phase="MessageOut"/><br /> </handler><br /> </outflow><br /> <Outfaultflow><br /> <handler name="LoggingOutHandler" class="axis2_mod_log"><br /> <order phase="MessageOut"/><br /> </handler><br /> </Outfaultflow><br /> </module><br /><br /></pre> +</div> +<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> +</div> +<div class="subsection"><a name="7_2_Packaging_and_Deploying_the_Module"></a> +<h3>7.2 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> +</div> +<div class="subsection"><a name="7_3_Adding_Module_Specific_Phases_to_the_axis2_xml_File"></a> +<h3>7.3 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> +<div class="source"> +<pre> <!-- User defined phases could be added here --></pre> +</div> +<p>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> +<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> +</div> +<div class="subsection"><a name="7_4_Engaging_a_Module_to_a_Services"></a> +<h3>7.4 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> +<div class="source"> +<pre> <service name="echo"><br /> <module ref ="logging"/><br /> <parameter name="ServiceClass" locked="xsd:false">echo</parameter><br /> <description><br /> This is a testing service, to test if the system is working or not.<br /> </description><br /> <operation name="echoString"><br /> <!--messageReceiver class="axis2_receivers" /--><br /> <parameter name="wsamapping" ><br /> http://ws.apache.org/axis2/c/samples/echoString<br /> </parameter><br /> </operation><br /> </service><br /><br /></pre> +</div> +<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> +</div> +<div class="subsection"><a name="7_4_1_Engaging_a_Module_Globally"></a> +<h3>7.4.1 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> +</div> +<div class="subsection"><a name="7_5_Engaging_a_Module_on_the_Client_Side"></a> +<h3>7.5 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> +<div class="source"> +<pre>axis2_svc_client_engage_module(svc_client, env, "module-name");<br /><br /></pre> +</div> +<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> +<div class="source"> +<pre>axis2_svc_client_engage_module(svc_client, env, "logging");<br /><br /></pre> +</div> +<p style="margin-bottom: 0in;"><br /> +</p> +<p><a name="ws_addressing"></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 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> +<div class="source"> +<pre>axis2_svc_client_engage_module(svc_client, env, AXIS2_MODULE_ADDRESSING);<br /><br /></pre> +</div> +<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> +<div class="source"> +<pre>axis2_options_set_action(options,env,"http://ws.apache.org/axis2/c/samples/echoString")<br /><br /></pre> +</div> +<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> +<div class="source"> +<pre>axis2_options_set_reply_to(options, env, reply_to)<br /><br /></pre> +</div> +<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> +<div class="source"> +<pre>axis2_options_set_fault_to(options, env, fault_to)<br /><br /></pre> +</div> +<p>Sets the <code>wsa:FaultTo</code> header. This +contains the endpoint to +direct fault messages.</p> +<div class="source"> +<pre>axis2_options_set_from(options, env, from)<br /><br /></pre> +</div> +<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> +<div class="source"> +<pre>axis2_options_set_relates_to(options, env, relates_to)<br /><br /></pre> +</div> +<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> +<p style="margin-bottom: 0in;"><br /> +</p> +<p><a name="writing_module"></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 +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> +<table class="bodyTable"> +<caption></caption><tbody> +<tr class="b"> +<th>Function Signature</th> +<th>Description</th> +</tr> +<tr class="a"> +<td> +<pre>axis2_status_t (AXIS2_CALL * <br /> init)(axis2_module_t *module, const<br /> axutil_env_t *env, <br /> axis2_conf_ctx_t *conf_ctx, <br /> axis2_module_desc_t *module_desc);</pre> +</td> +<td>This function takes care of the module initialization.</td> +</tr> +<tr class="b"> +<td width="410"> +<pre>axis2_status_t (AXIS2_CALL * <br /> shutdown)(axis2_module_t *module, <br /> const axutil_env_t *env );</pre> +</td> +<td>Shuts down and cleans up the module.</td> +</tr> +<tr class="a"> +<td> +<pre>axis2_status_t (AXIS2_CALL *<br /> fill_handler_create_func_map)(axis2_module_t *module, <br /> const axutil_env_t *env );</pre> +</td> +<td>This function fills the hash map of the handler create +functions for the module.</td> +</tr> +</tbody> +</table> +<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> +<div class="subsection"><a name="9_1_Writing_Handlers"></a> +<h3>9.1 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> +</div> +<div class="subsection"><a name="9_2_Writing_the_module_xml_File"></a> +<h3>9.2 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> +<p style="margin-bottom: 0in;"><br /> +</p> +<p><a name="simple_axis_server"></a></p> +</div> +</div> +<div class="section"><a name="10__Simple_Axis2_HTTP__Server"></a> +<h2>10. Simple Axis2 HTTP Server</h2> +<p>Simple Axis2 HTTP Server is the inbuilt HTTP server of Axis2/C.<br /> +</p> +<div class="subsection"><a name="10_1_Linux_Based_Systems"></a> +<h3>10.1 Linux Based Systems</h3> +<p>Synopsis :</p> +<div class="source"> +<pre> axis2_http_server [-p PORT] [-t TIMEOUT] [-r REPO_PATH] [-l LOG_LEVEL] [-f LOG_FILE] [-s LOG_FILE_SIZE]<br /><br /></pre> +</div> +<p>You can use the following options with simple axis HTTP server.</p> +<div class="source"> +<pre> -p PORT port number to use, default port is 9090<br /> -r REPO_PATH repository path, default is ../<br /> -t TIMEOUT socket read timeout, default is 30 seconds<br /> -l LOG_LEVEL log level, available log levels:<br /> 0 - critical 1 - errors 2 - warnings<br /> 3 - information 4 - debug 5- user 6 - trace<br /> Default log level is 4(debug).<br /> -f LOG_FILE log file, default is $AXIS2C_HOME/logs/axis2.log<br /> or axis2.log in current folder if AXIS2C_HOME not set<br /> -s LOG_FILE_SIZE Maximum log file size in mega bytes, default maximum size is 1MB.<br /> -h display the help screen.<br /><br /></pre> +</div> +<p>Example :</p> +<div class="source"> +<pre> axis2_http_server -l 3 -p 8080 -r $AXIS2C_HOME -f /dev/stderr<br /><br /></pre> +</div> +</div> +<div class="subsection"><a name="10_2_MS_Windows_Based_Systems"></a> +<h3>10.2 MS Windows Based Systems</h3> +<p>Synopsis :</p> +<div class="source"> +<pre> axis2_http_server.exe [-p PORT] [-t TIMEOUT] [-r REPO_PATH] [-l LOG_LEVEL] [-f LOG_FILE] [-s LOG_FILE_SIZE]<br /><br /></pre> +</div> +<p>You can use the following options with simple axis HTTP server.</p> +<div class="source"> +<pre> -p PORT port number to use, default port is 9090<br /> -r REPO_PATH repository path, default is ../<br /> -t TIMEOUT socket read timeout, default is 30 seconds<br /> -l LOG_LEVEL log level, available log levels:<br /> 0 - critical 1 - errors 2 - warnings<br /> 3 - information 4 - debug 5- user 6 - trace<br /> Default log level is 4(debug).<br /> -f LOG_FILE log file, default is %AXIS2C_HOME%\logs\axis2.log<br /> or axis2.log in current folder if AXIS2C_HOME not set<br /> -s LOG_FILE_SIZE Maximum log file size in mega bytes, default maximum size is 1MB.<br /> -h display the help screen.<br /><br /></pre> +</div> +<p>Example :</p> +<div class="source"> +<pre> axis2_http_server.exe -l 3 -p 8080 -r %AXIS2C_HOME% -f C:\logs\error.log<br /><br /></pre> +</div> +<p style="margin-bottom: 0in;"><br /> +</p> +<p><a name="mod_axis2"></a></p> +</div> +</div> +<div class="section"><a name="11__Deploying_with_Apache_HTTP_Server_Version_2_x"></a> +<h2>11. Deploying with Apache HTTP Server Version 2.x</h2> +<div class="subsection"><a name="11_1_Linux_Platform"></a> +<h3>11.1 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> +<div class="source"> +<pre>./configure --with-apache2=[path to Apache2 include directory] [other configure options]<br /><br /></pre> +</div> +<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> +<div class="source"> +<pre>./configure --with-apache2=[path to Apache2 include directory] --with-apr=[path to APR include directory]<br /> [other configure options]<br /><br /></pre> +</div> +<p>Then build the source tree as usual using:</p> +<div class="source"> +<pre> make<br /> make install<br /><br /></pre> +</div> +<p>This will install mod_axis2.so into your +AXIS2C_INSTALL_DIR/lib folder.</p> +</div> +<div class="subsection"><a name="11_2_MS_Windows_Platform"></a> +<h3>11.2 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> +<div class="source"> +<pre>APACHE_BIN_DIR = "C:\Program Files\Apache Software Foundation\Apache2.2"<br /><br /></pre> +</div> +<p>Based on the Apache HTTP server version you are using, you +also need to +set the setting APACHE_VERSION_2_0_X in the configure.in file. If +you are +using Apache 2.2 family, this setting should be set to 0,else set it to +1.</p> +<div class="source"> +<pre>APACHE_VERSION_2_0_X = 0<br /><br /></pre> +</div> +<p>To build the source, you have to run the command</p> +<div class="source"> +<pre>nmake axis2_apache_module</pre> +</div> +<p>This will build mod_axis2.dll and copy it to +AXIS2C_INSTALL_DIR\lib directory. +</p> +</div> +<div class="subsection"><a name="11_3_Deploying_mod_axis2"></a> +<h3>11.3 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. If you are +using the binary release of Axis2/C, please note that it is built with +Apache 2.2.</font></p> +<p>Copy the mod_axis2 shared library <font color="#4169e1">(libmod_axis2.so.0.6.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> +<div class="source"> +<pre> cp $AXIS2C_HOME/lib/libmod_axis2.so.0.6.0 /usr/lib/apache2/modules/mod_axis2.so<br /></pre> +</div> +<p>On MS Windows</p> +<div class="source"> +<pre> copy /Y "%AXIS2C_HOME%\lib\mod_axis2.dll" C:\Apache2\modules\mod_axis2.so<br /><br /></pre> +</div> +<p>Edit the Apache2's configuration file (generally httpd.conf) +and add the +following directives at the end of the file.</p> +<div class="source"> +<pre>LoadModule axis2_module MOD_AXIS2_SO_PATH<br />Axis2RepoPath AXIS2C_INSTALL_DIR<br />Axis2LogFile PATH_TO_LOG_FILE<br />Axis2LogLevel LOG_LEVEL<br />Axis2ServiceURLPrefix PREFIX<br />Axis2MaxLogFileSize SIZE_IN_MB<br /><Location /axis2><br /> SetHandler axis2_module<br /></Location><br /><br /></pre> +</div> +<p>Please note that you have to fine tune the above settings to +mach your +system.<br /> +<br /> +MOD_AXIS2_SO_PATH has to be replaced with the full path to +mod_axis2.so, +for example, <code>/usr/lib/apache2/modules/mod_axis2.so</code> +on Linux, or <code>C:\Apache2\modules\mod_axis2.so</code> +on MS Windows<br /> +<br /> +AXIS2C_INSTALL_DIR has to be replaced with the full path to Axis2/C +repository, for example, <code>/usr/local/axis2</code> on +Linux, or <code>c:\axis2c</code> on MS Windows. 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, <code>/tmp/axis2.log</code> +on Linux, or <code>C:\Apache2\logs\axis2.log</code> on MS +Windows. 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>user - log user level messages and above</li> +<li>trace - log trace messages and above</li> +</ul> +<p>SIZE_IN_MB must be replaced by the size of the particular +resource in MB, rounded to +the nearest whole value.<br /> +<br /> +PREFIX has to be replaced with the prefix to be used with the service +endpoints. This is optional and defaults to "services". +As an example, if you have "web_services" as the prefix, then all the +services hosted would have the endpoint prefix of : <br /> +http://localhost/axis2/web_services <br /> +If you wish, you can also change the location as well by replacing +"/axis2" in <Location /axis2> setting with whatever you +wish. +</p> +<p><font color="#666666">NOTE: If you want to use a +Shared Global Pool with Apache +you have to give another entry called Axis2GlobalPoolSize.You have to +give the +size of the shared global pool in MB.If you doesn't set the value or if +you set a +negative value Apache module doesn't create shared global pool.</font></p> +<div class="source"> +<pre>Axis2GlobalPoolSize SIZE_IN_MB<br /><br /></pre> +</div> +<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" class="externalLink" title="External Link">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> +<div class="source"> +<pre>echo http://localhost/axis2/services/echo<br /><br /></pre> +</div> +<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, user 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 APACHE_INSTALL_DIR/logs folder.</li> +</ul> +<p style="margin-bottom: 0in;"><br /> +</p> +<p><a name="IIS"></a></p> +</div> +</div> +<div class="section"><a name="12__Deploying_with_Microsoft_IIS_Server"></a> +<h2>12. Deploying with Microsoft IIS Server</h2> +<p>Use the Axis2/C VC project or makefile to buid the +component. If you are using the makefile to build the source, you have +to run the command</p> +<div class="source"> +<pre>nmake axis2_iis_module</pre> +</div> +<p>In this document I assume that the mod_axis2_IIS.dll +is in the directory <code>c:\axis2c\lib</code> and +AXIS2C_HOME +is <code>c:\axis2c</code></p> +<p>Add the following key to the +registery.</p> +<p><code>HKEY_LOCAL_MACHINE\SOFTWARE\Apache Axis2c\IIS +ISAPI +Redirector</code></p> +<p>Add a string value with the name <code>AXIS2C_HOME</code> +and a +value of <code>c:\axis2c</code></p> +<p>Add a string value with the name <code>log_file</code> +and a value +of <code>c:\axis2c\logs\axis2.log</code></p> +<p>Add a string value with the name <code>log_level</code>. +The value +can be either <code>trace</code>, <code>error</code>, +<code>info</code>, <code>critical</code>, <code>user</code>, +<code>debug</code>, or <code>warning</code>.</p> +<p> +You can add a string value with the name <code>services_url_prefix</code>. This is optional and defaults to "/services". +As an example, if you have "/web_services" as the prefix, then all the +services hosted would have the endpoint prefix of : <br /> +http://localhost/axis2/web_services.<br />Note: don't forget the / at the begining.<br /> +</p> +<p> +If you wish, you can also change the location as well by adding a string value with the name <code>axis2_location</code>. This is also optional and defaults to /axis2. +If you have /myserser as the value you can access your web services with a url like http://localhost/myserver/services. <br />Note: Don't forget the / at the beginning.</p> +<p> + +</p><p>Now you can do all the registry editing using the JScript file +axis2_iis_regedit.js provided with the distribution. When you build +axis2/C with the IIS module the file is copied to the root directory of +the binary distribution. Just double click it and everything will be +set to the defaults. The axis2c_home is taken as the current directory, +so make sure you run the file in the Axis2/C repository location (or +root of the binary distribution). If you want to change the values you +can manually edit the the .js file or give it as command line arguments +to the script when running the script. To run the jscript from the +command line use the command <code>:\cscript axis2_iis_regedit.js optional arguments</code>. We recomend the manual editing as it is the easiest way to specify the values.</p> +<p><b>IIS 5.1 or Below</b></p> +Using the IIS management console, add a new virtual +directory to your IIS/PWS web site. The name of the virtual directory +must be <code>axis2</code>. Its +physical path should be the directory in which you placed +mod_axis2_IIS.dll (in our example it is +c:\axis2c\lib). When creating this new virtual directory, <b>assign +execute access to it</b>. +<p>By using the IIS management console, add +mod_axis2_IIS.dll as a filter in your IIS/PWS web site and restart the +IIS +admin service.</p> +<p><b>IIS 6 & 7</b></p> +Using the IIS management console, add the mod_axis2_IIS.dll as a +Wildcard Script Map. +<ul> +<li>Executable should be the complete path to the +mod_axis2_IIS.dll</li> +<li>You can put any name as the name of the Wildcard Script Map</li> +</ul> +<p>Please don't add the mod_axis2_IIS.dll as a filter to IIS as +in the IIS 5.1 case.</p> +<p>Note: If the Axis2/C failed to load, verify that Axis2/C and +its dependent DLLs are in the System Path (not the user path). </p> +<p style="margin-bottom: 0in;"><br /> +</p> +<p><a name="ssl_client"></a></p> +</div> +<div class="section"><a name="13__Using_SSL_Client"></a> +<h2>13. Using SSL Client</h2> +<div class="subsection"><a name="13_1_Building_and_Configuring_the_Client"></a> +<h3>13.1 Building and Configuring the Client</h3> +<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/" class="externalLink" title="External Link">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 <code>nmake +all</code> command.</p> +<p><a name="client_chain"></a></p> +</div> +<div class="subsection"><a name="13_1_1_Creating_the_Client_Certificate_Chain_File"></a> +<h3>13.1.1 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> +</div> +<div class="subsection"><a name="13_1_2_Configuration"></a> +<h3>13.1.2 Configuration</h3> +<p>Uncomment the following in <code>axis2.xml</code> +to enable https transport receiver and https transport sender. +Axis2/C will then be able to recognize the "https" sheme in a given end +point reference (EPR) and use SSL transport. +</p> +<div class="source"> +<pre><transportReceiver name="https" class="axis2_http_receiver"><br /> <parameter name="port" locked="false">6060</parameter><br /> <parameter name="exposeHeaders" locked="true">false</parameter><br /></transportReceiver><br /></pre> +</div> +<div class="source"> +<pre><transportSender name="https" class="axis2_http_sender"><br /> <parameter name="PROTOCOL" locked="false">HTTP/1.1</parameter><br /></transportSender><br /></pre> +</div> +<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> +<div class="source"> +<pre>-----BEGIN CERTIFICATE-----<br />-----END CERTIFICATE-----<br /><br /></pre> +</div> +<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> +<div class="source"> +<pre>echo |\<br />openssl s_client -connect <servername>:<port> 2>&1 |\<br />sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > cert.pem<br /><br /></pre> +</div> +<p><font color="#666666">NOTE: Instead of setting +these parameters in the <code>axis2.xml</code> +file, you can also set these parameters programmatically in your client +code.</font></p> +</div> +<div class="subsection"><a name="13_2_Configuring_the_Server"></a> +<h3>13.2 Configuring the Server</h3> +<p>Here we will only look at the configuration of the Apache HTTP +Web server. +Refer to the '<a href="#mod_axis2">Deploying with Apache +HTTP Server Version2.x</a>' section 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" class="externalLink" title="External Link">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><font color="#666666">NOTE: The last two lines, <code>SSLVerifyClient</code> +and +<code>SSLVerifyDepth</code> are only needed when you need +client +authentication.</font></p> +<p style="margin-bottom: 0in;"><br /> +</p> +<p><a name="proxy"></a></p> +</div> +</div> +<div class="section"><a name="14__Using_Proxy_Support"></a> +<h2>14. Using Proxy Support</h2> +<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</li> +</ol> +<div class="subsection"><a name="14_1_Specifying_Proxy_Settings_in_axis2_xml"></a> +<h3>14.1 Specifying Proxy Settings in axis2.xml</h3> +<div class="source"> +<pre><transportSender name="http" class="axis2_http_sender"><br /> <parameter name="PROTOCOL" locked="false">HTTP/1.1</parameter><br /> <parameter name="PROXY" proxy_host="127.0.0.1" proxy_port="8080" locked="true"/><br /></transportSender><br /><br /></pre> +</div> +</div> +<div class="subsection"><a name="14_2_Providing_Proxy_Settings_Using_Service_Client_API"></a> +<h3>14.2 Providing Proxy Settings Using Service Client API</h3> +<p>You can specify proxy settings using the following function +with the +service client:</p> +<div class="source"> +<pre>axis2_svc_client_set_proxy(axis2_svc_client_t *svc_client,<br /> const axutil_env_t *env,<br /> axis2_char_t *proxy_host,<br /> axis2_char_t *proxy_port);<br /><br /></pre> +</div> +<p style="margin-bottom: 0in;"><br /> +</p> +<p><a name="proxy_auth"></a></p> +</div> +</div> +<div class="section"><a name="15__Using_Proxy_Authentication_Support"></a> +<h2>15. Using Proxy Authentication Support</h2> +<p>When using proxy authentication, there are three methods for +specifying proxy +authentication settings:</p> +<ol> +<li>Specify proxy settings with authentication in axis2.xml</li> +<li>Provide proxy settings with authentication using service +client API</li> +<li>Provide proxy authentication settings using service client +options</li> +</ol> +<div class="subsection"><a name="15_1_Specifying_Proxy_Settings_with_Authentication_in_axis2_xml"></a> +<h3>15.1 Specifying Proxy Settings with Authentication in +axis2.xml</h3> +<div class="source"> +<pre><transportSender name="http" class="axis2_http_sender"><br /> <parameter name="PROTOCOL" locked="false">HTTP/1.1</parameter><br /> <parameter name="PROXY" proxy_host="127.0.0.1" proxy_port="8080" proxy_username="" proxy_password="" locked="true"/><br /></transportSender><br /><br /></pre> +</div> +</div> +<div class="subsection"><a name="15_2_Providing_Proxy_Settings_with_Authentication_Using_Service_Client_API"></a> +<h3>15.2 Providing Proxy Settings with Authentication Using +Service Client API</h3> +<p>You can specify proxy authentication settings using the +following function with the +service client:</p> +<div class="source"> +<pre>axis2_svc_client_set_proxy_with_auth(axis2_svc_client_t *svc_client,<br /> const axutil_env_t *env,<br /> axis2_char_t *proxy_host,<br /> axis2_char_t *proxy_port,<br /> axis2_char_t *username,<br /> axis2_char_t *password);<br /><br /></pre> +</div> +</div> +<div class="subsection"><a name="15_3_Providing_Proxy_Authentication_Settings_Using_Service_Client_Options"></a> +<h3>15.3 Providing Proxy Authentication Settings Using Service +Client Options</h3> +<p>You can specify proxy authentication settings using the +following function with the +service client options:</p> +<div class="source"> +<pre>axis2_options_set_proxy_auth_info(<br /> axis2_options_t * options,<br /> const axutil_env_t * env,<br /> const axis2_char_t * username,<br /> const axis2_char_t * password,<br /> const axis2_char_t * auth_type);<br /></pre> +</div> +<p>In <code>auth_type</code>, use <b>Basic</b> +to force Basic Authentication or <b>Digest</b> to force +Digest +Authentication. Leave this field NULL if you are not forcing +authentication.</p> +<div class="subsection"><a name="15_4_Predetermining_Proxy_Authentication_Details"></a> +<h3>15.4 Predetermining Proxy Authentication Details</h3> +<p>You can also predetermine whether proxy authentication is +required. This can be done by calling the function below:</p> +<div class="source"> +<pre>axis2_options_set_test_proxy_auth(<br /> axis2_options_t * options,<br /> const axutil_env_t * env,<br /> const axis2_bool_t test_proxy_auth);<br /></pre> +</div> +<p>Set <code>test_proxy_auth</code> to <b><code>AXIS2_TRUE</code></b> +to enable testing.When testing is enabled, the request will be sent +without without adding authentication information. If it fails, and +requests Authentication Information, the request type of authentication +will be saved. This information can be obtained in the following manner:</p> +<div class="source"> +<pre>axis2_svc_client_get_auth_type(<br /> const axis2_svc_client_t * svc_client,<br /> const axutil_env_t * env);<br /></pre> +</div> +<p> This will return either <b>Basic</b>, <b>Digest</b> +or <b>NULL</b> according to the type of authentiation +requested. In addition to that, after each request made through the +service client, you can check whether authentication was required.</p> +<div class="source"> +<pre>axis2_svc_client_get_proxy_auth_required(<br /> const axis2_svc_client_t * svc_client,<br /> const axutil_env_t * env);<br /></pre> +</div> +<p>Please take a look at the <code>echo_blocking_auth</code> +sample for more information on how to use these methods to identify +proxy Authentication requirements.</p> +<p style="margin-bottom: 0in;"><br /> +</p> +<p><a name="http_auth"></a></p> +</div> +</div> +<div class="section"><a name="16__Using_HTTP_Authentication_Support"></a> +<h2>16. Using HTTP Authentication Support</h2> +<p>When using HTTP authentication, there are two methods for +specifying proxy +authentication settings:</p> +<ol> +<li>Specify HTTP authentication settings in axis2.xml</li> +<li>Provide HTTP authentication settings using service client +options</li> +</ol> +<div class="subsection"><a name="16_1_Specifying_HTTP_Authentication_Settings_in_axis2_xml"></a> +<h3>16.1 Specifying HTTP Authentication Settings in axis2.xml</h3> +<div class="source"> +<pre><transportSender name="http" class="axis2_http_sender"><br /> <parameter name="PROTOCOL" locked="false">HTTP/1.1</parameter><br /> <parameter name="HTTP-Authentication" username="your username" password="your password" locked="true"/><br /></transportSender><br /><br /></pre> +</div> +</div> +<div class="subsection"><a name="16_2_Providing_HTTP_Authentication_Settings_Using_Service_Client_Options"></a> +<h3>16.2 Providing HTTP Authentication Settings Using Service +Client Options</h3> +<p>You can specify HTTP authentication settings using the +following function with the +service client options:</p> +<div class="source"> +<pre>axis2_options_set_http_auth_info(<br /> axis2_options_t * options,<br /> const axutil_env_t * env,<br /> const axis2_char_t * username,<br /> const axis2_char_t * password,<br /> const axis2_char_t * auth_type);<br /></pre> +</div> +<p>In <code>auth_type</code>, use <b>Basic</b> +to force HTTP Basic Authentication or <b>Digest</b> to +force HTTP Digest +Authentication. Leave this field NULL if you are not forcing +authentication.</p> +<div class="subsection"><a name="16_3_Predetermining_HTTP_Authentication_Details"></a> +<h3>16.3 Predetermining HTTP Authentication Details</h3> +<p>You can also predetermine whether HTTP authentication is +required. This can be done by calling the function below:</p> +<div class="source"> +<pre>axis2_options_set_test_http_auth(<br /> axis2_options_t * options,<br /> const axutil_env_t * env,<br /> const axis2_bool_t test_http_auth);<br /></pre> +</div> +<p>Set <code>test_http_auth</code> to <b><code>AXIS2_TRUE</code></b> +to enable testing.When testing is enabled, the request will be sent +without without adding authentication information. If it fails, and +requests Authentication Information, the request type of authentication +will be saved. This information can be obtained in the following manner:</p> +<div class="source"> +<pre>axis2_svc_client_get_auth_type(<br /> const axis2_svc_client_t * svc_client,<br /> const axutil_env_t * env);<br /></pre> +</div> +<p> This will return either <b>Basic</b>, <b>Digest</b> +or <b>NULL</b> according to the type of authentiation +requested. In addition to that, after each request made through the +service client, you can check whether authentication was required.</p> +<div class="source"> +<pre>axis2_svc_client_get_http_auth_required(<br /> const axis2_svc_client_t * svc_client,<br /> const axutil_env_t * env);<br /></pre> +</div> +<p>Please take a look at the <code>echo_blocking_auth</code> +sample for more information on how to use these methods to identify +HTTP Authentication requirements.</p> +<p style="margin-bottom: 0in;"><br /> +</p> +<p><a name="wsdl2c"></a></p> +</div> +</div> +<div class="section"><a name="17__WSDL2C_Tool"></a> +<h2>17. WSDL2C Tool</h2> +<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" class="externalLink" title="External Link">Axis2/Java +SVN</a> revision 529533 or later revisions. You can download the <a href="http://people.apache.org/dist/axis2/nightly/" class="externalLink" title="External Link">Axis2/Java +nightly +build</a> and use those binaries to generate code. Check out a <a href="http://ws.apache.org/axis2/1_4_1/reference.html#wsdl2java" class="externalLink" title="External Link">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> +<div class="subsection"><a name="17_1_Generating_Service_Skeletons"></a> +<h3>17.1 Generating Service Skeletons</h3> +<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> +<div class="source"> +<pre>java org.apache.axis2.wsdl.WSDL2C -uri interoptestdoclitparameters.wsdl -ss -sd -d adb -u <br /><br /></pre> +</div> +<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_4_1/reference.html#wsdl2java" class="externalLink" title="External Link"> 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> +<div class="source"> +<pre>java org.apache.axis2.wsdl.WSDL2C -uri interoptestdoclitparameters.wsdl -ss -sd -d none<br /><br /></pre> +</div> +<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> +<div class="source"> +<pre>/* Todo fill this with the necessary business logic */</pre> +</div> +<p>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. +</p> +</div> +<div class="subsection"><a name="17_2_Generating_Client_Stubs"></a> +<h3>17.2 Generating Client Stubs</h3> +<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> +<div class="source"> +<pre>java WSDL2C -uri interoptestdoclitparameters.wsdl -d adb -u<br /><br /></pre> +</div> +<p>In order to ignore the data binding support and use a raw XML +in/out +model, just use the following parameters.</p> +<div class="source"> +<pre>java WSDL2C -uri interoptestdoclitparameters.wsdl -d none<br /><br /></pre> +</div> +<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> +<p style="margin-bottom: 0in;"><br /> +</p> +<p><a name="tcptrans"></a></p> +</div> +</div> +<div class="section"><a name="18__TCP_Transport"></a> +<h2>18. TCP Transport</h2> +<div class="subsection"><a name="18_1_Building_AXIS2C_enabling_TCP"></a> +<h3>18.1 Building AXIS2C enabling TCP</h3> +<p>This section will guide you through installing Axis2C with tcp +enabled, and this also includes how to test it by running samples. +Please note that both the Server and the Client must be built with TCP +enabled.</p> +</div> +<div class="subsection"><a name="18_1_1_Linux_Based_Systems"></a> +<h3>18.1.1 Linux Based Systems</h3> +<ol> +<li>When you are installing, you have to use the configure +command with +the option to enable tcp by providing the following argument:</li> +<pre> ./configure --enable-tcp=yes<br /> make<br /> make install</pre> +<li>Then to confirm that you have successfully built the source +with tcp enabled you can check in your $AXIS2C_HOME/lib folder for +following files:</li> +<pre> libaxis2_tcp_sender.so<br /> libaxis2_tcp_reciever.so</pre> +<li>To setup the tcp transport sender, you have to edit the +axis2.xml by uncommenting following entry:</li> +<pre> <transportSender name="tcp" class="axis2_tcp_sender"><br /> <parameter name="PROTOCOL" locked="false">TCP</parameter><br /> </transportSender></pre> +</ol> +</div> +<div class="subsection"><a name="18_1_2_MS_Windows_Based_Systems"></a> +<h3>18.1.2 MS Windows Based Systems</h3> +<ol> +<li>When you are installing, you have to set the configure +option to enable tcp +by specifying in <code>configure.in</code>:</li> +<pre> WITH_TCP = 1</pre> +<li>Then to confirm that you have successfully built the source +with tcp enabled you can check in your %AXIS2C_HOME%\lib folder for +following files:</li> +<pre> axis2_tcp_sender.dll<br /> axis2_tcp_reciever.dll</pre> +<li>To setup the tcp transport sender, you have to edit the +axis2.xml by uncommenting following entry:</li> +<pre> <transportSender name="tcp" class="axis2_tcp_sender"><br /> <parameter name="PROTOCOL" locked="false">TCP</parameter><br /> </transportSender></pre> +</ol> +</div> +<div class="subsection"><a name="18_2_Server_Side"></a> +<h3>18.2 Server Side</h3> +<ul> +<li>To run the tcp server on Linux based systems, you have to +start the tcp +server which runs in 9091 as its default port.</li> +<pre> cd $AXIS2C_HOME/bin/<br /> ./axis2_tcp_server</pre> +<li>To run the tcp server on MS Windows based systems, you have +to start the tcp server as,</li> +<pre> cd %AXIS2C_HOME%\bin<br /> axis2_tcp_server.exe</pre> +</ul> +</div> +<div class="subsection"><a name="18_2_1_Simple_Axis2_TCP_Server"></a> +<h3>18.2.1 Simple Axis2 TCP Server</h3> +<p>Simple Axis2 TCP Server is the inbuilt TCP server of Axis2/C.<br /> +</p> +</div> +<div class="subsection"><a name="18_2_1_1_Linux_Based_Systems"></a> +<h3>18.2.1.1 Linux Based Systems</h3> +<p>Synopsis :</p> +<div class="source"> +<pre> axis2_tcp_server [-p PORT] [-t TIMEOUT] [-r REPO_PATH] [-l LOG_LEVEL] [-f LOG_FILE] [-s LOG_FILE_SIZE]<br /><br /></pre> +</div> +<p>You can use the following options with simple axis TCP server.</p> +<div class="source"> +<pre> -p PORT port number to use, default port is 9091<br /> -r REPO_PATH repository path, default is ../<br /> -t TIMEOUT socket read timeout, default is 30 seconds<br /> -l LOG_LEVEL log level, available log levels:<br /> 0 - critical 1 - errors 2 - warnings<br /> 3 - information 4 - debug 5- user 6 - trace<br /> Default log level is 4(debug).<br /> -f LOG_FILE log file, default is $AXIS2C_HOME/logs/axis2.log<br /> or axis2.log in current folder if AXIS2C_HOME not set<br /> -s LOG_FILE_SIZE Maximum log file size in mega bytes, default maximum size is 1MB.<br /> -h display the help screen.<br /><br /></pre> +</div> +<p>Example :</p> +<div class="source"> +<pre> axis2_tcp_server -l 3 -p 8080 -r $AXIS2C_HOME -f /dev/stderr<br /><br /></pre> +</div> +</div> +<div class="subsection"><a name="18_2_1_2_MS_Windows_Based_Systems"></a> +<h3>18.2.1.2 MS Windows Based Systems</h3> +<p>Synopsis :</p> +<div class="source"> +<pre> axis2_tcp_server.exe [-p PORT] [-t TIMEOUT] [-r REPO_PATH] [-l LOG_LEVEL] [-f LOG_FILE] [-s LOG_FILE_SIZE]<br /><br /></pre> +</div> +<p>You can use the following options with simple axis TCP server.</p> +<div class="source"> +<pre> -p PORT port number to use, default port is 9091<br /> -r REPO_PATH repository path, default is ../<br /> -t TIMEOUT socket read timeout, default is 30 seconds<br /> -l LOG_LEVEL log level, available log levels:<br /> 0 - critical 1 - errors 2 - warnings<br /> 3 - information 4 - debug 5- user 6 - trace<br /> Default log level is 4(debug).<br /> -f LOG_FILE log file, default is %AXIS2C_HOME%\logs\axis2.log<br /> or axis2.log in current folder if AXIS2C_HOME not set<br /> -s LOG_FILE_SIZE Maximum log file size in mega bytes, default maximum size is 1MB.<br /> -h display the help screen.<br /><br /></pre> +</div> +<p>Example :</p> +<div class="source"> +<pre> axis2_tcp_server.exe -l 3 -p 8080 -r %AXIS2C_HOME% -f C:\logs\error.log<br /><br /></pre> +</div> +</div> +<div class="subsection"><a name="18_3_Client_Side"></a> +<h3>18.3 Client Side</h3> +<ul> +<li>In your service client you have to give the end point +address adding tcp as the URI Schema name in the client's code.</li> +<pre>tcp://[service_hostname]:[service_port]/axis2/services/your_service_name</pre> +<li>You can use TCPMon to figure out how the message is +transferred (without having it's http headers) after you've built +Axis2C enabling tcp.</li> +</ul> +<p style="margin-bottom: 0in;"><br /> +</p> +<p><a name="amqptrans"></a></p> +</div> +</div> +<div class="section"> +<h2>19. AMQP Transport</h2> +<div class="subsection"> +<h3>19.1 Building AXIS2C enabling AMQP</h3> +<p>This section will guide you through installing Axis2C with +AMQP +enabled, and this also includes how to test it by running samples. +Please note that both the Server and the Client must be built with AMQP +enabled.</p> +</div> +<div class="subsection"> +<h3>19.1.1 Linux Based Systems</h3> +<ol> +<li>When you are installing, you have to use the configure +command with +the option --with-qpid as follows</li> +<pre> ./configure --with-qpid=path/to/qpid home<br /> make<br /> make install</pre> +<li>Then to confirm that you have successfully built the source +with AMQP enabled you can check in your $AXIS2C_HOME/lib folder for +following files:</li> +<pre> libaxis2_qmqp_sender.so<br /> libaxis2_amqp_reciever.so</pre> +<li>To setup the AMQP transport, you have to edit the +axis2.xml and add the following entries:</li> +<pre> <transportReceiver name="amqp" class="axis2_amqp_receiver"><br /> <parameter name="qpid_broker_ip" locked="false">127.0.0.1</parameter><br /> <parameter name="qpid_broker_port" locked="false">5672</parameter><br /> </transportReceiver><br /><br /> <transportSender name="amqp" class="axis2_amqp_sender"/></pre> +</ol> +</div> +<div class="subsection"> +<h3>19.1.2 MS Windows Based Systems</h3> +Axis2/C does not support AMQP transport on Windows. +<ol> +</ol> +</div> +<div class="subsection"> +<h3>19.2 Server Side<span style="font-family: monospace;"></span></h3> +Start the Qpid broker as follows.<br /> +<br /> +<pre>$ cd ${QPID_HOME}/sbin<br />$ ./qpidd --data-dir ./</pre> +<br /> +Start the axis2_amqp_server as follows.<br /> +<br /> +<pre>$ cd ${AXIS2C_HOME}/bin<br />$ ./axis2_amqp_server<br /> </pre> +You should see the message<br /> + Started +Simple Axis2 AMQP Server...<br /> +<br /> +This will connect to the Qpid broker listening on 127.0.0.1:5672. <br /> +To see the possible command line options run<br /> +<br /> +<pre>$ ./axis2_amqp_server -h<br /></pre> +<br /> +NOTE : You have the flexibility of starting the Qpid broker first and +then axis2_amqp_server or vise versa.<br /> +<div class="subsection"> +<div style="text-align: left;"></div> +<h3>19.2.1 Simple Axis2 AMQP Server</h3> +<p>Simple Axis2 AMQP Server is the inbuilt AMQP server of Axis2/C.<br /> +</p> +</div> +<div class="subsection"> +<h3>19.2.1.1 Linux Based Systems</h3> +<p>Synopsis :</p> +<div class="source"> +<pre> axis2_amqp_server [-i QPID_BROKER_IP] [-p QPID_BROKER_PORT] [-r REPO_PATH] [-l LOG_LEVEL] [-f LOG_FILE] [-s LOG_FILE_SIZE]<br /><br /></pre> +</div> +<p>You can use the following options with simple axis AMQP server.</p> +<div class="source"> +<pre> -i IP where the Qpid broker is running, default IP is 127.0.0.1<br /> -p PORT port number the Qpid broker listens on, default port is 5672<br /> -r REPO_PATH repository path, default is ../<br /> -l LOG_LEVEL log level, available log levels:<br /> 0 - critical <br /> 1 - errors <br /> 2 - warnings<br /> 3 - information <br /> 4 - debug <br /> 5- user <br /> 6 - trace<br /> Default log level is 4(debug).<br /> -f LOG_FILE log file, default is $AXIS2C_HOME/logs/axis2.log or axis2.log in current folder if AXIS2C_HOME not set<br /> -s LOG_FILE_SIZE Maximum log file size in mega bytes, default maximum size is 1MB.<br /> -h display the help screen.<br /><br /></pre> +</div> +<p>Example :</p> +<div class="source"> +<pre> axis2_amqp_server -i 127.0.0.1 -p 5050 -r $AXIS2C_HOME -f /dev/stderr<br /><br /></pre> +</div> +</div> +<div class="subsection"> +<h3>19.3 Client Side</h3> +<ul> +</ul> +<p style="margin-bottom: 0in;"> +When the axis2_amqp_server is up and running, you can run the sample +clients in a new shell as follows.<br /> +<br /> +</p> +<pre>$ cd ${AXIS2C_HOME}/samples/bin/amqp<br /><br />$ ./echo_blocking<br /></pre> +This will invoke the echo service.<br /> +<br /> +To see the possible command line options for sample clients run them +with '-h' option<br /> +<p><a name="archive"></a></p> +</div> +</div> +<div class="section"><a name="19__Archive_Based_Deployment"></a> +<h2>20. Archive Based Deployment</h2> +<p>Axis2/C supports two main deployment models,<br /> +</p> +<ol> +<li>Directory Based Deployment</li> +<li>Archive Based Deployment</li> +</ol> +Our discussion in this section focuses on how to setup and use archive +based deployment in Axis2/C. By default, Axis2/C may be built without +enabling archive based deployment. Therefore, first and foremost you +will have to most probably rebuild from source. +<p>Also, it is requirement that you have zlib. Most Linux systems +do have zlib by default, but would require zlib development packages. +More information can be found <a href="http://www.zlib.net/">here</a>. +For MS Windows systems, you can download it from <a href="http://www.zlatkovic.com/pub/libxml">here</a>.</p> +<p>Next, you will have to build Axis2/C enabling Archive Based +Deployment. On Linux, you need to set the <code>--with-archive=[path_to_zlib_headers]</code></p> +<p>Example: <code><br /> +%./configure --with-archive=/usr/include/ --prefix=${AXIS2C_HOME}/deploy<br /> +%make<br /> +%make install<br /> +</code></p> +<p>On MS Windows, set <code>WITH_ARCHIVE = 1</code> +in the +<code>configure.in</code> file and run the <code>nmake +all</code> command. Please note that you have to specify the +directory where you can find the zlib binary, for a MS Windows system. +This can be done by setting the <code>ZLIB_BIN_DIR</code> +in the +<code>configure.in</code> file.</p> +</div> +<div class="subsection"><a name="19_1_Deploying_Services"></a> +<h3>20.1 Deploying Services</h3> +<p>Once you have successfully completed the installation, you +will have to deploy services as archives in order to make use of this +deployment model. Please note that directory based deployment can +coexist with the archive based deployment model. Therefore, you can +alternatively use either of the two.</p> +<p></p> +<p>You will merely have to add your existing service libraries +and the services.xml file into an archive. For example, in order to +deploy the sample echo service as an archive, you can zip the echo +folder found in the <code>AXIS2C_BIN_DIR/services</code> +directory. You can optionally rename your zip file, to have the <code>.aar</code> +extension.</p> +<p>Please note that all such services deployed as archives should +also be placed inside the <code>AXIS2C_BIN_DIR/services</code> +directory. Now, when ever you start your Simple Axis2 Server, or any +Axis2/C module attached to any other server, your services deployed as +archives, will also get loaded. +</p> +</div> +<div class="subsection"><a name="19_2_Deploying_Modules"></a> +<h3>20.2 Deploying Modules</h3> +<p>Similar to services, you also can deploy modules as archives. +You also can optionally rename your zip files to have the extension, <code>.mar</code> +as in service archives.</p> +<p>Your module archives must be placed in the <code>AXIS2C_BIN_DIR/modules</code> +directory.</p> +</div> +<div class="subsection"><a name="19_3_Known_Issues"></a> +<h3>20.3 Known Issues</h3> +<p>Please note that there are a few known issues when running +archive based deployment, mainly on Linux based systems.<br /> +</p> +<ul> +<li>If you want to run both client and server from same +respository, assign super-user privilideges for your server in order to +prevent un-zipped files getting overwritten, which will in return cause +a segmentation fault on your server. +<p></p> +</li> +<li>Please make sure that the application you choose to create +archives preserves executable rights, and symbolic links of libraries +that are found inside the archive, once unzipped.</li> +</ul> +<p style="margin-bottom: 0in;"><br /> +</p> +<p><a name="tcpmon"></a></p> +</div> +</div> +<div class="section"><a name="20__TCPMon_Tool"></a> +<h2>21. TCPMon Tool</h2> +<p>TCPMon is a TCP Monitor tool provided by Axis2/C for +monitoring payloads exchanged between client and server. If you are +using a source distribution, this may or may not be built for you by +default. Thus, to get started, you may require building it from source.</p> +<p>On Linux</p> +<div class="source"> +<pre> ./configure --prefix=${AXIS2C_HOME} --enable-tests=no<br /> make<br /></pre> +</div> +<p>On MS Windows</p> +<div class="source"> +<pre> nmake tcpmon<br /></pre> +</div> +<p>Please note that in most Linux based installations, this will +most probably be built for you. Once you've done with the building +process, you can find the executable at <code>${AXIS2C_HOME}/bin/tools</code> +on Linux, or at <code>%AXIS2C_HOME%\bin\tools</code> on MS +Windows.</p> +<p>By default, the TCPMon tool will listen on port <b><code>9090</code></b> +and reply to port <b><code>8080</code></b>. +The default target host will be <b><code>localhost</code></b> +and <b><code>tcpmon_traffic.log</code></b> +will be the default log_file. If you want to change any of these +settings run ./<code>tcpmon -h</code> on Linux, or <code>tcpmon.exe +-h</code> on MS Windows for more information.</p> +<p>The TCPMon tool does depend on the Axis2/C Util, Axis2/C AXIOM +and Axis2/C Parser libraries. Thus, if you want to use TCPMon to +monitor payloads in any other message transfer, independant of the +Axis2/C engine, you will have to build those dependant libraries too. +In addition to that, TCPMon does not depend on the Axis2/C Core and +installing the Axis2/C engine is not always a pre-requisite to run +TCPMon. +</p> +<p style="margin-bottom: 0in;"><br /> +</p> +<p><a name="appA"></a></p> +</div> +</div> +<div class="section"><a name="Appendix_A_-_axis2_xml"></a> +<h2>Appendix A - 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 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> +<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 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 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>Possible 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>Indicates 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 parameter can be changed from the code.</td> +</tr> +</tbody> +</table> +</td> +</tr> +</tbody> +</table> +</div> +<div class="subsection"><a name="transportReceiver"></a> +<h3>transportReceiver</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 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>Specifies which transport protocol is used</td> +<td>http (when using HTTP)</td> +</tr> +<tr class="a"> +<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 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> +<tr class="a"> +<td>exposeHeaders</td> +<td>Whether Transport Headers are exposed to a Service</td> +<td>true/false</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 parameter 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>Specifies which transport protocol is used when sending +messages</td> +<td>http(when using http)</td> +</tr> +<tr class="b"> +<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 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>Protocol version. Example:- HTTP /1.1, HTTP/1.0</td> +</tr> +</tbody> +</table> +</td> +</tr> +<tr class="a"> +<td>locked</td> +<td>Indicates 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 parameter 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 globally for every service deployed with Axis2/C.</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>Example : 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 a particular execution chain has to be +configured +using phaseOrder 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>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 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 handlers invoked for a message going out +of the system.</td> +</tr> +<tr class="b"> +<td>INfaultflow</td> +<td>Collection of handlers invoked for an incoming fault +message.</td> +</tr> +<tr class="a"> +<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 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>Transport, 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 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 the handler name. +<p>Example: AddressingbasedDispatcher, +RequestURIbaseddispatcher</p> +</td> +</tr> +<tr class="b"> +<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> +</div> +<div class="subsection"><a name="messageReceiver"></a> +<h3>messageReceiver</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>IN-OUT, IN-ONLY</td> +</tr> +<tr class="a"> +<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> +<p style="margin-bottom: 0in;"><br /> +</p> +<p><a name="appB"></a></p> +</div> +</div> +<div class="section"><a name="Appendix_B_-_services_xml"></a> +<h2>Appendix B - 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> +<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 or service group.</td> +<td>Depends on the service or the service group.<br /> +Examples: echo, sg_math</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 +elements.</p> +<table class="bodyTable"> +<caption></caption><tbody> +<tr class="a"> +<th>Attribute</th> +<th>Detail</th> +</tr> +<tr class="b"> +<td>name</td> +<td> +<table class="bodyTable"> +<caption></caption><tbody> +<tr class="b"> +<th>Description</th> +<th>Possible Value</th> +<th>Parameter Value</th> +</tr> +<tr class="a"> +<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 class="a"> +<td>Path of static WSDL to be attached with service</td> +<td>wsdl_path</td> +<td>Absolute path or path relative to AXIS2C_HOME/bin</td> +</tr> +<tr class="a"> +<td>Default HTTP Method used in a REST invocation</td> +<td>defaultRESTMethod</td> +<td>One of GET, POST, HEAD, PUT or DELETE</td> +</tr> +</tbody> +</table> +</td> +</tr> +<tr class="b"> +<td>locked</td> +<td> +<table class="bodyTable"> +<caption></caption><tbody> +<tr class="b"> +<th>Description</th> +<th>Possible Value</th> +</tr> +<tr class="a"> +<td>Indicates whether the parameter can be changed +from the code</td> +<td>true/false</td> +</tr> +</tbody> +</table> +</td> +</tr> +</tbody> +</table> +<p></p> +</div> +<div class="subsection"> +<p>The operations of the service are specified using operation +elements.</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>Example: echoString</td> +</tr> +<tr class="b"> +<td>mep</td> +<td>message exchange pattern uri. <p>This is defaulted to in-out MEP. For other MEPs, You need to specify the MEP.</p></td> +<td>Example: "http://www.w3.org/2004/08/wsdl/in-only"</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 class="bodyTable"> +<caption></caption><tbody> +<tr class="a"> +<th>Attribute</th> +<th>Detail</th> +</tr> +<tr class="b"> +<td>name</td> +<td> +<table class="bodyTable"> +<caption></caption><tbody> +<tr class="b"> +<th>Description</th> +<th>Possible Value</th> +<th>Parameter Value</th> +</tr> +<tr class="a"> +<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> +<tr class="a"> +<td>REST template mapping to the operation</td> +<td>RESTLocation</td> +<td>A template of the expected URL for the operation, +with compulsary parts and optional parts, well defined</td> +</tr> +<tr class="a"> +<td>HTTP Method used in a REST invocation</td> +<td>RESTMethod</td> +<td>One of GET, POST, HEAD, PUT or DELETE</td> +</tr> +</tbody> +</table> +</td> +</tr> +</tbody> +</table> +<p>Also, an <em>operation</em> element can have one +or more <em>actionMapping</em> element as sub elements.</p> +<table class="bodyTable"> +<caption></caption><tbody> +<tr class="a"> +<th>Description</th> +<th>Possible Values</th> +</tr> +<tr class="b"> +<td>Action mapping or an alias to an operation</td> +<td>Example: echoString</td> +</tr> +</tbody> +</table> +<p></p> +</div> +<div class="subsection"> +<p>An operation specific message receiver 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 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> +<p style="margin-bottom: 0in;"><br /> +</p> +<p><a name="appC"></a></p> +</div> +</div> +<div class="section"><a name="Appendix_C_-_module_xml"></a> +<h2>Appendix C - 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> +<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>Example- addressing</td> +</tr> +<tr class="a"> +<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> +</div> +<div class="subsection"><a name="parameter"></a> +<h3>parameter</h3> +<p>Any number of parameters can be present, depending 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>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> +</div> +<div class="subsection"><a name="Description"></a> +<h3>Description</h3> +<p>Describes the behavior of the module. This element is optional +and has no +attributes or sub elements.</p> +</div> +<div class="subsection"><a name="inflow"></a> +<h3>inflow</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 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>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 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>Indicates that the handler is the last handler of the +phase</td> +<td>true</td> +</tr> +<tr class="a"> +<td>phaseFirst</td> +<td>Indicates that the handler is the first handler of the +phase.</td> +<td>true</td> +</tr> +<tr class="b"> +<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 class="a"> +<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 class="bodyTable"> +<caption></caption><tbody> +<tr class="b"> +<th>Combination</th> +<th>Description</th> +</tr> +<tr class="a"> +<td>phaseLast</td> +<td>Indicates that the handler is the last handler of the +phase</td> +</tr> +<tr class="b"> +<td>phasefirst</td> +<td>Indicates that the handler is the first handler of the +phase.</td> +</tr> +<tr class="a"> +<td>before</td> +<td>Handler should be invoked before the handler, which is +specified by the before handler</td> +</tr> +<tr class="b"> +<td>after</td> +<td>Handler should be invoked after the handler, which is +specified by the 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><em>outflow</em>, <em>INfaultflow</em>, +<em>OUTfaultflow</em> elements +have the same syntax as that of <em>inflow</em>.</p> +</div> +<div class="subsection"><a name="operation"></a> +<h3>operation</h3> +<p>This is used when a module wants to add operations to a +service that +engages 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 operation (compulsory)</td> +<td>Depends on the module</td> +</tr> +<tr class="b"> +<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 style="margin-bottom: 0in;"><br /> +</p> +<p><a name="appD"></a></p> +</div> +</div> +<div class="section"><a name="Appendix_D_-_axis2_options"></a> +<h2>Appendix D - 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 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>Pointer to the options struct</td> +</tr> +<tr class="a"> +<td>const axutil_env_t *env</td> +<td>Pointer to the environment struct</td> +</tr> +<tr class="b"> +<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 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>Pointer to the options struct.</td> +</tr> +<tr class="a"> +<td>const axutil_env_t *env</td> +<td>Pointer to the environment struct.</td> +</tr> +<tr class="b"> +<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 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>Pointer to the options struct.</td> +</tr> +<tr class="a"> +<td>const axutil_env_t *env</td> +<td>Pointer to the environment struct.</td> +</tr> +<tr class="b"> +<td>axis2_endpoint_ref_t *from</td> +<td>Pointer to the endpoint reference struct representing +the from 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>Pointer to the options struct.</td> +</tr> +<tr class="a"> +<td>const axutil_env_t *env</td> +<td>Pointer to the environment struct.</td> +</tr> +<tr class="b"> +<td>axis2_endpoint_ref_t *to</td> +<td>Pointer to the endpoint reference struct representing +the to address.</td> +</tr> +</tbody> +</table> +<p><strong>axis2_options_set_transport_receiver(options, +env, +receiver)</strong></p> +<p>Sets the transport receiver in an OUT-IN message exchange +scenario.</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>Pointer to the options struct.</td> +</tr> +<tr class="a"> +<td>const axutil_env_t *env</td> +<td>Pointer to the environment struct.</td> +</tr> +<tr class="b"> +<td>axis2_transport_receiver_t *receiver</td> +<td>Pointer to the transport receiver struct.</td> +</tr> +</tbody> +</table> +<p><strong>axis2_options_set_transport_in(options, env, +transport_in)</strong></p> +<p>Sets the transport-in description.</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>Pointer to the options struct.</td> +</tr> +<tr class="a"> +<td>const axutil_env_t *env</td> +<td>Pointer to the environment struct.</td> +</tr> +<tr class="b"> +<td>axis2_transport_in_desc_t *transport_in</td> +<td>Pointer to the transport_in struct.</td> +</tr> +</tbody> +</table> +<p></p> +<p><strong>axis2_options_set_transport_in_protocol(options, +env, +transport_in_protocol)</strong></p> +<p>Sets the transport-in protocol.</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>Pointer to the options struct.</td> +</tr> +<tr class="a"> +<td>const axutil_env_t *env</td> +<td>Pointer to the environment struct.</td> +</tr> +<tr class="b"> +<td>const AXIS2_TRANSPORT_ENUMS transport_in_protocol</td> +<td>The value indicating the transport protocol.</td> +</tr> +</tbody> +</table> +<p></p> +<p><strong>axis2_options_set_message_id(options, env, +message_id)</strong></p> +<p>Sets the message ID.</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>The pointer to the options struct.</td> +</tr> +<tr class="a"> +<td>const axutil_env_t *env</td> +<td>The pointer to the environment struct.</td> +</tr> +<tr class="b"> +<td>const axis2_char_t *message_id</td> +<td>The message ID string.</td> +</tr> +</tbody> +</table> +<p></p> +<p><strong>axis2_options_set_properties(options, env, +properties)</strong></p> +<p>Sets the properties hash map.</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>Pointer to the options struct.</td> +</tr> +<tr class="a"> +<td>const axutil_env_t *env</td> +<td>Pointer to the environment struct.</td> +</tr> +<tr class="b"> +<td>axis2_hash_t *properties</td> +<td>Pointer to the properties hash map.</td> +</tr> +</tbody> +</table> +<p></p> +<p><strong>axis2_options_set_property(options, env, key, +property)</strong></p> +<p>Sets a property with a given key value.</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>Pointer to the options struct.</td> +</tr> +<tr class="a"> +<td>const axutil_env_t *env</td> +<td>Pointer to the environment struct.</td> +</tr> +<tr class="b"> +<td>const axis2_char_t *property_key</td> +<td>The property key string.</td> +</tr> +<tr class="a"> +<td>const void *property</td> +<td>Pointer to the property to be set.</td> +</tr> +</tbody> +</table> +<p></p> +<p><strong>axis2_options_set_relates_to(options, env, +relates_to)</strong></p> +<p>Sets the relates-to message information.</p> +<table class="bodyTable"> +<caption></caption><tbody> +<tr class="b"> +<th>Parameter</th> +<th>Description</th> +</tr> +<tr class="a"> +<td>axis2_options_t *options</td> +<td>Pointer to the options struct.</td> +</tr> +<tr class="b"> +<td>const axutil_env_t *env</td> +<td>Pointer to the environment struct.</td> +</tr> +<tr class="a"> +<td>axis2_relates_to_t *relates_to</td> +<td>Pointer to the relates_to struct.</td> +</tr> +</tbody> +</table> +<p></p> +<p><strong>axis2_options_set_reply_to(options, env, +reply_to)</strong></p> +<p>Sets the reply-to address, when the client wants a reply to be +sent to a +different end point.</p> +<table class="bodyTable"> +<caption></caption><tbody> +<tr class="b"> +<th>Parameter</th> +<th>Description</th> +</tr> +<tr class="a"> +<td>axis2_options_t *options</td> +<td>Pointer to the options struct.</td> +</tr> +<tr class="b"> +<td>const axutil_env_t *env</td> +<td>Pointer to the environment struct.</td> +</tr> +<tr class="a"> +<td>axis2_endpoint_ref_t *reply_to</td> +<td>Pointer to the endpoint reference struct representing +the reply-to address.</td> +</tr> +</tbody> +</table> +<p></p> +<p><strong>axis2_options_set_transport_out(options, env, +transport_out)</strong></p> +<p>Sets the transport-out description.</p> +<table class="bodyTable"> +<caption></caption><tbody> +<tr class="b"> +<th>Parameter</th> +<th>Description</th> +</tr> +<tr class="a"> +<td>axis2_options_t *options</td> +<td>Pointer to the options struct.</td> +</tr> +<tr class="b"> +<td>const axutil_env_t *env</td> +<td>Pointer to the environment struct.</td> +</tr> +<tr class="a"> +<td>axis2_transport_out_desc_t *transport_out</td> +<td>Pointer to the transport-out description struct.</td> +</tr> +</tbody> +</table> +<p></p> +<p><strong>axis2_options_set_sender_transport(options, env, +sender_transport, +conf)</strong></p> +<p>Sets the sender transport.</p> +<table class="bodyTable"> +<caption></caption><tbody> +<tr class="b"> +<th>Parameter</th> +<th>Description</th> +</tr> +<tr class="a"> +<td>axis2_options_t *options</td> +<td>Pointer to the options struct.</td> +</tr> +<tr class="b"> +<td>const axutil_env_t *env</td> +<td>Pointer to the environment struct.</td> +</tr> +<tr class="a"> +<td>const AXIS2_TRANSPORT_ENUMS sender_transport</td> +<td>The name of the sender transport to be set.</td> +</tr> +<tr class="b"> +<td>axis2_conf_t *conf</td> +<td>Pointer to the conf struct. It is from the conf that +the transport is picked with the given name.</td> +</tr> +</tbody> +</table> +<p></p> +<p><strong>axis2_options_set_soap_version_uri(options, env, +soap_version_uri)</strong></p> +<p>Sets the SOAP version URI.</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>Pointer to the options struct.</td> +</tr> +<tr class="a"> +<td>const axutil_env_t *env</td> +<td>Pointer to the environment struct.</td> +</tr> +<tr class="b"> +<td>const axis2_char_t *soap_version_uri</td> +<td>URI of the SOAP version to be set.</td> +</tr> +</tbody> +</table> +<p></p> +<p><strong>axis2_options_set_timeout_in_milli_seconds(options, +env, +timeout_in_milli_seconds)</strong></p> +<p>Sets the time out in milli seconds. This is used in +asynchronous message +exchange scenarios to specify how long the call back object is to wait +for +the response.</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>Pointer to the options struct.</td> +</tr> +<tr class="a"> +<td>const axutil_env_t *env</td> +<td>Pointer to the environment struct.</td> +</tr> +<tr class="b"> +<td>const long timeout_in_milli_seconds</td> +<td>Timeout in milli seconds.</td> +</tr> +</tbody> +</table> +<p></p> +<p><strong>axis2_options_set_transport_info(options, env, +sender_transport, +receiver_transport, user_separate_listener)</strong></p> +<p>Sets the transport information. Transport information includes +the name of +the sender transport, name of the receiver transport, and whether a +separate +listener is to be used to receive a response.</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>Pointer to the options struct.</td> +</tr> +<tr class="a"> +<td>const axutil_env_t *env</td> +<td>Pointer to the environment struct.</td> +</tr> +<tr class="b"> +<td>const AXIS2_TRANSPORT_ENUMS sender_transport</td> +<td>Name of the sender transport to be used.</td> +</tr> +<tr class="a"> +<td>const AXIS2_TRANSPORT_ENUMS receiver_transport</td> +<td>Name of the receiver transport to be used.</td> +</tr> +<tr class="b"> +<td>const axis2_bool_t use_separate_listener</td> +<td>bool value indicating whether to use a separate +listener or not.</td> +</tr> +</tbody> +</table> +<p></p> +<p><strong>axis2_options_set_use_separate_listener(options, +env, +use_separate_listener)</strong></p> +<p>Sets the bool value indicating whether to use a separate +listener or not. +A separate listener is used when the transport is a one-way transport +and the +message exchange pattern is two way.</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>Pointer to the options struct.</td> +</tr> +<tr class="a"> +<td>const axutil_env_t *env</td> +<td>Pointer to the environment struct.</td> +</tr> +<tr class="b"> +<td>const axis2_bool_t use_separate_listener</td> +<td>bool value indicating whether to use a separate +listener or not</td> +</tr> +</tbody> +</table> +<p></p> +<p><strong>axis2_options_set_soap_version(options, env, +soap_version)</strong></p> +<p>Sets the SOAP version.</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>Pointer to the options struct.</td> +</tr> +<tr class="a"> +<td>const axutil_env_t *env</td> +<td>Pointer to the environment struct.</td> +</tr> +<tr class="b"> +<td>const int soap_version</td> +<td>SOAP version, either AXIOM_SOAP11 or AXIOM_SOAP12.</td> +</tr> +</tbody> +</table> +<p></p> +<p><strong>axis2_options_set_enable_mtom(options, env, +enable_mtom)</strong></p> +<p>Enable or disable MTOM handling when sending binary +attachments.</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>Pointer to the options struct.</td> +</tr> +<tr class="a"> +<td>const axutil_env_t *env</td> +<td>Pointer to the environment struct.</td> +</tr> +<tr class="b"> +<td>axis2_bool_t enable_mtom</td> +<td>AXIS2_TRUE if MTOM is to be enabled, else AXIS2_FALSE</td> +</tr> +</tbody> +</table> +<p></p> +<p><strong>axis2_options_set_enable_rest(options, env, +enable_rest)</strong></p> +<p>Enable or disable REST support.</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>Pointer to the options struct.</td> +</tr> +<tr class="a"> +<td>const axutil_env_t *env</td> +<td>Pointer to the environment struct.</td> +</tr> +<tr class="b"> +<td>axis2_bool_t enable_rest</td> +<td>AXIS2_TRUE if REST is to be enabled, else AXIS2_FALSE</td> +</tr> +</tbody> +</table> +<p><strong>axis2_options_set_http_auth_info(options, env, +username, password, auth_type)</strong></p> +<p>Sets HTTP Authentication information.</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>Pointer to the options struct.</td> +</tr> +<tr class="a"> +<td>const axutil_env_t *env</td> +<td>Pointer to the environment struct.</td> +</tr> +<tr class="b"> +<td>const axis2_char_t *username</td> +<td>String representing username</td> +</tr> +<tr class="a"> +<td>const axis2_char_t *password</td> +<td>String representing password.</td> +</tr> +<tr class="b"> +<td>const axis2_char_t *auth_type</td> +<td>use "Basic" to force basic authentication and "Digest" +to force digest authentication or NULL for not forcing authentication</td> +</tr> +</tbody> +</table> +<p><strong>axis2_options_set_proxy_auth_info(options, env, +username, password, auth_type)</strong></p> +<p>Sets Proxy Authentication information.</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>Pointer to the options struct.</td> +</tr> +<tr class="a"> +<td>const axutil_env_t *env</td> +<td>Pointer to the environment struct.</td> +</tr> +<tr class="b"> +<td>const axis2_char_t *username</td> +<td>String representing username</td> +</tr> +<tr class="a"> +<td>const axis2_char_t *password</td> +<td>String representing password.</td> +</tr> +<tr class="b"> +<td>const axis2_char_t *auth_type</td> +<td>use "Basic" to force basic authentication and "Digest" +to force digest authentication or NULL for not forcing authentication</td> +</tr> +</tbody> +</table> +<p><strong>axis2_options_set_test_http_auth(options, env, +test_http_auth)</strong></p> +<p>Enables testing of HTTP Authentication information.</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>Pointer to the options struct.</td> +</tr> +<tr class="a"> +<td>const axutil_env_t *env</td> +<td>Pointer to the environment struct.</td> +</tr> +<tr class="b"> +<td>const axis2_bool_t test_http_auth</td> +<td>bool value indicating whether to test or not, +AXIS2_TRUE to enable, AXIS2_FALSE to disable</td> +</tr> +</tbody> +</table> +<p><strong>axis2_options_set_test_proxy_auth(options, env, +test_proxy_auth)</strong></p> +<p>Enables testing of proxy Authentication information.</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>Pointer to the options struct.</td> +</tr> +<tr class="a"> +<td>const axutil_env_t *env</td> +<td>Pointer to the environment struct.</td> +</tr> +<tr class="b"> +<td>const axis2_bool_t test_proxy_auth</td> +<td>bool value indicating whether to test or not, +AXIS2_TRUE to enable, AXIS2_FALSE to disable</td> +</tr> +</tbody> +</table> +</div> +<div class="clear"> +<hr /></div> +</div> + +</body></html> |