1.1 Hello Service

Let's see how you can write your first Web service with Axis2/C and how to deploy it.

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:

Request:

 <greet>
 Hello Service!
 <greet>

Response:

 <greetResponse>
 Hello Client!
 <greetResponse>

The steps to be followed when implementing a service with Axis2/C include:

1. Implement the functions corresponding to the operations of the service.
   In our sample, we will have one function that implements the "greet" operation.
   We will name that function axis2_hello_greet.
2. Implement the functions defined by the axis2_svc_skeleton interface
   axis2_svc_skeleton interface expects the functions init, invoke, on_fault and free to be implemented by our service.
   In our sample, we would implement those and name them as hello_init, hello_invoke, hello_on_fault and hello_free respectively.
   
3. Implement the create function, that would create an instance of the service skeleton
   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.
   
4. Implement axis2_get_instance and axis2_remove_instance functions
   These functions are used to create and destroy service instances by the engine, and each service must define these functions.
   
5. Write the services.xml file for the service
   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.
   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.
   

1.1.1 Operation Implementation

Look for the axis2_hello_greet function in the hello_svc.c source file.

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 axiom_node, process it to understand the request logic, and prepares the response as an axiom_node and returns that.

1.1.2 Skeleton Create Method

Look for the axis2_hello_create function in the hello_svc.c source file.

The create function creates and returns a new axis2_svc_skeleton 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.

1.1.3 Invoking Operation Implementation

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.

Look for the hello_invoke function in the hello_svc.c source file.

In our implementation of the hello_invoke, 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.
The Axis2/C engine will call the invoke method with an axiom_node, containing the request payload, and axis2_msg_ctx instance, containing the message context information, in addition to the service skeleton and the environment pointers. We can use the message context to extract whatever information we deem necessary that is related to the incoming message. The Axis2/C engine expects the invoke method to return a pointer to an axiom_node, representing the response payload.

1.1.4 Full Source

Here is the complete source code for the service : hello_svc.c

1.1.5 Service Descriptor

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.

<service name="hello">
 <parameter name="ServiceClass" locked="xsd:false">hello</parameter>
 <description>
 Quick start guide hello service sample.
 </description>
 <operation name="greet"/>
</service>

The service configuration shown above specifies that the name of the service is hello.
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.
There can be one or more operation elements. For this sample, we only have one operation, with the name "greet".

1.1.6 Compiling the Service

You can compile the service sample as shown below.

On Linux:

gcc -shared -olibhello.so -I$AXIS2C_HOME/include/axis2-1.6.0/ -L$AXIS2C_HOME/lib -laxutil -laxis2_axiom -laxis2_parser -laxis2_engine -lpthread -laxis2_http_sender -laxis2_http_receiver hello_svc.c

On MS Windows:

to compile,

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

to link,

link.exe /nologo /LIBPATH:%AXIS2C_HOME%\lib axutil.lib axiom.lib axis2_parser.lib axis2_engine.lib /DLL /OUT:hello.dll *.obj

1.1.7 Deploying the Service

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.

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 http://localhost:9090/axis2/services. You should get an entry for the hello service on the page that is displayed.

1.1.8 Providing a WSDL for the Service

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.

1. Adding the WSDL file to the folder in which the service DLL is found.
2. Providing the path of the WSDL file in the services.xml.

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 wsdl_path parameter in the services.xml file. More info on how this can be done is found under the services.xml section.

An example of the second option can be found the services.xml of the echo sample service, which is commented. An example of the first option in use is seen in the Calculator sample service.

The static WSDL file can be accessed by appending ?wsdl to the service end-point. You can view the WSDL provided for the Calculator sample, by pointing to http://localhost:9090/axis2/services/Calculator?wsdl.

1.2 Hello Client

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.

The steps to be followed when implementing a client with Axis2/C:

1. Create the environment to be used by the client.
   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 axutil_env_create_all method can be used to create a default, ready to use environment instance.
   
2. Create an options instance, and set options.
   The axis2_options 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.
3. Create a service client instance, giving the client repository folder as a parameter.
   The axis2_svc_client 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 repository is explained in detail in a later section.
   
4. Set options to service client instance
   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.
   
5. Send the request and receive the response
   The service client's axis2_svc_client_send_receive method can be used to invoke the send receive operation on the service client instance.
   The send receive operation takes the request payload as an axiom_node and returns the response payload as an axiom_node.
6. Process the response
   Process the response in line with the client business logic.

1.2.1 Creating and Setting Options

 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);

In the above section of code, an axis2_options 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.

1.2.2 Using Service Client

 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);

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 ret_node, which is a pointer to an axiom_node that can be used to process the response further.

1.2.3 Full Source

Here is the complete source code for the client : hello.c

1.2.4 Compiling the Client

You can compile the client sample as shown below.

On Linux:

gcc -o hello -I$AXIS2C_HOME/include/axis2-1.6.0/ -L$AXIS2C_HOME/lib -laxutil -laxis2_axiom -laxis2_parser -laxis2_engine -lpthread -laxis2_http_sender -laxis2_http_receiver hello.c -ldl -Wl,--rpath -Wl,$AXIS2C_HOME/lib

On MS Windows:

to compile,

cl.exe /nologo /D "WIN32" /D "_WINDOWS" /D "_MBCS" /I %AXIS2C_HOME%\include /c hello.c

to link,

link.exe /LIBPATH:%AXIS2C_HOME%\lib axutil.lib axiom.lib axis2_parser.lib axis2_engine.lib /OUT:hello.exe *.obj

1.2.5 Running the Client

To run the client, make sure you start the simple axis server and then run the hello executable.

2.1 Module Folders

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.
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.

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.

2.2 Service Folders

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.

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.

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.

4.1 Synchronous vs. Asynchronous Behavior (Blocking/Non-Blocking)

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.
axis2_svc_client_send_receive operates in synchronous mode, whereas axis2_svc_client_send_receive_non_blocking operates in asynchronous mode.

4.2 Two-Way or One-Way Transport

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.
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 axis2_options_set_use_separate_listener function above the options.

Please have a look at the echo_blocking_dual sample to see how to set the separate channel option.

Please see Appendix D for further details on setting options.

7.1 Writing the module.xml File

In the module.xml file, the handlers of the module and the phases to which they are to be added have to be specified. Below is the module.xml file of the sample logging module.

 <module name="logging" class="axis2_mod_log">
 <inflow>
 <handler name="LoggingInHandler" class="axis2_mod_log">
 <order phase="PreDispatch"/>
 </handler>
 </inflow>
 <outflow>
 <handler name="LoggingOutHandler" class="axis2_mod_log">
 <order phase="MessageOut"/>
 </handler>
 </outflow>
 <Outfaultflow>
 <handler name="LoggingOutHandler" class="axis2_mod_log">
 <order phase="MessageOut"/>
 </handler>
 </Outfaultflow>
 </module>

In the above shown module configuration file, the name of the module is logging. There are two handlers in this module, the LoggingInHandler and the LoggingOutHandler. The LoggingInHandler is placed into the PreDispatch phase of the in flow. The LoggingOutHandler is placed into the MessageOut phase of both the out flow and the fault out flow.

7.2 Packaging and Deploying the Module

The above module.xml file should be copied to a folder named "logging" (because the module name is "logging") inside the AXIS2C_INSTALL_DIR/modules folder. The module libraries containing the handler implementation should also be copied to the same folder. According to the module.xml file shown above, the name of the shared library file should be libaxis2_mod_log.so on Linux and axis2_mod_log.dll on MS Windows.

7.3 Adding Module Specific Phases to the axis2.xml File

Module specific phases have to be added after the system predefined phases. The following example shows where to add the module specific phases. Look for the phaseOrder elements in the axis2.xml file. Note the comment lines:

 <!-- User defined phases could be added here -->

You can add user defined phases after the above comment line into any of the flows. The type attribute of the phaseOrder element indicates the flow.

For the logging module example, user defined phases are not required. All the module specific handlers are added to system predefined phases as specified in the module.xml file.

7.4 Engaging a Module to a Services

The following is an example of engaging the logging module to the echo service. This can be done by simply adding <module ref ="logging"/> in the services.xml file of the echo service. This informs the Axis2/C engine that the module "logging" should be engaged for this service. The handlers inside the module will be executed in their respective phases as described by the module.xml.

 <service name="echo">
 <module ref ="logging"/>
 <parameter name="ServiceClass" locked="xsd:false">echo</parameter>
 <description>
 This is a testing service, to test if the system is working or not.
 </description>
 <operation name="echoString">
 <!--messageReceiver class="axis2_receivers" /-->
 <parameter name="wsamapping" >
 http://ws.apache.org/axis2/c/samples/echoString
 </parameter>
 </operation>
 </service>

One important thing to note here is that because the logging module's handlers are placed into the global phases, even though the logging module is engaged only to the echo service, the module will be engaged globally. This is a feature of the Axis2 architecture, not a bug. When invoked, the handlers in a module can check whether the module has been engaged to a particular service, and act accordingly.

7.4.1 Engaging a Module Globally

If we want to engage a module for every service deployed in the Axis2/C system, we can add the <module ref ="logging"/> entry in the axis2.xml file. This will inform the Axis2/C engine to invoke the handlers associated with the module for every message coming in or going out for all the services deployed.

7.5 Engaging a Module on the Client Side

On the client side, if <module ref ="logging"/> is added in the axis2.xml, the handlers specific to the logging module will be invoked for every request the client sends and every response the client receives. If only a particular client wants to engage the module, it can be done by engaging the module programmatically. This can be done by adding the following line in the client code after setting the options.

axis2_svc_client_engage_module(svc_client, env, "module-name");

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:

axis2_svc_client_engage_module(svc_client, env, "logging");

9.1 Writing Handlers

A handler is the smallest unit of execution in the Axis2/C engine's execution flow. The engine can have two flows, the in-flow and the out-flow. A flow is a collection of phases, and a phase in turn is a collection of handlers. A handler is invoked when the phase within which it lives is invoked. Axis2/C defines an interface called axis2_handler, which is to be implemented by all the handlers.

log_in_handler.c contains the source code of the in-handler of the logging module. Please have a look at the axutil_log_in_handler_create function to see how an axis2_handler instance is created and how the invoke function implementation, axis2_log_in_handler_invoke is assigned to the axis2_handler invoke function pointer. The invoke is called to do the actual work assigned to the handler. The phase that owns the handler is responsible for calling the invoke function of the handler.

log_out_handler.c contains the source code of the out handler of the logging module. The implementation is similar to the in handler, except that it is placed along the out-flow when deployed.

9.2 Writing the module.xml File

After writing the module, the module.xml file should be written. The module.xml file contains all the configuration details for a particular module. Please see the sample module.xml file for the logging module.

Please see the Engaging a Module section for more details on how to package and deploy the module.

10.1 Linux Based Systems

Synopsis :

 axis2_http_server [-p PORT] [-t TIMEOUT] [-r REPO_PATH] [-l LOG_LEVEL] [-f LOG_FILE] [-s LOG_FILE_SIZE]

You can use the following options with simple axis HTTP server.

 -p PORT port number to use, default port is 9090
 -r REPO_PATH repository path, default is ../
 -t TIMEOUT socket read timeout, default is 30 seconds
 -l LOG_LEVEL log level, available log levels:
 0 - critical 1 - errors 2 - warnings
 3 - information 4 - debug 5- user 6 - trace
 Default log level is 4(debug).
 -f LOG_FILE log file, default is $AXIS2C_HOME/logs/axis2.log
 or axis2.log in current folder if AXIS2C_HOME not set
 -s LOG_FILE_SIZE Maximum log file size in mega bytes, default maximum size is 1MB.
 -h display the help screen.

Example :

 axis2_http_server -l 3 -p 8080 -r $AXIS2C_HOME -f /dev/stderr

10.2 MS Windows Based Systems

Synopsis :

 axis2_http_server.exe [-p PORT] [-t TIMEOUT] [-r REPO_PATH] [-l LOG_LEVEL] [-f LOG_FILE] [-s LOG_FILE_SIZE]

You can use the following options with simple axis HTTP server.

 -p PORT port number to use, default port is 9090
 -r REPO_PATH repository path, default is ../
 -t TIMEOUT socket read timeout, default is 30 seconds
 -l LOG_LEVEL log level, available log levels:
 0 - critical 1 - errors 2 - warnings
 3 - information 4 - debug 5- user 6 - trace
 Default log level is 4(debug).
 -f LOG_FILE log file, default is %AXIS2C_HOME%\logs\axis2.log
 or axis2.log in current folder if AXIS2C_HOME not set
 -s LOG_FILE_SIZE Maximum log file size in mega bytes, default maximum size is 1MB.
 -h display the help screen.

Example :

 axis2_http_server.exe -l 3 -p 8080 -r %AXIS2C_HOME% -f C:\logs\error.log

11.1 Linux Platform

To build Axis2/C with the Apache HTTP server module, also called mod_axis2, you need to provide the following configuration options on the Linux platform:

./configure --with-apache2=[path to Apache2 include directory] [other configure options]

NOTE: Some Apache2 distributions, specially development versions, install APR (Apache Portable Run-time) include files in a separate location. In that case, to build mod_axis2, use:

./configure --with-apache2=[path to Apache2 include directory] --with-apr=[path to APR include directory]
 [other configure options]

Then build the source tree as usual using:

 make
 make install

This will install mod_axis2.so into your AXIS2C_INSTALL_DIR/lib folder.

11.2 MS Windows Platform

On the MS Windows platform, you have to provide the Apache2 install location in the configure.in file with the setting APACHE_BIN_DIR. Example:

APACHE_BIN_DIR = "C:\Program Files\Apache Software Foundation\Apache2.2"

Based on the Apache HTTP server version you are using, you also need to set the setting APACHE_VERSION_2_0_X in the configure.in file. If you are using Apache 2.2 family, this setting should be set to 0,else set it to 1.

APACHE_VERSION_2_0_X = 0

To build the source, you have to run the command

nmake axis2_apache_module

This will build mod_axis2.dll and copy it to AXIS2C_INSTALL_DIR\lib directory.

11.3 Deploying mod_axis2

NOTE: To execute some of the commands given below, you might require super user privileges on your machine. If you are using the binary release of Axis2/C, please note that it is built with Apache 2.2.

Copy the mod_axis2 shared library (libmod_axis2.so.0.6.0 on Linux and mod_axis2.dll on MS Windows) to the Apache2 modules directory as mod_axis2.so

On Linux

	cp $AXIS2C_HOME/lib/libmod_axis2.so.0.6.0 /usr/lib/apache2/modules/mod_axis2.so

On MS Windows

	copy /Y "%AXIS2C_HOME%\lib\mod_axis2.dll" C:\Apache2\modules\mod_axis2.so

Edit the Apache2's configuration file (generally httpd.conf) and add the following directives at the end of the file.

LoadModule axis2_module MOD_AXIS2_SO_PATH
Axis2RepoPath AXIS2C_INSTALL_DIR
Axis2LogFile PATH_TO_LOG_FILE
Axis2LogLevel LOG_LEVEL
Axis2ServiceURLPrefix PREFIX
Axis2MaxLogFileSize SIZE_IN_MB
<Location /axis2>
 SetHandler axis2_module
</Location>

Please note that you have to fine tune the above settings to mach your system.

MOD_AXIS2_SO_PATH has to be replaced with the full path to mod_axis2.so, for example, /usr/lib/apache2/modules/mod_axis2.so on Linux, or C:\Apache2\modules\mod_axis2.so on MS Windows

AXIS2C_INSTALL_DIR has to be replaced with the full path to Axis2/C repository, for example, /usr/local/axis2 on Linux, or c:\axis2c on MS Windows. Note that repository path should have read access to the daemon user account under which the Apache2 HTTPD process is run.

PATH_TO_LOG_FILE has to be replaced with the full path to where you wish to have the Axis2/C log file, for example, /tmp/axis2.log on Linux, or C:\Apache2\logs\axis2.log on MS Windows. Note that the log file path should have write access to the daemon user account under which the Apache2 HTTPD process is run.

LOG_LEVEL has to be replaced with one of the following values: crit, error, warn, info, debug, trace. These log levels have the following meanings:

• crit - log critical errors
• error - log errors and above
• warn - log warnings and above
• info - log information and above
• debug - log debug information and above, this is the default log level used
• user - log user level messages and above
• trace - log trace messages and above

SIZE_IN_MB must be replaced by the size of the particular resource in MB, rounded to the nearest whole value.

PREFIX has to be replaced with the prefix to be used with the service endpoints. This is optional and defaults to "services". As an example, if you have "web_services" as the prefix, then all the services hosted would have the endpoint prefix of :
http://localhost/axis2/web_services
If you wish, you can also change the location as well by replacing "/axis2" in <Location /axis2> setting with whatever you wish.

NOTE: If you want to use a Shared Global Pool with Apache you have to give another entry called Axis2GlobalPoolSize.You have to give the size of the shared global pool in MB.If you doesn't set the value or if you set a negative value Apache module doesn't create shared global pool.

Axis2GlobalPoolSize SIZE_IN_MB

To ensure that everything works fine, start Apache2 (restart if it is already running) and test whether the mod_axis2 module is loaded correctly by accessing the URL: http://localhost/axis2/services.

This should show the list of services deployed with Axis2/C. Then you should be able to run clients against this endpoint. Example:

echo http://localhost/axis2/services/echo

In case things are not working as expected, here are some tips on how to troubleshoot:

• Double check the steps you followed in installing and configuring mod_axis2. Check if the locations given in httpd.conf are correct, and also check the folder permissions.
• Have a look at the axis2.log file for clues as to what is going wrong. You can set the log level to debug, user or trace to gather more information
• In case the axis2.log file is not written at all, there is a good chance that mod_axis2 is crashing. You can have a look at the error.log file of Apache2 to get an idea on what is going wrong. This file is usually placed in the APACHE_INSTALL_DIR/logs folder.

13.1 Building and Configuring the Client

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.

To build with SSL client support, first of all, make sure you have installed OpenSSL on your machine. Then you can start building with SSL client support. This can be achieved on Linux by configuring Axis2/C with the --enable-openssl=yes option.

Example
%./configure --enable-openssl=yes --prefix=${AXIS2C_HOME}/deploy
%make
%make install


On MS Windows, set ENABLE_SSL=1 in the configure.in file and run the nmake all command.

13.1.1 Creating the Client Certificate Chain File

If you need SSL client authentication, Axis2/C requires you to provide the client certificate and the private key file in a single file. Such a file which contains both the certificate and relevant private key is called a certificate chain file. Creating such a file is very easy. Assume that the client certificate is stored in a file named client.crt and the private key is stored in a file named client.key. Then the certificate chain file can be created by concatenating the certificate file and the private key file in that order, in to another file, say client.pem.

On Linux you can do this as follows: %cat client.crt client.key > client.pem

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.

13.1.2 Configuration

Uncomment the following in axis2.xml to enable https transport receiver and https transport sender. Axis2/C will then be able to recognize the "https" sheme in a given end point reference (EPR) and use SSL transport.

<transportReceiver name="https" class="axis2_http_receiver">
 <parameter name="port" locked="false">6060</parameter>
 <parameter name="exposeHeaders" locked="true">false</parameter>
</transportReceiver>

<transportSender name="https" class="axis2_http_sender">
 <parameter name="PROTOCOL" locked="false">HTTP/1.1</parameter>
</transportSender>

For the SSL client to work, the file containing the CA certificate should be given as SERVER_CERT parameter in the axis2.xml file. If you need client authentication, you can also set the parameters in the axis2.xml file to specify the client certificate, private key, and the passphrase for the client private key. Parameter names for these are:

KEY_FILE - certificate chain file containing the client's certificate and the private key (Please refer to the creating the client certificate chain file section)
SSL_PASSPHRASE - passphrase used to encrypt the private key file.

Example:

<parameter name="SERVER_CERT">/path/to/ca/certificate</parameter>
<parameter name="KEY_FILE">/path/to/client/certificate/chain/file</parameter>
<parameter name="SSL_PASSPHRASE">passphrase</parameter>

For testing purposes, you can use the server's certificate instead of the CA certificate. You can obtain this by running the command openssl s_client -connect <servername>:<port> and copying the portion of the output bounded by and including:

-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----

On Linux, if you run the following piece of code, the server certificate will be saved to a file cert.pem:

echo |\
openssl s_client -connect <servername>:<port> 2>&1 |\
sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > cert.pem

NOTE: Instead of setting these parameters in the axis2.xml file, you can also set these parameters programmatically in your client code.

13.2 Configuring the Server

Here we will only look at the configuration of the Apache HTTP Web server. Refer to the 'Deploying with Apache HTTP Server Version2.x' section for information on deploying Axis2/C as an Apache module.

For more detailed information on SSL configuration, please refer to Apache2 SSL/TLS documentation.

In the httpd.conf file, add the following configuration statements (in addition to other necessary configuration):

SSLEngine on
SSLCertificateFile /path/to/server/certificate/file
SSLCertificateKeyFile /path/to/private/key/file
SSLCACertificateFile /path/to/CA/certificate/file
SSLVerifyClient require
SSLVerifyDepth 1

NOTE: The last two lines, SSLVerifyClient and SSLVerifyDepth are only needed when you need client authentication.

14.1 Specifying Proxy Settings in axis2.xml

<transportSender name="http" class="axis2_http_sender">
 <parameter name="PROTOCOL" locked="false">HTTP/1.1</parameter>
 <parameter name="PROXY" proxy_host="127.0.0.1" proxy_port="8080" locked="true"/>
</transportSender>

14.2 Providing Proxy Settings Using Service Client API

You can specify proxy settings using the following function with the service client:

axis2_svc_client_set_proxy(axis2_svc_client_t *svc_client,
 const axutil_env_t *env,
 axis2_char_t *proxy_host,
 axis2_char_t *proxy_port);

15.1 Specifying Proxy Settings with Authentication in axis2.xml

<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" proxy_username="" proxy_password="" locked="true"/>
</transportSender>

15.2 Providing Proxy Settings with Authentication Using Service Client API

You can specify proxy authentication settings using the following function with the service client:

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);

15.3 Providing Proxy Authentication Settings Using Service Client Options

You can specify proxy authentication settings using the following function with the service client options:

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);

In auth_type, use Basic to force Basic Authentication or Digest to force Digest Authentication. Leave this field NULL if you are not forcing authentication.

axis2_options_set_test_proxy_auth(
 axis2_options_t * options,
 const axutil_env_t * env,
 const axis2_bool_t test_proxy_auth);

axis2_svc_client_get_auth_type(
 const axis2_svc_client_t * svc_client,
 const axutil_env_t * env);

axis2_svc_client_get_proxy_auth_required(
 const axis2_svc_client_t * svc_client,
 const axutil_env_t * env);