| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| <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://axis.apache.org/axis2/c/core/" 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:c-dev@axis.apache.org">c-dev@axis.apache.org</a>). |
| Subscription |
| details are available on the <a href="http://axis.apache.org/axis2/c/core/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://axis.apache.org/axis2/c/core/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://axis.apache.org/axis2/c/core/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.7.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.7.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.7.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.7.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>--with-openssl=[path to Openssl installation directory]</code> |
| option.</p> |
| <p>Example <code><br /> |
| %./configure --with-openssl=/opt/openssl --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="https://svn.apache.org/repos/asf/axis/axis2/java/core/trunk" class="externalLink" title="External Link">Axis2/Java |
| SVN</a> revision 529533 or later revisions. You can download the <a href="http://axis.apache.org/axis2/java/core/download.cgi" class="externalLink" title="External Link">Axis2/Java latest |
| release</a> and use those binaries to generate the code. Check out a <a href="http://axis.apache.org/axis2/java/core/docs/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> |
| <p> |
| <em>Note: You can use the WSDL2C.sh or WSDL2C.bat that shipped with the axis2/c binaries |
| (inside the <axis2_src_dir>/bin/tools/wsdl2c directory) to run the tool. |
| The README comes in the directory guide you how to use that scripts.</em></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://axis.apache.org/axis2/java/core/docs/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
|