Movatterモバイル変換

1.1 Hello Service

Let's see how you can write your first Web service withAxis2/C and how todeploy it.

The first service that we are going to write is named "hello"with asingle operation named "greet" in the service. This "greet" operation,wheninvoked by the client, will expect the client to send a greeting in therequest, and in turn send a greeting in the response. Following areexamplesof 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 withAxis2/Cinclude:

1. Implement the functions corresponding to theoperations of the service.
   
   In our sample, we will have one function that implements the "greet"operation.
   
   We will name that functionaxis2_hello_greet.
2. Implement the functions defined by theaxis2_svc_skeletoninterface
   
   axis2_svc_skeleton interface expects thefunctionsinit,invoke,on_fault andfreeto be implemented by our service.
   
   In our sample, we would implement those and name them ashello_init,hello_invoke,hello_on_faultandhello_free respectively.
   
   
3. Implement the create function, that would createan instance of the service skeleton
   
   The create function would create an axis2_svc_skeleton and assign therespective function pointers to map the axis2_svc_skeleton interface toour interface implementation methods explained in the above step.
   
   
4. Implement axis2_get_instance andaxis2_remove_instance functions
   
   These functions are used to create and destroy service instances by theengine, 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 theservice. As the bare minimum, we need to configure the service name,operations, and the shared library file name containing the serviceimplementation 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 MSWindows.
   
   

1.1.1 Operation Implementation

Look for theaxis2_hello_greetfunction in thehello_svc.csource file.

This function implements the business logic for the greetoperation. Wewill be calling this function from our implementation of the invokefunction.Basically, this function receives the request payload as anaxiom_node, process it to understand therequest logic, andprepares the response as anaxiom_node andreturns that.

1.1.2 Skeleton Create Method

Look for theaxis2_hello_createfunction in thehello_svc.csource file.

The create function creates and returns a newaxis2_svc_skeleton instance. The mostimportant aspect to noteabout this function is the function pointer assignments. They are usedto mapthe interface operations to the corresponding functions of theimplementation. This is done by assigning the ops member of the serviceskeleton to the address of the ops struct variable.

1.1.3 Invoking Operation Implementation

The invoke method of the service skeleton is the point ofentry forinvoking the operations. Hence in our implementation of the invokefunction,we have to define how the operations are to be called.

Look for thehello_invoke functionin thehello_svc.csource file.

In our implementation of thehello_invoke,we call thefunction implementing the greet operation. As we have only oneoperation, thetask is simple here. If we had multiple operations, we will have tolook intothe information in the message context to map it to the exactoperation.

The Axis2/C engine will call the invoke method with anaxiom_node, containing the request payload,andaxis2_msg_ctx instance, containing the messagecontextinformation, in addition to the service skeleton and the environmentpointers. We can use the message context to extract whateverinformation wedeem necessary that is related to the incoming message. The Axis2/Cengineexpects the invoke method to return a pointer to anaxiom_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 thatwould be readby the Axis2/C deployment engine during server start up time. Thefollowingshows 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 nameof theservice is hello.

The value of the "ServiceClass", "hello" in this case, will be mappedto theservice implementation by the deployment engine as libhello.so on Linuxorhello.dll on MS Windows. The description element contains a briefdescriptionof the service.

There can be one or more operation elements. For this sample, we onlyhaveone 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 todeploy the service. To deploy the service, you have to create a foldernamed'hello' in the AXIS2C_HOME/services folder, and copy the services.xmlfileand the shared library file (libhello.so on Linux or hello.dll on MSWindows)into that folder.

To verify that your service has been correctly deployed, youcan start thesimple axis server and then browse the list of deployed services usinga Webbrowser. To start the simple axis server, you can go to theAXIS2C_HOME/binfolder and run the executable axis2_http_server. The default URL thatyou cantest the service list with ishttp://localhost:9090/axis2/services.You should get an entry for the hello service on the page that isdisplayed.

1.1.8 Providing a WSDL for the Service

Axis2/C does not support dynamic WSDL generation. However, itis possible to attach the contract you used to generate the serviceskeleton, to the respective service. This can be done in two ways.

1. Adding the WSDL file to the folder in which the service DLLis 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 WSDLfile to the folder in which the service DLL is found. The name of theWSDL file should be the name of the service. And, if you choose thesecond option, you will have to make use of thewsdl_pathparameter in the services.xml file. More info on how this can be doneis found under theservices.xmlsection.

An example of the second option can be found the services.xmlof theecho sample service, which is commented. Anexample of the first option in use is seen in theCalculatorsample service.

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

1.2 Hello Client

Now that you know how to write a service with Axis2/C, let'ssee how towrite a client to consume that service. The request payload that theclientwill be sending to the service was described in the previous section.Theclient has to prepare the payload, send it to the service, and thenreceiveand process the response.

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

1. Create the environment to be used by the client.
   
   Each function in Axis2/C takes a pointer to the environment instancethat encapsulates the memory allocator, error handler, and logging andthreading mechanisms. Theaxutil_env_create_allmethod can be used to create a default, ready to use environmentinstance.
   
   
2. Create an options instance, and set options.
   
   The axis2_options struct can be used to setthe client side options. For example, we can use options to set theendpoint address of the service to be consumed by the client.
3. Create a service client instance, giving theclient repository folder as a parameter.
   
   The axis2_svc_client struct is meant to beused by the users to consume Web services. It provides an easy to useAPI. Service client create method takes the location of the repositoryas a parameter. For the purpose of our sample, you can use theAXIS2C_HOME as the repository. The concept ofrepositoryis 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 serviceclient, indicating the options that are meant to be used by the serviceclient.
   
   
5. Send the request and receive the response
   
   The service client'saxis2_svc_client_send_receivemethod can be used to invoke the send receive operation on the serviceclient instance.
   
   The send receive operation takes the request payload as anaxiom_nodeand returns the response payload as anaxiom_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, anaxis2_optionsinstance iscreated first. Then an endpoint reference instance is created with theaddress of the location of the service. Finally, the created endpointis setas the "to" address of the options. The "to" address indicates wheretherequest 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 tocreate aservice client instance and use it to send the request and receive theresponse. The code fragment given above shows how options can be set ontopof the service client and how to invoke the send receive operation witharequest payload. Once the response is received, the response payloadwill bestored in theret_node, which is a pointer toanaxiom_node that can be used to process theresponse 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 serverand then runthe hello executable.

2.1 Module Folders

As described earlier, all the modules are placed inside themodules folderof the repository, and each module will have its own sub folder withinthemodules folder.

The folder in which a module is placed must have the same name as themodulename. For example, the addressing module will be placed in a sub foldernamedaddressing.

Inside the folder corresponding to a module, the sharedlibraryimplementing the module and the module configuration file, module.xml,isplaced. It is a must that these two files are present inside eachfolderrepresenting a module. The module.xml file will be processed by thedeployment engine to find out module specific information such as themodulename, set of handlers, the flows into which those handlers are to beadded,etc.

2.2 Service Folders

All the services are placed inside the services folder of therepository,and each service will be in one of the sub folders within the servicesfolder. Axis2/C has a concept called service groups, where there can beoneor more services inside a service group. A single stand alone serviceisassigned a service group with the same name as that of the service bytheAxis2/C engine for the purpose of easy handling. Therefore the subfolders inthe services folder correspond to the service groups.

A service, if deployed as a stand alone service, will resideinside afolder with the same name as that of the service. For example, the echoservice will be placed in a sub folder named echo. The shared libraryimplementing the service and the service configuration file, theservices.xml, will be placed inside the folder corresponding to aservice.Given the fact that the engine treats the folders to represent servicegroupsand not a single service, the configuration file is calledservices.xml.However, you can always place a single service inside a single folder,whichis the most common use case.

Each sub folder within the services folder should have atleast one sharedlib implementing a service and a services.xml file. If it is a realservicegroup, there will be multiple shared libs, yet there is only oneservices.xmlfile configuring all those services. The services.xml file is processedbythe deployment engine to find out the service group and the servicespecificinformation such as the service group name, service name, the set ofoperations for each service, etc.

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

This will determine whether the client would block for theresponse(synchronous) or return immediately expecting the response to behandled by acallback (asynchronous, in other words non-blocking) in an Out-In MEPscenario.

axis2_svc_client_send_receive operates insynchronous mode,whereasaxis2_svc_client_send_receive_non_blockingoperates inasynchronous mode.

4.2 Two-Way or One-Way Transport

If the transport is two-way, then only one channel is used,which meansthe request is sent and the response is received on the same channel.If thetransport is one-way, then the request is sent on one channel and theresponse is received on a separate channel.

If we want to use a separate channel for the response, a separatelistenerhas to be started to receive the response, This can be done by settingtheseparate listener option to True using theaxis2_options_set_use_separate_listenerfunction above theoptions.

Please have a look at theecho_blocking_dualsample to seehow to set the separate channel option.

Please seeAppendix Dfor further details on settingoptions.

axis2_options_set_enable_rest(options, env, AXIS2_TRUE);

axis2_options_set_http_method(options, env, AXIS2_HTTP_GET);

<operation name="locate">

 <parameter name="RESTMethod">GET</parameter>

 <parameter name="RESTLocation">location/{lat}/{long}</parameter>

</operation>

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

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

7.1 Writing the module.xml File

In the module.xml file, the handlers of the module and thephases to whichthey are to be added have to be specified. Below is the module.xml fileofthe sample logging module.

 <module name="logging">

 <inflow>

 <handler name="LoggingInHandler">

 <order phase="PreDispatch"/>

 </handler>

 </inflow>

 <outflow>

 <handler name="LoggingOutHandler">

 <order phase="MessageOut"/>

 </handler>

 </outflow>

 <Outfaultflow>

 <handler name="LoggingOutHandler">

 <order phase="MessageOut"/>

 </handler>

 </Outfaultflow>

 </module>

In the above shown module configuration file, the name of themodule islogging. There are two handlers in this module, the LoggingInHandlerand theLoggingOutHandler. The LoggingInHandler is placed into the PreDispatchphaseof the in flow. The LoggingOutHandler is placed into the MessageOutphase ofboth 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 theAXIS2C_INSTALL_DIR/modulesfolder. The module libraries containing the handler implementationshouldalso be copied to the same folder. According to the module.xml fileshownabove, the name of the shared library file should belibaxis2_mod_log.so onLinux 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 systempredefinedphases. The following example shows where to add the module specificphases.Look for thephaseOrder elements in theaxis2.xml file. Note thecomment lines:

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

You can add user defined phases after the above comment lineinto any of theflows. Thetype attribute of thephaseOrderelementindicates the flow.

For the logging module example, user defined phases are notrequired. Allthe module specific handlers are added to system predefined phases asspecified in the module.xml file.

7.4 Engaging a Module to a Services

The following is an example of engaging the logging module tothe echoservice. This can be done by simply adding<moduleref="logging"/> in the services.xml file of the echoservice. Thisinforms the Axis2/C engine that the module "logging" should be engagedforthis service. The handlers inside the module will be executed in theirrespective 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 /-->

 <parameter name="wsamapping" >

 http://ws.apache.org/axis2/c/samples/echoString

 </parameter>

 </operation>

 </service>

One important thing to note here is that because the loggingmodule'shandlers are placed into the global phases, even though the loggingmodule isengaged only to the echo service, the module will be engaged globally.Thisis a feature of the Axis2 architecture, not a bug. When invoked, thehandlersin a module can check whether the module has been engaged to aparticularservice, and act accordingly.

7.4.1 Engaging a Module Globally

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

7.5 Engaging a Module on the Client Side

On the client side, if<module ref="logging"/> isadded in the axis2.xml, the handlers specific to the logging modulewill beinvoked for every request the client sends and every response theclientreceives. If only a particular client wants to engage the module, itcan bedone by engaging the module programmatically. This can be done byadding thefollowing 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 moduleyou want toengage. For example to engage the logging module you can use:

axis2_svc_client_engage_module(svc_client, env, "logging");

axis2_svc_client_engage_module(svc_client, env, AXIS2_MODULE_ADDRESSING);

axis2_options_set_action(options,env,"http://ws.apache.org/axis2/c/samples/echoString")

axis2_options_set_reply_to(options, env, reply_to)

axis2_options_set_fault_to(options, env, fault_to)

axis2_options_set_from(options, env, from)

axis2_options_set_relates_to(options, env, relates_to)

9.1 Writing Handlers

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

log_in_handler.ccontains thesource code of the in-handler of the logging module. Please have a lookattheaxutil_log_in_handler_create function tosee how anaxis2_handler instance is created and how theinvoke functionimplementation,axis2_log_in_handler_invokeis assigned to theaxis2_handler invoke function pointer. Theinvoke is called todo the actual work assigned to the handler. The phase that owns thehandleris responsible for calling the invoke function of the handler.

log_out_handler.ccontainsthe source code of the out handler of the logging module. Theimplementationis similar to the in handler, except that it is placed along theout-flowwhen deployed.

9.2 Writing the module.xml File

After writing the module, the module.xml file should bewritten. Themodule.xml file contains all the configuration details for a particularmodule. Please see the samplemodule.xmlfile for the logging module.

Please see theEngaginga Module sectionfor 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, alsocalledmod_axis2, you need to provide the following configuration options ontheLinux platform:

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

./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 yourAXIS2C_INSTALL_DIR/lib folder.

11.2 MS Windows Platform

On the MS Windows platform, you have to provide the Apache2installlocation 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, youalso need toset the setting APACHE_VERSION_2_0_X in the configure.in file. Ifyou areusing Apache 2.2 family, this setting should be set to 0,else set it to1.

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 toAXIS2C_INSTALL_DIR\lib directory.

11.3 Deploying mod_axis2

Copy the mod_axis2 shared library 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 thefollowing 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 tomach yoursystem.



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



AXIS2C_INSTALL_DIR has to be replaced with the full path to Axis2/Crepository, for example,/usr/local/axis2 onLinux, orc:\axis2c on MS Windows. Note thatrepository path shouldhave read access to the daemon user account under which the Apache2HTTPDprocess is run.



PATH_TO_LOG_FILE has to be replaced with the full path to where youwish tohave the Axis2/C log file, for example,/tmp/axis2.logon Linux, orC:\Apache2\logs\axis2.log on MSWindows. Note that the logfile path should have write access to the daemon user account underwhich theApache2 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 thedefault 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 particularresource in MB, rounded tothe nearest whole value.



PREFIX has to be replaced with the prefix to be used with the serviceendpoints. This is optional and defaults to "services".As an example, if you have "web_services" as the prefix, then all theservices 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 youwish.

Axis2GlobalPoolSize SIZE_IN_MB

To ensure that everything works fine, start Apache2 (restartif it isalready running) and test whether the mod_axis2 module is loadedcorrectly byaccessing the URL:http://localhost/axis2/services.

This should show the list of services deployed with Axis2/C.Then youshould 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 tipson how totroubleshoot:

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

nmake axis2_iis_module

13.1 Building and Configuring the Client

In order to allow an Axis2/C client to communicate with an SSLenabledserver, we need to compile Axis2/C with SSL support enabled.

To build with SSL client support, first of all, make sure youhaveinstalledOpenSSLon your machine. Thenyou can start building with SSL client support. This can be achieved onLinuxby configuring Axis2/C with the--enable-openssl=yesoption.

Example

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

%make

%make install



On MS Windows, setENABLE_SSL=1 intheconfigure.in file and run thenmakeall command.

13.1.1 Creating the Client Certificate Chain File

If you need SSL client authentication, Axis2/C requires you toprovide theclient certificate and the private key file in a single file. Such afilewhich contains both the certificate and relevant private key is calledacertificate chain file. Creating such a file is very easy. Assume thattheclient certificate is stored in a file namedclient.crtand theprivate key is stored in a file namedclient.key.Then thecertificate chain file can be created by concatenating the certificatefileand the private key file in that order, in to another file, sayclient.pem.

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

On MS Windows, you can do this by copying the contents ofclient.crt andclient.key files and saving them in a file named client.pem usingNotepad.

13.1.2 Configuration

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

<transportReceiver name="https">

 <parameter name="port" locked="false">6060</parameter>

 <parameter name="exposeHeaders" locked="true">false</parameter>

</transportReceiver>

<transportSender name="https">

 <parameter name="PROTOCOL" locked="false">HTTP/1.1</parameter>

</transportSender>

For the SSL client to work, the file containing the CAcertificate shouldbe given asSERVER_CERT parameter in theaxis2.xml file. If youneed client authentication, you can also set the parameters in theaxis2.xmlfile to specify the client certificate, private key, and the passphraseforthe client private key. Parameter names for these are:

KEY_FILE - certificate chain filecontaining the client'scertificate and the private key (Please refer to thecreating the client certificate chainfilesection)

SSL_PASSPHRASE - passphrase used to encryptthe private keyfile.

Example:

<parametername="SERVER_CERT">/path/to/ca/certificate</parameter>

<parametername="KEY_FILE">/path/to/client/certificate/chain/file</parameter>

<parametername="SSL_PASSPHRASE">passphrase</parameter>

For testing purposes, you can use the server's certificateinstead of theCA certificate. You can obtain this by running the commandopenssls_client -connect <servername>:<port>and copying theportion of the output bounded by and including:

-----BEGIN CERTIFICATE-----

-----END CERTIFICATE-----

On Linux, if you run the following piece of code, the servercertificatewill be saved to a filecert.pem:

echo |\

openssl s_client -connect <servername>:<port> 2>&1 |\

sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > cert.pem

13.2 Configuring the Server

Here we will only look at the configuration of the Apache HTTPWeb server.Refer to the 'Deploying with ApacheHTTP Server Version2.x' section for information on deployingAxis2/C as an Apachemodule.

For more detailed information on SSL configuration, pleaserefer toApache2SSL/TLSdocumentation.

In thehttpd.conf file, add thefollowing configurationstatements (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

14.1 Specifying Proxy Settings in axis2.xml

<transportSender name="http">

 <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 functionwith theservice 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 inaxis2.xml

<transportSender name="http">

 <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 UsingService Client API

You can specify proxy authentication settings using thefollowing function with theservice 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 ServiceClient Options

You can specify proxy authentication settings using thefollowing function with theservice 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);

Inauth_type, useBasicto force Basic Authentication orDigest to forceDigestAuthentication. Leave this field NULL if you are not forcingauthentication.

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

16. Using HTTP Authentication Support

When using HTTP authentication, there are two methods forspecifying proxyauthentication settings:

1. Specify HTTP authentication settings in axis2.xml
2. Provide HTTP authentication settings using service clientoptions

<transportSender name="http">

 <parameter name="PROTOCOL" locked="false">HTTP/1.1</parameter>

 <parameter name="HTTP-Authentication" username="your username" password="your password" locked="true"/>

</transportSender>

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

axis2_options_set_test_http_auth(

 axis2_options_t * options,

 const axutil_env_t * env,

 const axis2_bool_t test_http_auth);

axis2_svc_client_get_auth_type(

 const axis2_svc_client_t * svc_client,

 const axutil_env_t * env);

axis2_svc_client_get_http_auth_required(

 const axis2_svc_client_t * svc_client,

 const axutil_env_t * env);

java org.apache.axis2.wsdl.WSDL2C -uri interoptestdoclitparameters.wsdl -ss -sd -d adb -u

java org.apache.axis2.wsdl.WSDL2C -uri interoptestdoclitparameters.wsdl -ss -sd -d none

/* Todo fill this with the necessary business logic */

java WSDL2C -uri interoptestdoclitparameters.wsdl -d adb -u

java WSDL2C -uri interoptestdoclitparameters.wsdl -d none

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

 -p PORT port number to use, default port is 9091

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

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

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

 -p PORT port number to use, default port is 9091

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

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

$ cd ${QPID_HOME}/sbin

$ ./qpidd --data-dir ./

$ cd ${AXIS2C_HOME}/bin

$ ./axis2_amqp_server

$ ./axis2_amqp_server -h

 axis2_amqp_server [-i QPID_BROKER_IP] [-p QPID_BROKER_PORT] [-r REPO_PATH] [-l LOG_LEVEL] [-f LOG_FILE] [-s LOG_FILE_SIZE]

 -i IP where the Qpid broker is running, default IP is 127.0.0.1

 -p PORT port number the Qpid broker listens on, default port is 5672

 -r REPO_PATH repository path, default is ../

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

 axis2_amqp_server -i 127.0.0.1 -p 5050 -r $AXIS2C_HOME -f /dev/stderr

$ cd ${AXIS2C_HOME}/samples/bin/amqp



$ ./echo_blocking

./configure --prefix=${AXIS2C_HOME} --enable-tests=no

make

nmake tcpmon

Appendix A - axis2.xml

The axis2.xml file is the configuration file for Axis2/C. Ithas 6 toplevel elements. They areparameter, transportReceiver,transportSender,module, phaseOrder andmessageReceiver.The following sectionsdescribe these elements, their sub elements, element attributes,possiblevalues, and their purpose.

axisconfigis the root element of axis2.xmlfile.

Appendix B - services.xml

Configuration of a service is specified using a services.xml.Each serviceor service archive file needs to have a services.xml in order to be avalidservice. The following sections describe the elements of theservices.xmlfile.

If services.xml describes a single service, the root elementisservice. If it is describing a service group, thenthe root elementisserviceGroup. The serviceelement will be a childelement of serviceGroup if there are multiple services specified inservices.xml.

Appendix C - module.xml

The module.xml file provides the configuration details for aparticularmodule in Axis2/C. The top level element ismodule.

Appendix D - axis2_options

This section describes various types of options that can beset withaxis2_options. These options are used by theservice clientbefore sending messages.

axis2_options_set_action(options, env, action)

Sets the WS-Addressing action that is to be set in theaddressing SOAPheaders.

axis2_options_set_fault_to(options, env,fault_to)

Sets the end point reference which may receive the message ina case of aSOAP fault.

axis2_options_set_from(options, env, from)

Some services need to know the source from which the messagecomes. Thisoption sets the from endpoint

axis2_options_set_to(options, env, to)

Sets the endpoint reference the message is destined to.

axis2_options_set_transport_receiver(options,env,receiver)

Sets the transport receiver in an OUT-IN message exchangescenario.

axis2_options_set_transport_in(options, env,transport_in)

Sets the transport-in description.

axis2_options_set_transport_in_protocol(options,env,transport_in_protocol)

Sets the transport-in protocol.

axis2_options_set_message_id(options, env,message_id)

Sets the message ID.

axis2_options_set_properties(options, env,properties)

Sets the properties hash map.

axis2_options_set_property(options, env, key,property)

Sets a property with a given key value.

axis2_options_set_relates_to(options, env,relates_to)

Sets the relates-to message information.

axis2_options_set_reply_to(options, env,reply_to)

Sets the reply-to address, when the client wants a reply to besent to adifferent end point.

axis2_options_set_transport_out(options, env,transport_out)

Sets the transport-out description.

axis2_options_set_sender_transport(options, env,sender_transport,conf)

Sets the sender transport.

axis2_options_set_soap_version_uri(options, env,soap_version_uri)

Sets the SOAP version URI.

axis2_options_set_timeout_in_milli_seconds(options,env,timeout_in_milli_seconds)

Sets the time out in milli seconds. This is used inasynchronous messageexchange scenarios to specify how long the call back object is to waitforthe response.

axis2_options_set_transport_info(options, env,sender_transport,receiver_transport, user_separate_listener)

Sets the transport information. Transport information includesthe name ofthe sender transport, name of the receiver transport, and whether aseparatelistener is to be used to receive a response.

axis2_options_set_use_separate_listener(options,env,use_separate_listener)

Sets the bool value indicating whether to use a separatelistener or not.A separate listener is used when the transport is a one-way transportand themessage exchange pattern is two way.

axis2_options_set_soap_version(options, env,soap_version)

Sets the SOAP version.

axis2_options_set_enable_mtom(options, env,enable_mtom)

Enable or disable MTOM handling when sending binaryattachments.

axis2_options_set_enable_rest(options, env,enable_rest)

Enable or disable REST support.

axis2_options_set_http_auth_info(options, env,username, password, auth_type)

Sets HTTP Authentication information.

axis2_options_set_proxy_auth_info(options, env,username, password, auth_type)

Sets Proxy Authentication information.

axis2_options_set_test_http_auth(options, env,test_http_auth)

Enables testing of HTTP Authentication information.

axis2_options_set_test_proxy_auth(options, env,test_proxy_auth)

Enables testing of proxy Authentication information.