You are viewing a plain text version of this content. The canonical link for it is here.
Posted to java-dev@axis.apache.org by su...@apache.org on 2008/07/21 07:35:33 UTC
svn commit: r678352 [2/5] - in /webservices/axis2/site/c: ./ api/ docs/
docs/hello/client/ docs/hello/service/ docs/mod_log/
Modified: webservices/axis2/site/c/docs/axis2c_manual.html
URL: http://svn.apache.org/viewvc/webservices/axis2/site/c/docs/axis2c_manual.html?rev=678352&r1=678351&r2=678352&view=diff
==============================================================================
--- webservices/axis2/site/c/docs/axis2c_manual.html (original)
+++ webservices/axis2/site/c/docs/axis2c_manual.html Sun Jul 20 22:35:32 2008
@@ -2,1796 +2,3023 @@
@import url("../style/maven-base.css");
@import url("../style/maven-classic.css");</style><link rel="stylesheet" href="../style/print.css" type="text/css" media="print"></link><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"></meta></head><body class="composite"><div id="banner"><a href="http://www.apache.org/" id="organizationLogo"><img alt="Apache Software Foundation" src="http://www.apache.org/images/asf-logo.gif"></img></a><a href="http://ws.apache.org/axis2/c" id="projectLogo"><img alt="Apache Axis2/C" src="http://ws.apache.org/axis2/images/axis.jpg"></img></a><div class="clear"><hr></hr></div></div><div id="breadcrumbs"><div class="xleft">
- Last published: 07 May 2008
- | Doc for 1.4.0</div><div class="xright"></div><div class="clear"><hr></hr></div></div><div id="leftColumn"><div id="navcolumn"><div id="menuApache_Axis2_C"><h5>Apache Axis2/C</h5><ul><li class="none"><a href="../index.html">Apache Axis2/C Home</a></li><li class="expanded"><a href="../download.cgi">Download Axis2/C</a><ul><li class="none"><a href="../download.cgi">Releases</a></li></ul></li><li class="expanded"><a href="../docs/index.html">Documentation</a><ul><li class="none"><a href="../docs/installationguide.html">Installation Guide</a></li><li class="none"><a href="../docs/axis2c_manual.html">Axis2/C manual</a></li><li class="none"><a href="../docs/faq.html">Axis2/C FAQ</a></li></ul></li><li class="expanded"><a href="../lists_issues.html">Get Involved</a><ul><li class="none"><a href="../lists_issues.html">Mailing Lists & Issue Tracking</a></li><li class="none"><a href="../svn.html">Checkout Source Code</a></li></ul></li><li class="expanded"><a href=
"../coding_conventions.html">Developer Guidelines</a><ul><li class="none"><a href="../coding_conventions.html">Coding Convention</a></li><li class="none"><a href="../versioning.html">Versionning</a></li></ul></li><li class="expanded"><a href="../team-list.html">Project Information</a><ul><li class="none"><a href="../team-list.html">Project Team</a></li><li class="none"><a href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/c/" class="externalLink" title="External Link">Source Code</a></li></ul></li></ul></div><a href="http://maven.apache.org/" title="Built by Maven" id="poweredBy"><img alt="Built by Maven" src="../images/logos/maven-button-1.png"></img></a></div></div><div id="bodyColumn"><div class="contentBox"><div class="section"><a name="Preamble"></a><h2>Preamble</h2><p style="margin-bottom: 0in">This document is intended to be a reference
-manual for <a href="http://ws.apache.org/axis2/c" class="externalLink" title="External Link">Apache Axis2/C</a>. This
+ Last published: 21 July 2008
+ | Doc for 1.5.0</div><div class="xright"></div><div class="clear"><hr></hr></div></div><div id="leftColumn"><div id="navcolumn"><div id="menuApache_Axis2_C"><h5>Apache Axis2/C</h5><ul><li class="none"><a href="../index.html">Apache Axis2/C Home</a></li><li class="expanded"><a href="../download.cgi">Download Axis2/C</a><ul><li class="none"><a href="../download.cgi">Releases</a></li></ul></li><li class="expanded"><a href="../docs/index.html">Documentation</a><ul><li class="none"><a href="../docs/installationguide.html">Installation Guide</a></li><li class="none"><a href="../docs/axis2c_manual.html">Axis2/C manual</a></li><li class="none"><a href="../docs/faq.html">Axis2/C FAQ</a></li></ul></li><li class="expanded"><a href="../lists_issues.html">Get Involved</a><ul><li class="none"><a href="../lists_issues.html">Mailing Lists & Issue Tracking</a></li><li class="none"><a href="../svn.html">Checkout Source Code</a></li></ul></li><li class="expanded"><a href=
"../coding_conventions.html">Developer Guidelines</a><ul><li class="none"><a href="../coding_conventions.html">Coding Convention</a></li><li class="none"><a href="../versioning.html">Versionning</a></li></ul></li><li class="expanded"><a href="../team-list.html">Project Information</a><ul><li class="none"><a href="../team-list.html">Project Team</a></li><li class="none"><a href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/c/" class="externalLink" title="External Link">Source Code</a></li></ul></li></ul></div><a href="http://maven.apache.org/" title="Built by Maven" id="poweredBy"><img alt="Built by Maven" src="../images/logos/maven-button-1.png"></img></a></div></div><div id="bodyColumn"><div class="contentBox"><div class="section"><a name="Preamble"></a><h2>Preamble</h2><p style="margin-bottom: 0in;">This document is intended
+to be a reference
+manual for <a href="http://ws.apache.org/axis2/c" class="externalLink" title="External Link">Apache
+Axis2/C</a>. This
manual details how Axis2/C can be used to provide and consume Web
-services.</p><p style="margin-bottom: 0in">Please send your feedback to the Apache Axis2/C
-developer mailing list (<a href="mailto:axis-c-dev@apache.org">axis-c-dev@apache.org</a>). Subscription
-details are available on the <a href="http://ws.apache.org/axis2/c/mail-lists.html" class="externalLink" title="External Link">Apache Axis2/C website</a>.</p><p>This document uses the following conventions:</p><ul>
- <li>The directory each package is installed in is given with an
- "_INSTALL_DIR" suffix to the package name. For example, the path in which
- Libxml2 is installed is referred to as LIBXML2_INSTALL_DIR</li>
-</ul><p style="margin-bottom: 0in"><br></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="#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></br>
-</p><p><a name="quick_start"></a></p></div><div class="section"><a name="1__Quick_Start_Guide"></a><h2>1. Quick Start Guide</h2><p>This section is aimed to help you get a Web service running in a short
-time using Axis2/C, and consume that service using an Axis2/C client.</p><p>First, <a href="http://ws.apache.org/axis2/c/download.cgi" class="externalLink" title="External Link">download</a>
-the latest binary release from Apache Axis2/C. Once you download the correct
-binary that suits your platform, all that you require to get it running is to
+services.</p><p style="margin-bottom: 0in;">Please send your feedback
+to the Apache Axis2/C
+developer mailing list (<a href="mailto:axis-c-dev@apache.org">axis-c-dev@apache.org</a>).
+Subscription
+details are available on the <a href="http://ws.apache.org/axis2/c/mail-lists.html" class="externalLink" title="External Link">Apache
+Axis2/C website</a>.</p><p>This document uses the following conventions:</p><ul>
+<li>The directory each package is installed in is given with an
+"_INSTALL_DIR" suffix to the package name. For example, the path in
+which Libxml2 is installed is referred to as LIBXML2_INSTALL_DIR</li>
+</ul><p style="margin-bottom: 0in;"><br></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></br>
+</p>
+<p><a name="quick_start"></a></p>
+</div><div class="section"><a name="1__Quick_Start_Guide"></a>
+<h2>1. Quick Start Guide</h2>
+<p>This section is aimed to help you get a Web service running in
+a short
+time using Axis2/C, and consume that service using an Axis2/C client.</p>
+<p>First, <a href="http://ws.apache.org/axis2/c/download.cgi" class="externalLink" title="External Link">download</a>
+the latest binary release from Apache Axis2/C. Once you download the
+correct
+binary that suits your platform, all that you require to get it running
+is to
extract the package to a folder of your choice, and set the AXIS2C_HOME
-environment variable to point to this extracted folder. For Linux, you may
+environment variable to point to this extracted folder. For Linux, you
+may
have to set the LD_LIBRARY_PATH environment variable to include the lib
-folder (e.g. add $AXIS2C_HOME/lib). For MS Windows, you will have to add the
-lib folder to your PATH variable to include the Axis2/C DLLs to your path.</p><p>Now you should be able to change the directory to the bin folder of the
-extracted folder, and run the simple axis server in one command shell. Then
-change the directory to bin/samples in another command shell and run any of
-the samples there (you may have to set the environment variables in this new
+folder (e.g. add $AXIS2C_HOME/lib). For MS Windows, you will have to
+add the
+lib folder to your PATH variable to include the Axis2/C DLLs to your
+path.</p>
+<p>Now you should be able to change the directory to the bin
+folder of the
+extracted folder, and run the simple axis server in one command shell.
+Then
+change the directory to bin/samples in another command shell and run
+any of
+the samples there (you may have to set the environment variables in
+this new
shell as well). Please see the <a href="http://ws.apache.org/axis2/c/docs/installationguide.html" 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
+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>
- Hello Service!
- <greet>
-
-</pre></div>
- <p>Response:</p>
- <div class="source"><pre> <greetResponse>
- Hello Client!
- <greetResponse>
-</pre></div>
- <br></br><p>The steps to be followed when implementing a service with Axis2/C
-include:</p><ol>
- <li><b>Implement the functions corresponding to the operations of the
- service.</b> <br></br>
- In our sample, we will have one function that implements the "greet"
- operation. <br></br>
- We 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></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></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></br>
- </li>
- <li><b>Implement the create function, that would create an instance of the
- service skeleton</b><br></br>
- The create function would create an axis2_svc_skeleton and assign the
- respective function pointers to map the axis2_svc_skeleton interface to
- our interface implementation methods explained in the above step.<br></br>
- </li>
- <li><b>Implement axis2_get_instance and axis2_remove_instance
- functions</b><br></br>
- These functions are used to create and destroy service instances by the
- engine, and each service must define these functions.<br></br>
- </li>
- <li><b>Write the services.xml file for the service</b><br></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></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></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.
+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></br> Hello Service!<br></br> <greet><br></br><br></br></pre>
+</div>
+<p>Response:</p>
+<div class="source">
+<pre> <greetResponse><br></br> Hello Client!<br></br> <greetResponse><br></br></pre>
+</div>
+<br></br>
+<p>The steps to be followed when implementing a service with
+Axis2/C
+include:</p>
+<ol>
+<li><b>Implement the functions corresponding to the
+operations of the service.</b> <br></br>
+In our sample, we will have one function that implements the "greet"
+operation. <br></br>
+We 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></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></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></br>
+</li>
+<li><b>Implement the create function, that would create
+an instance of the service skeleton</b><br></br>
+The create function would create an axis2_svc_skeleton and assign the
+respective function pointers to map the axis2_svc_skeleton interface to
+our interface implementation methods explained in the above step.<br></br>
+</li>
+<li><b>Implement axis2_get_instance and
+axis2_remove_instance functions</b><br></br>
+These functions are used to create and destroy service instances by the
+engine, and each service must define these functions.<br></br>
+</li>
+<li><b>Write the services.xml file for the service</b><br></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></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></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
+<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></br>
+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></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
+<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
+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
+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">
- <parameter name="ServiceClass" locked="xsd:false">hello</parameter>
- <description>
- Quick start guide hello service sample.
- </description>
- <operation name="greet"/>
-</service>
-
-</pre></div>
- <p>The service configuration shown above specifies that the name of the
+<div class="source">
+<pre><service name="hello"><br></br> <parameter name="ServiceClass" locked="xsd:false">hello</parameter><br></br> <description><br></br> Quick start guide hello service sample.<br></br> </description><br></br> <operation name="greet"/><br></br></service><br></br><br></br></pre>
+</div>
+<p>The service configuration shown above specifies that the name
+of the
service is hello. <br></br>
-The value of the "ServiceClass", "hello" in this case, will be mapped to the
-service implementation by the deployment engine as libhello.so on Linux or
-hello.dll on MS Windows. The description element contains a brief description
+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></br>
-There can be one or more operation elements. For this sample, we only have
+There can be one or more operation elements. For this sample, we only
+have
one operation, with the name "greet".<br></br>
-</p></div><div class="subsection"><a name="1_1_6_Compiling_the_Service"></a><h3>1.1.6 Compiling the Service</h3><p>You can compile the service sample as shown below.</p><p>On Linux:</p>
- <div class="source"><pre>gcc -shared -olibhello.so -I$AXIS2C_HOME/include/axis2-1.2/ -L$AXIS2C_HOME/lib -laxutil -laxis2_axiom -laxis2_parser -laxis2_engine -lpthread -laxis2_http_sender -laxis2_http_receiver hello_svc.c
-
-</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
-
-</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
-
-</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
+</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.2/ -L$AXIS2C_HOME/lib -laxutil -laxis2_axiom -laxis2_parser -laxis2_engine -lpthread -laxis2_http_sender -laxis2_http_receiver hello_svc.c<br></br><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><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><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>
+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></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></br>
- </li>
- <li><b>Create an options instance, and set options</b>.<br></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></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></br>
- </li>
- <li><b>Set options to service client instance</b><br></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></br>
- </li>
- <li><b>Send the request and receive the response</b><br></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></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></br>
- Process the response in line with the client business logic.</li>
-</ol></div><div class="subsection"><a name="1_2_1_Creating_and_Setting_Options"></a><h3>1.2.1 Creating and Setting Options</h3>
- <div class="source"><pre> options = axis2_options_create(env);
- address = "http://localhost:9090/axis2/services/hello";
- endpoint_ref = axis2_endpoint_ref_create(env, address);
- axis2_options_set_to(options, env, endpoint_ref);
-
-</pre></div>
- <p>In the above section of code, an <code>axis2_options</code> instance is
+<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></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></br>
+</li>
+<li><b>Create an options instance, and set options</b>.<br></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></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></br>
+</li>
+<li><b>Set options to service client instance</b><br></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></br>
+</li>
+<li><b>Send the request and receive the response</b><br></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></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></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></br> address = "http://localhost:9090/axis2/services/hello";<br></br> endpoint_ref = axis2_endpoint_ref_create(env, address);<br></br> axis2_options_set_to(options, env, endpoint_ref);<br></br><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);
- axis2_svc_client_set_options(svc_client, env, options);
- payload = build_om_request(env);
- ret_node = axis2_svc_client_send_receive(svc_client, env, payload);
-
-</pre></div>
- <p>After creating and preparing the options, the next step is to create a
+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></br> axis2_svc_client_set_options(svc_client, env, options);<br></br> payload = build_om_request(env);<br></br> ret_node = axis2_svc_client_send_receive(svc_client, env, payload);<br></br><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.2/ -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
-
-</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
-
-</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
-
-</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></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=""></img><p>Here the name of the repository folder is axis2c_repo. In your system, you
+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.2/ -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><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><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><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></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=""></img>
+<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></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></br>
- At deployment, the Axis2/C deployment engine would traverse the
- modules folders to find out what modules are available.<br></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></br>
- At deployment, the Axis2/C deployment engine will traverse the
- services folders to find out what services are available.<br></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></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
+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></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></br>
+At deployment, the Axis2/C deployment engine would traverse the modules
+folders to find out what modules are available.<br></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></br>
+At deployment, the Axis2/C deployment engine will traverse the services
+folders to find out what services are available.<br></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></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></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
+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></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
+</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,
+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. 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
+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></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
+operations for each service, etc.</p>
+<p style="margin-bottom: 0in;"><br></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 *
- init)(axis2_svc_skeleton_t *svc_skeleton,
- const axutil_env_t *env);</pre>
- </td><td>Initializes the service skeleton object instance. The Axis2/C
- engine initializes a service skeleton instance once per deployed
- service, during the first request made to the service.</td></tr>
- <tr class="a"><td width="410"><pre>axiom_node_t *(AXIS2_CALL*
- invoke )( axis2_svc_skeleton_t *svc_skeli,
- const axutil_env_t *env,
- axiom_node_t *node,
- axis2_msg_ctx_t *msg_ctx);</pre>
- </td><td>Invokes the service implementation. You have to implement the logic
- to call the correct functions in this method based on the name of the
- operation being invoked.</td></tr>
- <tr class="b"><td><pre>axiom_node_t *(AXIS2_CALL*
- on_fault)(
- axis2_svc_skeleton_t *svc_skeli,
- const axutil_env_t *env,
- axiom_node_t *node);</pre>
- </td><td>This method is called by the engine if a fault is detected.</td></tr>
- <tr class="a"><td><pre>axis2_status_t (AXIS2_CALL *
- free )( axis2_svc_skeleton_t *svc_skeli,
- const axutil_env_t *env);</pre>
- </td><td>Frees the service implementation instance.</td></tr>
- </tbody></table><br></br><p>There are two more methods that a service should implement. Once a service
+<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></br> init)(axis2_svc_skeleton_t *svc_skeleton,<br></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></br> invoke )( axis2_svc_skeleton_t *svc_skeli,<br></br> const axutil_env_t *env,<br></br> axiom_node_t *node,<br></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></br> on_fault)(<br></br> axis2_svc_skeleton_t *svc_skeli,<br></br> const axutil_env_t *env,<br></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></br> free )( axis2_svc_skeleton_t *svc_skeli,<br></br> const axutil_env_t *env);</pre>
+</td><td>Frees the service implementation instance.</td></tr>
+</tbody></table>
+<br></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
+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
-axis2_get_instance(
- axis2_svc_skeleton_t ** inst,
- 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
-axis2_remove_instance(
- axis2_svc_skeleton_t * inst,
- 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></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></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,
+<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></br>axis2_get_instance(<br></br> axis2_svc_skeleton_t ** inst,<br></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></br>axis2_remove_instance(<br></br> axis2_svc_skeleton_t * inst,<br></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></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></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
+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
- axis2_svc_client_fire_and_forget(
- axis2_svc_client_t * svc_client,
- const axutil_env_t * env,
- 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
- axis2_svc_client_send_robust(
- axis2_svc_client_t * svc_client,
- const axutil_env_t * env,
- 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></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
- axis2_svc_client_send_receive(
- axis2_svc_client_t * svc_client,
- const axutil_env_t * env,
- 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></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
- axis2_svc_client_send_receive_non_blocking(
- axis2_svc_client_t * svc_client,
- const axutil_env_t * env,
- const axiom_node_t * payload,
- 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></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></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
+<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></br> axis2_svc_client_fire_and_forget(<br></br> axis2_svc_client_t * svc_client,<br></br> const axutil_env_t * env,<br></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></br> axis2_svc_client_send_robust(<br></br> axis2_svc_client_t * svc_client,<br></br> const axutil_env_t * env,<br></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></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></br> axis2_svc_client_send_receive(<br></br> axis2_svc_client_t * svc_client,<br></br> const axutil_env_t * env,<br></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></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></br> axis2_svc_client_send_receive_non_blocking(<br></br> axis2_svc_client_t * svc_client,<br></br> const axutil_env_t * env,<br></br> const axiom_node_t * payload,<br></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></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></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></br>
-<code>axis2_svc_client_send_receive</code> operates in synchronous mode,
-whereas <code>axis2_svc_client_send_receive_non_blocking</code> operates in
+<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></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
+</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></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
+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></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
+<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></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
+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></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
+</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);
-
-</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
+<div class="source">
+<pre>axis2_options_set_enable_rest(options, env, AXIS2_TRUE);<br></br><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);
-
-</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
+<div class="source">
+<pre>axis2_options_set_http_method(options, env, AXIS2_HTTP_GET);<br></br><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></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></br>
-<div class="source"><pre><operation name="locate">
- <parameter name="RESTMethod">GET</parameter>
- <parameter name="RESTLocation">location/{lat}/{long}</parameter>
-</operation>
-
-</pre></div>
-</p><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></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></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
+</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></br>
+</p>
+<div class="source">
+<pre><operation name="locate"><br></br> <parameter name="RESTMethod">GET</parameter><br></br> <parameter name="RESTLocation">location/{lat}/{long}</parameter><br></br></operation><br></br><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></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></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>
- <ns1:mtomSample xmlns:ns1="http://ws.apache.org/axis2/c/samples/mtom">
- <ns1:fileName>test.jpg</ns1:fileName>
- <ns1:image>
- <xop:Include xmlns:xop="http://www.w3.org/2004/08/xop/include"
- href="cid:1.f399248e-8b39-1db1-3124-0015c53de2e5@apache.org"></xop:Include>
- </ns1:image>
- </ns1:mtomSample>
-</soapenv:Body>
-
-</pre></div>
- <p>In the above sample payload shown, we place our image file as text within
+<div class="source">
+<pre><soapenv:Body><br></br> <ns1:mtomSample xmlns:ns1="http://ws.apache.org/axis2/c/samples/mtom"><br></br> <ns1:fileName>test.jpg</ns1:fileName><br></br> <ns1:image><br></br> <xop:Include xmlns:xop="http://www.w3.org/2004/08/xop/include" <br></br> href="cid:1.f399248e-8b39-1db1-3124-0015c53de2e5@apache.org"></xop:Include><br></br> </ns1:image><br></br> </ns1:mtomSample><br></br></soapenv:Body><br></br><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);
-data_handler = axiom_data_handler_create(env, image_name, "image/jpeg");
-data_text = axiom_text_create_with_data_handler(env, image_om_node, data_handler, &data_om_node);
-
-</pre></div>
- <p>When sending attachments, you can configure the client either to send the
-attachment in the optimized format or non-optimized format.</p><p>To do this, set the option <code>axis2_options_set_enable_mtom(options,
+<div class="source">
+<pre>image_om_ele = axiom_element_create(env, mtom_om_node, "image", ns1, &image_om_node);<br></br>data_handler = axiom_data_handler_create(env, image_name, "image/jpeg");<br></br>data_text = axiom_text_create_with_data_handler(env, image_om_node, data_handler, &data_om_node);<br></br><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
+<code><enableMtom>true</enableMtom> </code>in
+axis2.xml</p>
+<p>If enableMTOM is set to True, the attachment is sent as it is,
+out of the
+SOAP body, using MIME headers. Also the payload will have an
+XOP:Include
+element, referring to the MIME part that contains the binary
+attachment.
+Sending the attachment as it is, in pure binary format, is called
+binary
optimized format. In the case of binary non-optimized format, where
-enableMTOM is False, the attachment content is sent in the payload itself, as
-a base64 encoded string.</p><p>Please have a look at the <code>mtom</code> sample for a complete example
-on how to use MTOM.</p><p style="margin-bottom: 0in"><br></br>
-</p><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.
+enableMTOM is False, the attachment content is sent in the payload
+itself, as
+a base64 encoded string.</p>
+<p>Please have a look at the <code>mtom</code>
+sample for a complete example
+on how to use MTOM.</p>
+<p style="margin-bottom: 0in;"><br></br>
+</p>
+<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
+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
+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>
[... 3194 lines stripped ...]