You are viewing a plain text version of this content. The canonical link for it is here.
Posted to axis-cvs@ws.apache.org by pi...@apache.org on 2007/12/17 13:28:08 UTC
svn commit: r604854 - in /webservices/axis2/trunk/c/xdocs/docs:
axis2c_manual.html installationguide.html
Author: pini
Date: Mon Dec 17 04:28:07 2007
New Revision: 604854
URL: http://svn.apache.org/viewvc?rev=604854&view=rev
Log:
Fixing jira issue 836
Modified:
webservices/axis2/trunk/c/xdocs/docs/axis2c_manual.html
webservices/axis2/trunk/c/xdocs/docs/installationguide.html
Modified: webservices/axis2/trunk/c/xdocs/docs/axis2c_manual.html
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/c/xdocs/docs/axis2c_manual.html?rev=604854&r1=604853&r2=604854&view=diff
==============================================================================
--- webservices/axis2/trunk/c/xdocs/docs/axis2c_manual.html (original)
+++ webservices/axis2/trunk/c/xdocs/docs/axis2c_manual.html Mon Dec 17 04:28:07 2007
@@ -25,6 +25,8 @@
Libxml2 is installed is referred to as LIBXML2_INSTALL_DIR</li>
</ul>
+<p style="margin-bottom: 0in"><br>
+</p>
<h1 class="western"><a name="toc">Axis2/C Manual - Contents</a></h1>
<ol>
<li><a href="#quick_start">Quick Start Guide</a></li>
@@ -41,6 +43,8 @@
<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="#appA">Appendix A - axis2.xml</a></li>
@@ -48,6 +52,9 @@
<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>
<a name="quick_start"></a>
<h1>1. Quick Start Guide</h1>
@@ -358,10 +365,10 @@
purpose of the repository contents.</p>
<table border="1">
- <caption>Axis2/C Repository Sub-folders</caption>
+ <caption>Axis2/C Repository Contents</caption>
<tbody>
<tr>
- <th>Folder Name</th>
+ <th>Folder/File Name</th>
<th>Description</th>
</tr>
<tr>
@@ -376,7 +383,7 @@
</td>
</tr>
<tr>
- <td><p>modules</p>
+ <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
@@ -390,7 +397,7 @@
</td>
</tr>
<tr>
- <td><p>services</p>
+ <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
@@ -448,7 +455,7 @@
name, set of handlers, the flows into which those handlers are to be added,
etc.</p>
-<h2>2.1 Service Folders</h2>
+<h2>2.2 Service Folders</h2>
<p>All the services are placed inside the services folder of the repository,
and each service will be in one of the sub folders within the services
@@ -475,6 +482,9 @@
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>
<a name="svc_api"></a>
<h1>3. Service API</h1>
@@ -527,7 +537,7 @@
on_fault)(
axis2_svc_skeleton_t *svc_skeli,
const axutil_env_t *env,
- axiom_node_t *node); </pre>
+ axiom_node_t *node);</pre>
</td>
<td>This method is called by the engine if a fault is detected.</td>
</tr>
@@ -551,6 +561,35 @@
<code>axis2_remove_instance</code> in the shared library for clean up
purposes.</p>
+<table border="1">
+ <caption></caption>
+ <tbody>
+ <tr>
+ <th>Function Signature</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <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>
+ <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>
+
<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
@@ -561,6 +600,9 @@
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>
<a name="client_api"></a>
<h1>4. Client API</h1>
@@ -607,47 +649,75 @@
<p></p>
-<h3><code>axis2_svc_client_fire_and_forget</code></h3>
-
-<p>Sends a message and forgets about it. This method is used to interact with
-a service operation whose MEP is In-Only. There is no way of getting an error
-from the service using this method. However, you may still get client-side
-errors, such as host unknown.</p>
-
-<h3><code>axis2_svc_client_send_robust</code></h3>
-
-<p>This method too is used to interact with a service operation whose MEP is
-In-Only. However, unlike <code>axis2_svc_client_fire_and_forget</code>, this
-function reports an error back to the caller if a fault triggers on the
-server side.</p>
-
-<p>When using Out-In MEP, the client expects a reply from the server.
-<code>axis2_svc_client_send_receive</code> and
-<code>axis2_svc_client_send_receive_non_blocking<code>
-</code></code>functions support this MEP<code><code>.</code></code></p>
-
-<h3><code>axis2_svc_client_send_receive</code></h3>
-
-<p>This method is used to interact with a service operation whose MEP is
-In-Out. It sends an XML request and receives an XML response.</p>
-
-<p>Returns a pointer to the AXIOM node representing the XML response. This
-method blocks the client until the response arrives.</p>
-
-<h3><code>axis2_send_receive_non_blocking</code></h3>
-
-<p>This method too, is used to interact with a service operation whose MEP is
-In-Out. It sends an XML request and receives an XML response, but the client
-does not block for the response.</p>
-
-<p>In this method, the client does not block for the response, but instead it
-expects the user to set a call back to capture the response.<br>
-</p>
+<table border="1">
+ <caption></caption>
+ <tbody>
+ <tr>
+ <th>Function Signature</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <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>
+ <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 />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>
+ <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 />Returns
+ a pointer to the AXIOM node representing the XML response. This method
+ blocks the client until the response arrives.</td>
+ </tr>
+ <tr>
+ <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 />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 function signatures of the above mentioned functions.</p>
+more information on the above mentioned functions, as well as their synonyms
+that accept an operation's qualified name.</p>
-<h3>Synchronous vs. Asynchronous Behavior (Blocking/Non-Blocking)</h3>
+<h2>4.1 Synchronous vs. Asynchronous Behavior (Blocking/Non-Blocking)</h2>
<p>This will determine whether the client would block for the response
(synchronous) or return immediately expecting the response to be handled by a
@@ -658,7 +728,7 @@
asynchronous mode.<br>
</p>
-<h3>Two-Way or One-Way Transport</h3>
+<h2>4.2 Two-Way or One-Way Transport</h2>
<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
@@ -675,6 +745,9 @@
<p>Please see <a href="#appD">Appendix D</a> for further details on setting
options.</p>
+
+<p style="margin-bottom: 0in"><br>
+</p>
<a name="rest"></a>
<h1>5. REST</h1>
@@ -697,6 +770,9 @@
<p>Please have a look at the <code>echo_rest</code> sample for a complete
source code on how to use REST.</p>
+
+<p style="margin-bottom: 0in"><br>
+</p>
<a name="mtom"></a>
<h1>6. MTOM</h1>
@@ -742,6 +818,9 @@
<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>
+</p>
<a name="engaging_module"></a>
<h1>7. Engaging a Module</h1>
@@ -777,7 +856,7 @@
<p>The following is an example of engaging a sample module called the logging
module with Axis2/C:</p>
-<h3>Writing the module.xml File</h3>
+<h2>7.1 Writing the module.xml File</h2>
<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
@@ -806,7 +885,7 @@
of the in flow. The LoggingOutHandler is placed into the MessageOut phase of
both the out flow and the fault out flow.</p>
-<h3>Packaging and Deploying the Module</h3>
+<h2>7.2 Packaging and Deploying the Module</h2>
<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
@@ -815,7 +894,7 @@
above, the name of the shared library file should be libaxis2_mod_log.so on
Linux and axis2_mod_log.dll on MS Windows.</p>
-<h3>Adding Module Specific Phases to the axis2.xml File</h3>
+<h2>7.3 Adding Module Specific Phases to the axis2.xml File</h2>
<p>Module specific phases have to be added after the system predefined
phases. The following example shows where to add the module specific phases.
@@ -830,7 +909,7 @@
the module specific handlers are added to system predefined phases as
specified in the module.xml file.</p>
-<h3>Engaging a Module to a Services</h3>
+<h2>7.4 Engaging a Module to a Services</h2>
<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
@@ -859,7 +938,7 @@
in a module can check whether the module has been engaged to a particular
service, and act accordingly.</p>
-<h3>Engaging a Module Globally</h3>
+<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
@@ -867,7 +946,7 @@
handlers associated with the module for every message coming in or going out
for all the services deployed.</p>
-<h3>Engaging a Module on the Client Side</h3>
+<h2>7.5 Engaging a Module on the Client Side</h2>
<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
@@ -880,6 +959,9 @@
<p>Remember to replace "module-name" with the name of the module you want to
engage. For example to engage the logging module you can use:</p>
<pre>axis2_svc_client_engage_module(svc_client, env, "logging");</pre>
+
+<p style="margin-bottom: 0in"><br>
+</p>
<a name="ws_addressing"></a>
<h1>8. WS-Addressing</h1>
@@ -936,6 +1018,9 @@
<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>
<a name="writing_module"></a>
<h1>9. Writing a Module</h1>
@@ -957,26 +1042,40 @@
<p>Every module should have three basic functions that are defined as
function pointer members of the <code>axis2_module_ops</code> struct. This
struct is defined in the <code>axis2_module.h</code> header file.</p>
-<ol>
- <li><pre>axis2_status_t (AXIS2_CALL *
+
+<table border="1">
+ <caption></caption>
+ <tbody>
+ <tr>
+ <th>Function Signature</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td><pre>axis2_status_t (AXIS2_CALL *
init)(axis2_module_t *module, const
axutil_env_t *env,
axis2_conf_ctx_t *conf_ctx,
- axis2_module_desc_t *module_desc)</pre>
- <p>This function takes care of the module initialization.</p>
- </li>
- <li><pre>axis2_status_t (AXIS2_CALL *
+ axis2_module_desc_t *module_desc);</pre>
+ </td>
+ <td>This function takes care of the module initialization.</td>
+ </tr>
+ <tr>
+ <td width="410"><pre>axis2_status_t (AXIS2_CALL *
shutdown)(axis2_module_t *module,
- const axutil_env_t *env )</pre>
- <p>Shuts down and cleans up the module.</p>
- </li>
- <li><pre>axis2_status_t (AXIS2_CALL *
+ const axutil_env_t *env );</pre>
+ </td>
+ <td>Shuts down and cleans up the module.</td>
+ </tr>
+ <tr>
+ <td><pre>axis2_status_t (AXIS2_CALL *
fill_handler_create_func_map)(axis2_module_t *module,
- const axutil_env_t *env )</pre>
- <p>This function fills the hash map of the handler create functions for
- the module.</p>
- </li>
-</ol>
+ 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
@@ -995,7 +1094,7 @@
two handlers. The in handler and the out handler that deals with logging
along with the in-flow and out-flow respectively.</p>
-<h3>Writing Handlers</h3>
+<h2>9.1 Writing Handlers</h2>
<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.
@@ -1018,7 +1117,7 @@
is similar to the in handler, except that it is placed along the out-flow
when deployed.</p>
-<h3>Writing the module.xml File</h3>
+<h2>9.2 Writing the module.xml File</h2>
<p>After writing the module, the module.xml file should be written. The
module.xml file contains all the configuration details for a particular
@@ -1027,6 +1126,9 @@
<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>
<a name="simple_axis_server"></a>
<h1>10. Simple Axis Server</h1>
@@ -1051,11 +1153,14 @@
<p>Example :</p>
<pre> axis2_http_server -l 3 -p 8080 -r $AXIS2C_HOME -f /dev/stderr</pre>
+
+<p style="margin-bottom: 0in"><br>
+</p>
<a name="mod_axis2"></a>
<h1>11. Deploying with Apache HTTP Server Version 2.x</h1>
-<h3>Linux Platform</h3>
+<h2>11.1 Linux Platform</h2>
<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
@@ -1074,7 +1179,7 @@
<p>This will install mod_axis2.so into your AXIS2C_INSTALL_DIR/lib folder.</p>
-<h3>MS Windows Platform</h3>
+<h2>11.2 MS Windows Platform</h2>
<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.
@@ -1091,7 +1196,7 @@
<pre>nmake axis2_apache_module</pre>
This will build mod_axis2.dll and copy it to AXIS2C_INSTALL_DIR\lib directory.
-<h3>Deploying mod_axis2</h3>
+<h2>11.3 Deploying mod_axis2</h2>
<p><font color="#666666">NOTE: To execute some of the commands given below,
you might require super user privileges on your machine.</font></p>
@@ -1180,7 +1285,10 @@
usually placed in the AXIS2C_INSTALL_DIR/logs folder.</li>
</ul>
+<p style="margin-bottom: 0in"><br>
+</p>
<a name="IIS"></a>
+
<h1>12. Deploying with Microsoft IIS Server</h1>
<p>Use the Axis2/C VC project or makefile to buid the
component.</a></p>
@@ -1213,10 +1321,12 @@
mod_axis2_IIS.dll as a filter in your IIS/PWS web site and restart the IIS
admin service.</p>
+<p style="margin-bottom: 0in"><br>
+</p>
<a name="ssl_client"></a>
<h1>13. Using SSL Client</h1>
-<h2>Building and Configuring the Client</h2>
+<h2>13.1 Building and Configuring the Client</h2>
<p>In order to allow an Axis2/C client to communicate with an SSL enabled
server, we need to compile Axis2/C with SSL support enabled.</p>
@@ -1234,9 +1344,10 @@
<p>On MS Windows, set <code>ENABLE_SSL=1</code> in the
<code>configure.in</code> file and run the 'nmake all' command.</p>
+
<a name="client_chain"></a>
-<h3>Creating the Client Certificate Chain File</h3>
+<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
@@ -1254,7 +1365,7 @@
<p>On MS Windows, you can do this by copying the contents of client.crt and
client.key files and saving them in a file named client.pem using Notepad.</p>
-<h3>Configuration</h3>
+<h3>13.1.2 Configuration</h3>
<p>Uncomment the following in the <code>axis2.xml</code> file. This will
enable the SSL transport for Axis2/C, by recognizing "https" in an end point
@@ -1298,11 +1409,11 @@
openssl s_client -connect <servername>:<port> 2>&1 |\
sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > cert.pem</pre>
-<p>NOTE: Instead of setting these parameters in the <code>axis2.xml</code>
+<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.</p>
+code.</font></p>
-<h3>Configuring the Server</h3>
+<h2>13.2 Configuring the Server</h2>
<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
@@ -1322,9 +1433,12 @@
SSLVerifyClient require<br>
SSLVerifyDepth 1</code></p>
-<p>NOTE: The last two lines, <code>SSLVerifyClient</code> and
+<p><font color="#666666">NOTE: The last two lines, <code>SSLVerifyClient</code> and
<code>SSLVerifyDepth</code> are only needed when you need client
-authentication.</p>
+authentication.</font></p>
+
+<p style="margin-bottom: 0in"><br>
+</p>
<a name="proxy"></a>
<h1>14. Using Proxy Support</h1>
@@ -1333,16 +1447,16 @@
settings:</p>
<ol>
<li>Specify proxy settings in axis2.xml</li>
- <li>Provide proxy settings using service client API</il></li>
+ <li>Provide proxy settings using service client API</li>
</ol>
-<h3>Specifying Proxy Settings in axis2.xml</h3>
+<h2>14.1 Specifying Proxy Settings in axis2.xml</h2>
<pre><transportSender name="http" class="axis2_http_sender">
<parameter name="PROTOCOL" locked="false">HTTP/1.1</parameter>
- <parameter name="PROXY" proxy_host="127.0.0.1" proxy_port="8080" locked="true"/>
+ <parameter name="PROXY" proxy_host="127.0.0.1" proxy_port="8080" proxy_username="" proxy_password="" locked="true"/>
</transportSender></pre>
-<h3>Providing Proxy Settings Using Service Client API</h3>
+<h2>14.2 Providing Proxy Settings Using Service Client API</h2>
<p>You can specify proxy settings using the following function with the
service client:</p>
@@ -1350,9 +1464,88 @@
const axutil_env_t *env,
axis2_char_t *proxy_host,
axis2_char_t *proxy_port);</pre>
+
+<p style="margin-bottom: 0in"><br>
+</p>
+<a name="proxy_auth"></a>
+
+<h1>15. Using Proxy Authentication Support</h1>
+
+<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>
+
+<h2>15.1 Specifying Proxy Settings with Authentication in axis2.xml</h2>
+<pre><transportSender name="http" class="axis2_http_sender">
+ <parameter name="PROTOCOL" locked="false">HTTP/1.1</parameter>
+ <parameter name="PROXY" proxy_host="127.0.0.1" proxy_port="8080" <b>proxy_username="your username" proxy_password="your password"</b> locked="true"/>
+</transportSender></pre>
+
+<h2>15.2 Providing Proxy Settings with Authentication Using Service Client API</h2>
+
+<p>You can specify proxy authentication settings using the following function with the
+service client:</p>
+<pre>axis2_svc_client_set_proxy_with_auth(axis2_svc_client_t *svc_client,
+ const axutil_env_t *env,
+ axis2_char_t *proxy_host,
+ axis2_char_t *proxy_port,
+ axis2_char_t *username,
+ axis2_char_t *password);</pre>
+
+<h2>15.3 Providing Proxy Authentication Settings Using Service Client Options</h2>
+
+<p>You can specify proxy authentication settings using the following function with the
+service client options:</p>
+<pre>axis2_options_set_proxy_auth_info(
+ axis2_options_t * options,
+ const axutil_env_t * env,
+ const axis2_char_t * username,
+ const axis2_char_t * password,
+ const axis2_char_t * auth_type);</pre>
+<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>
+
+<p style="margin-bottom: 0in"><br>
+</p>
+<a name="http_auth"></a>
+
+<h1>16. Using HTTP Authentication Support</h1>
+
+<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>
+
+<h2>16.1 Specifying HTTP Authentication Settings in axis2.xml</h2>
+<pre><transportSender name="http" class="axis2_http_sender">
+ <parameter name="PROTOCOL" locked="false">HTTP/1.1</parameter>
+ <parameter name="HTTP-Authentication" username="your username" password="your password" locked="true"/>
+</transportSender></pre>
+
+<h2>16.2 Providing HTTP Authentication Settings Using Service Client Options</h2>
+
+<p>You can specify HTTP authentication settings using the following function with the
+service client options:</p>
+<pre>axis2_options_set_http_auth_info(
+ axis2_options_t * options,
+ const axutil_env_t * env,
+ const axis2_char_t * username,
+ const axis2_char_t * password,
+ const axis2_char_t * auth_type);</pre>
+<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>
+
+<p style="margin-bottom: 0in"><br>
+</p>
<a name="wsdl2c"></a>
-<h1>15. WSDL2C Tool</h1>
+<h1>17. WSDL2C Tool</h1>
<p>WSDL2C tool that comes with Axis2/Java supports the generation of Axis2/C
stubs and skeletons for WSDL files. This is a Java tool that can be used to
@@ -1367,7 +1560,7 @@
<p>Before you run the tool, make sure that all the .jar library files that
come with Axis2/Java are added to the CLASSPATH environment variable.</p>
-<h2>Generating Service Skeletons</h2>
+<h2>17.1 Generating Service Skeletons</h2>
<p>The tool can be run with the following parameters and generate the service
skeleton and other required files with ADB (Axis Data Binding) support.</p>
@@ -1397,7 +1590,7 @@
You can also go through the generated header files and understand the API in
line with the WSDL file that you used to generate the code.
-<h2>Generating Client Stubs</h2>
+<h2>17.2 Generating Client Stubs</h2>
<p>The WSDL2C code generator tool provides support for generating client
stubs as well. You can generate the required stubs from a given WSDL with the
@@ -1414,62 +1607,56 @@
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>
<a name="tcptrans"></a>
-<h1>TCP Transport</h1>
-<h2>Building AXIS2C enabling TCP</h2>
-<p>This will Guide you to install Axis2C by enabling tcp and how to
- check it by running samples</p>
+<h1>18. TCP Transport</h1>
+
+<h2>18.1 Building AXIS2C enabling TCP</h2>
+<p>This section will guide you through installing Axis2C with tcp enabled, and this
+also includes how to test it by running samples.</p>
<ol>
-<li>If you are going to install using configure you have use the
- configure command by tcp enabling by giving following argument</li>
-<pre>
- ./configure --enable-tcp=yes
+<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
make
- make install
-</pre>
+ make install</pre>
-<li>Then to confirm that you have successfully built with tcp enable
- you can check in your lib folder for following files</li>
-<pre>
- ls $AXIS2C_HOME/lib/
- libaxis2_tcp_sender.so
- libaxis2_tcp_reciever.so
-</pre>
-
-<h2>Server Side</h2>
-<li>Then you have to edit the axis2.xml by uncommenting following entry.</li>
-<pre>
- <transportSender name="tcp" class="axis2_tcp_sender">
+<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
+ libaxis2_tcp_reciever.so</pre>
+</ol>
+<h2>18.2 Server Side</h2>
+<ul>
+<li>To setup the server side, you have to edit the axis2.xml by uncommenting
+following entry:</li>
+<pre> <transportSender name="tcp" class="axis2_tcp_sender">
<parameter name="PROTOCOL" locked="false">TCP</parameter>
- </transportSender>
-</pre>
-
-<li>Then for tcp you have to start the tcp server which runs in 9091
- as default port.</li>
-<pre>
- cd $AXIS2C_HOME/bin/
- ./axis2_tcp_server
-</pre>
-
-<h2>Client Side</h2>
-<li>If your clients are in different location then you have to do the
- same modification to axis2.xml as you did in the server side.</li>
+ </transportSender></pre>
+<li>To run the tcp server, you have to start the tcp server which runs in 9091
+ as its default port.</li>
+<pre> cd $AXIS2C_HOME/bin/
+ ./axis2_tcp_server</pre>
+</ul>
+<h2>18.3 Client Side</h2>
+<ul>
<li>In your service client you have to give the end point address
- adding URI Schema name as tcp in the client code.</li>
-<pre>
- tcp://[service_hostname]:[service_port]/axis2/services/your_service_name
-</pre>
+ 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 message goes without having
- it's http headers when you build Axis2C by enabling tcp.</li>
-</ol>
+<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>
<a name="appA"></a>
-<h1>Appendix A</h1>
-<h2 style="margin-bottom: 0in">axis2.xml</h2>
+
+<h1>Appendix A - axis2.xml</h1>
<p>The axis2.xml file is the configuration file for Axis2/C. It has 6 top
level elements. They are <em>parameter, transportReceiver, transportSender,
@@ -1875,7 +2062,7 @@
<tr>
<td>name</td>
<td>Specifies the name of the phase</td>
- <td>TransportIn, Dispatch, PreDispatch, PostDispatch, MessageOut
+ <td>Transport, Dispatch, PreDispatch, PostDispatch, MessageOut
<p>User defined phases (can have a user defined name)</p>
</td>
@@ -1949,11 +2136,12 @@
</tr>
</tbody>
</table>
-<a name="appB"></a>
-<h1>Appendix B</h1>
+<p style="margin-bottom: 0in"><br>
+</p>
+<a name="appB"></a>
-<h2 style="margin-bottom: 0in">services.xml</h2>
+<h1>Appendix B - services.xml</h1>
<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
@@ -2119,11 +2307,12 @@
</tr>
</tbody>
</table>
-<a name="appC"></a>
-<h1>Appendix C</h1>
+<p style="margin-bottom: 0in"><br>
+</p>
+<a name="appC"></a>
-<h2 style="margin-bottom: 0in">module.xml</h2>
+<h1>Appendix C - module.xml</h1>
<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>
@@ -2352,12 +2541,11 @@
message is intended for. If it is not set, the default message receiver is
used.</p>
-<p></p>
+<p style="margin-bottom: 0in"><br>
+</p>
<a name="appD"></a>
-<h1>Appendix D</h1>
-
-<h2 style="margin-bottom: 0in">axis2_options</h2>
+<h1>Appendix D - axis2_options</h1>
<p>This section describes various types of options that can be set with
<code>axis2_options</code>. These options are used by the service client
@@ -2988,6 +3176,76 @@
</tbody>
</table>
-<p></p>
+<p><strong>axis2_options_set_http_auth_info(options, env,
+username, password, auth_type)</strong></p>
+
+<p>Sets HTTP Authentication information.</p>
+
+<table border="1">
+ <caption></caption>
+ <tbody>
+ <tr>
+ <th>Parameter</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>axis2_options_t *options</td>
+ <td>Pointer to the options struct.</td>
+ </tr>
+ <tr>
+ <td>const axutil_env_t *env</td>
+ <td>Pointer to the environment struct.</td>
+ </tr>
+ <tr>
+ <td>const axis2_char_t *username</td>
+ <td>String representing useranme</td>
+ </tr>
+ <tr>
+ <td>const axis2_char_t *password</td>
+ <td>String representing password.</td>
+ </tr>
+ <tr>
+ <td>const axis2_char_t *auth_type</td>
+ <td>use "Basic" to force basic authentication and "Digest" to
+ force digest authentication or NULL for not forcing authentication</td>
+ </tr>
+ </tbody>
+</table>
+
+<p><strong>axis2_options_set_proxy_auth_info(options, env,
+username, password, auth_type)</strong></p>
+
+<p>Sets Proxy Authentication information.</p>
+
+<table border="1">
+ <caption></caption>
+ <tbody>
+ <tr>
+ <th>Parameter</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>axis2_options_t *options</td>
+ <td>Pointer to the options struct.</td>
+ </tr>
+ <tr>
+ <td>const axutil_env_t *env</td>
+ <td>Pointer to the environment struct.</td>
+ </tr>
+ <tr>
+ <td>const axis2_char_t *username</td>
+ <td>String representing useranme</td>
+ </tr>
+ <tr>
+ <td>const axis2_char_t *password</td>
+ <td>String representing password.</td>
+ </tr>
+ <tr>
+ <td>const axis2_char_t *auth_type</td>
+ <td>use "Basic" to force basic authentication and "Digest" to
+ force digest authentication or NULL for not forcing authentication</td>
+ </tr>
+ </tbody>
+</table>
</body>
</html>
Modified: webservices/axis2/trunk/c/xdocs/docs/installationguide.html
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/c/xdocs/docs/installationguide.html?rev=604854&r1=604853&r2=604854&view=diff
==============================================================================
--- webservices/axis2/trunk/c/xdocs/docs/installationguide.html (original)
+++ webservices/axis2/trunk/c/xdocs/docs/installationguide.html Mon Dec 17 04:28:07 2007
@@ -47,8 +47,9 @@
remember to prefix the subject with [Axis2].</p>
-
-<h2>Contents</h2>
+<p style="margin-bottom: 0in"><br>
+</p>
+<h1>Contents</h1>
<ul>
@@ -78,11 +79,13 @@
</ul>
+<p style="margin-bottom: 0in"><br>
+</p>
<a id="linux"></a>
-<h2>1. Installing and Running on Linux</h2>
+<h1>1. Installing and Running on Linux</h1>
@@ -108,7 +111,7 @@
-<h3>1.1. Installing the Binary Distribution</h3>
+<h2>1.1. Installing the Binary Distribution</h2>
@@ -126,9 +129,9 @@
<ul>
- <li>AXIS2C_HOME='/your_path_to_axis2c'</li>
+ <li><code>AXIS2C_HOME='/your_path_to_axis2c'</code></li>
- <li>export AXIS2C_HOME</li>
+ <li><code>export AXIS2C_HOME</code></li>
<p><strong>Note:</strong> You will need to set the AXIS2C_HOME only if
@@ -152,15 +155,15 @@
<ul>
- <li>cd /your_path_to_axis2c/bin</li>
+ <li><code>cd /your_path_to_axis2c/bin</code></li>
- <li>./axis2_http_server</li>
+ <li><code>./axis2_http_server</code></li>
</ul>
</li>
- <li>To see the possible command line options run ./axis2_http_server -h
+ <li>To see the possible command line options run <code>./axis2_http_server -h</code>
<p><strong>Note:</strong> If you run into shared library problems,
@@ -170,9 +173,9 @@
<ul>
- <li>LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/your_path_to_axis2c/lib</li>
+ <li><code>LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/your_path_to_axis2c/lib</code></li>
- <li>export LD_LIBRARY_PATH</li>
+ <li><code>export LD_LIBRARY_PATH</code></li>
</ul>
@@ -186,13 +189,13 @@
<ul>
- <li>cd /your_path_to_axis2c/bin/samples</li>
+ <li><code>cd /your_path_to_axis2c/bin/samples</code></li>
<li>To run the client for echo service
<ul>
- <li>./echo</li>
+ <li><code>./echo</code></li>
</ul>
@@ -202,7 +205,7 @@
<ul>
- <li>./math</li>
+ <li><code>./math</code></li>
</ul>
@@ -218,9 +221,9 @@
<ul>
- <li>LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/your_path_to_axis2c/lib</li>
+ <li><code>LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/your_path_to_axis2c/lib</code></li>
- <li>export LD_LIBRARY_PATH</li>
+ <li><code>export LD_LIBRARY_PATH</code></li>
</ul>
@@ -234,7 +237,7 @@
-<h3>1.2. Installing the Source Distribution</h3>
+<h2>1.2. Installing the Source Distribution</h2>
@@ -252,9 +255,9 @@
<ul>
- <li>AXIS2C_HOME='/your_desired_path_to_axis2c_installation'</li>
+ <li><code>AXIS2C_HOME='/your_desired_path_to_axis2c_installation'</code></li>
- <li>export AXIS2C_HOME</li>
+ <li><code>export AXIS2C_HOME</code></li>
<p><strong>Note:</strong> You will have to set AXIS2C_HOME only if you
@@ -272,7 +275,7 @@
<ul>
- <li>cd /your_path_to_axis2c_source</li>
+ <li><code>cd /your_path_to_axis2c_source</code></li>
</ul>
@@ -288,19 +291,19 @@
<ul>
- <li>./configure</li>
+ <li><code>./configure</code></li>
- <li>make</li>
+ <li><code>make</code></li>
- <li>make install</li>
+ <li><code>make install</code></li>
</ul>
</li>
- <li>Use './configure --help' for possible command line options.</li>
+ <li>Use <code>./configure --help</code> for possible command line options.</li>
- <li><strong>Note:</strong> If you do not provide a --prefix configure
+ <li><strong>Note:</strong> If you do not provide a <code>--prefix</code> configure
option, the default installation would be in the /usr/local/axis2c
@@ -308,17 +311,17 @@
<li>You may have to try Axis2/C with Guththila XML parser. You can do
- that by providing the --enable-guththila=yes option when configuring.
+ that by providing the <code>--enable-guththila=yes</code> option when configuring.
<ul>
- <li>./configure --enable-guththila=yes [other configuration
+ <li><code>./configure --enable-guththila=yes</code> [other configuration
options]</li>
- <li>make</li>
+ <li><code>make</code></li>
- <li>make install</li>
+ <li><code>make install</code></li>
</ul>
@@ -332,27 +335,27 @@
<ul>
- <li>LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path_you_installed_axis2c/lib/</li>
+ <li><code>LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path_you_installed_axis2c/lib/</code></li>
- <li>export LD_LIBRARY_PATH</li>
+ <li><code>export LD_LIBRARY_PATH</code></li>
- <li>cd samples</li>
- <li>./configure --prefix=${AXIS2C_HOME}
- --with-axis2=$AXIS2C_HOME}/include/axis2-1.2 </li>
+ <li><code>cd samples</code></li>
+ <li><code>./configure --prefix=${AXIS2C_HOME}
+ --with-axis2=$AXIS2C_HOME}/include/axis2-1.2</code></li>
- <li>make</li>
+ <li><code>make</code></li>
- <li>make install</li>
+ <li><code>make install</code></li>
</ul>
</li>
- <li>Please run "./configure --help" in the samples folder for more
+ <li>Please run <code>./configure --help</code> in the samples folder for more
information on the configure options.</li>
- <li><strong>Note:</strong> If you do not provide a --prefix configure
+ <li><strong>Note:</strong> If you do not provide a <code>--prefix</code> configure
option, by default, the samples will be installed into the
@@ -374,17 +377,17 @@
<ul>
- <li>cd /path_you_installed_axis2c/bin</li>
+ <li><code>cd /path_you_installed_axis2c/bin</code></li>
- <li>./axis2_http_server</li>
+ <li><code>./axis2_http_server</code></li>
</ul>
</li>
- <li>To see the possible command line options, run ./axis2_http_server
+ <li>To see the possible command line options, run <code>./axis2_http_server
- -h</li>
+ -h</code></li>
<li><strong>Note:</strong> You may have to be logged in as a superuser
@@ -400,13 +403,13 @@
<ul>
- <li>cd /path_you_installed_axis2c/bin/samples</li>
+ <li><code>cd /path_you_installed_axis2c/bin/samples</code></li>
<li>To run the client for the echo service
<ul>
- <li>./echo</li>
+ <li><code>./echo</code></li>
</ul>
@@ -416,7 +419,7 @@
<ul>
- <li>./math</li>
+ <li><code>./math</code></li>
</ul>
@@ -432,11 +435,13 @@
</ol>
+<p style="margin-bottom: 0in"><br>
+</p>
<a id="win"></a>
-<h2>2. Installing and Running on Microsoft Windows</h2>
+<h1>2. Installing and Running on Microsoft Windows</h1>
@@ -456,11 +461,11 @@
-<h3>2. 1. Installing the Binary Distribution </h3>
+<h2>2.1. Installing the Binary Distribution </h2>
-<h4>2.1.1. Requirements</h4>
+<h3>2.1.1. Requirements</h3>
<ul>
@@ -504,7 +509,7 @@
-<h4>2.1.2. Binaries in the Release</h4>
+<h3>2.1.2. Binaries in the Release</h3>
<ul>
@@ -552,7 +557,7 @@
-<h4>2.1.3. Running the Binaries</h4>
+<h3>2.1.3. Running the Binaries</h3>
<ul>
@@ -588,7 +593,7 @@
<li>(<strong>Note</strong>: You can provide command line options to change
- the default behavior. Use the command "axis2_http_server.exe -h" to learn
+ the default behavior. Use the command <code>axis2_http_server.exe -h</code> to learn
about the usage)</li>
@@ -608,11 +613,11 @@
-<h3>2. 2. Installing Source Distribution</h3>
+<h2>2.2. Installing the Source Distribution</h2>
-<h4>2.2.1. Requirements</h4>
+<h3>2.2.1. Requirements</h3>
<ul>
@@ -658,7 +663,7 @@
-<h4>2.2.3. Editing the configure.in File</h4>
+<h3>2.2.2. Editing the configure.in File</h3>
@@ -706,7 +711,7 @@
file.<br />
- Example: ENABLE_GUTHTHILA = 1<br />
+ Example: <code>ENABLE_GUTHTHILA = 1</code><br />
<br />
@@ -724,7 +729,7 @@
-<h4>2.2.4. Compiling the Source</h4>
+<h3>2.2.3. Compiling the Source</h3>
@@ -740,7 +745,7 @@
<li>Open a DOS shell</li>
- <li>cd C:\axis2c\build\win32</li>
+ <li><code>cd C:\axis2c\build\win32</code></li>
<li>to access .Net tools, run
@@ -804,7 +809,7 @@
</ul>
-<p>Please note that "nmake install" does not build the apache or the IIS module. Refer to <a href="axis2c_manual.html">Axis2/C manual</a> to see how to install these modules.</p>
+<p>Please note that <code>nmake install</code> does not build the apache or the IIS module. Refer to <a href="axis2c_manual.html">Axis2/C manual</a> to see how to install these modules.</p>
<p>
@@ -814,7 +819,7 @@
-<h4>2.2.5. Running the Binaries</h4>
+<h3>2.2.4. Running the Binaries</h3>
<ul>
---------------------------------------------------------------------
To unsubscribe, e-mail: axis-cvs-unsubscribe@ws.apache.org
For additional commands, e-mail: axis-cvs-help@ws.apache.org