Creating the web service
How to use the WSDL2WS tool on the command line
Deploying your web service
Deploying your web service using AdminClient Tool
Coding the client
Running your sample
Axis Transport and Parser Library
Handlers
Before you follow this guide, make sure that you have followed the
Windows Installation guide
Currently axis supports two methods to create and deploy a Web Service.
Method 1) A top down approach where you start with a WSDL.
Method 2) A bottom up approach where you start with a pre-written web
service.
Here we discuss the first approach since the tool to support Method 2 (i.e
wcg.exe) is in a primitive and frozen state.
Here the document is written with the idea that the user uses Visual C++
(VC). But the user could use this guide with a different IDE of his choice.
Method 1
This method assums that the user has written the wsdl of the service which he
needs to deploy. In this method user will start with this wsdl and the tool
will generate the web service skeleton and other required files.
1) There is a folder called "simple" inside the samples/server folder in your axiscpp binary distribution. Inside this you can find the relevant wsdl for the calculator sample .Get the wsdl (eg:Calculator.wsdl)
2) Run the WSDL2WS tool (refer the section below 'How to use the WSDL2WS tool
on the command line') and generate the server side skeletons and wrappers.
These files will be in two new folders which are generated from the tool
called 'ServerOut' and 'ClientOut'.
3) Create a VC workspace.
4) Create a 'Win32 Static Library' project in this workspace.
5) Add the following files to this project, from the generated 'ServerOut'
folder. Calculator.cpp Calculator.h
6) Set the include path to the include directory of the binary distribution
(These include files are in AXIS_EXTRACT/include/).
7) Fill the empty methods of the generated skeletons.
8) Generate the lib (eg: MyCalculator.lib)
9) Now create a 'Win32 Dynamic-Link Library' project.
10) Add the following files to this project, from the generated 'ServerOut'
folder. CalculatorService.cpp CalculatorWrapper.cpp CalculatorWrapper.h
11) Set the include path to the include directory of the binary distribution.
12) Add the above created lib (Calculator.lib) as the input libraries of this
project.
13) Build and create the DLL. (Calculator.dll)
For using WSDL2Ws java tool on the command line you require jdk1.4 or
above.
To use WSDL2Ws java tool you should set the CLASSPATH Environment Variable to
point to the following jar files in AXIS_EXTRACT\lib\axisjava.
axis.jar
commons-discovery.jar
commons-logging.jar
jaxrpc.jar
saaj.jar
wsdl4j.jar
xml-apis.jar
The CLASSPATH Environment Variable should have the absolute paths of the jars
(including the jar file name) given as a semicolon separated list.
Open a command window. Change directory to AXIS_EXTRACT\lib\axis. Create a folder of your choice and we will
call this folder as WSDL2WS_FOLDER.
Now copy the wsdl file (eg.Calculator.wsdl) which you use to the folder
WSDL2WS_FOLDER.
Copy the file wsdl2ws.jar from AXIS_EXTRACT\bin to WSDL2WS_FOLDER
Now change the directory to WSDL2WS_FOLDER and run the following command to generate the server side skeletons and
wrappers.
Java -classpath %classpath%;.\wsdl2ws.jar
org.apache.axis.wsdl.wsdl2ws.WSDL2Ws Calculator.wsdl -o./ServerOut -lc++
-sserver
If the file generation is successful the tool will display the files that it has
generated. The skeletons and wrappers will be generated in
[WSDL2WS_FOLDER]\ServerOut.
Run the following command to generate the client stubs.
Java -classpath %classpath%;.\wsdl2ws.jar
org.apache.axis.wsdl.wsdl2ws.WSDL2Ws Calculator.wsdl -o./ClientOut -lc++
-sclient
The generated client stubs will be in [WSDL2WS_FOLDER]\ClientOut
Axis cpp user can use the AdminClient tool to deploy a service or manually deploy. The first section
shows you how to deploy your Web Service manually, without using the
AdminClient tool.
Say the apache installation folder is APACHE_FOLDER.
(For the default installation this is "C:\Program Files\Apache Group\Apache"
for apache 1.3.X and "C:\Program Files\Apache Group\Apache2" for apache
2.X).
1) Copy the above Calculator.dll to the folder
APACHE_FOLDER/Axis/webservices.
2) Go and add the following in the server.wsdd at the service level. Make
sure you add these lines at the correct place, i.e at service level.
(APACHE_FOLDER/Axis/conf/server.wsdd)
<service name="Calculator" provider="CPP:RPC" description="Calculator Web
Service">
<parameter name="className"
value="APACHE_FOLDER\Axis\webservices\Calculator.dll"/>
<parameter name="allowedMethods" value="add subtract "/>
</service>
Now you have deployed your web service
The wsdl2ws Tool generates the deploy.wsdd and the undeploy.wsdd files needed for the AdminClient. Once we have these files, we have to deploy the web service (in this case the calculator service) with the AdminClient. We do this with the AdminClient.exe which comes with axiscpp binary distribution. A typical invocation of the AdminClient looks like this.
AdminClient <server> <Port> <wsddfile>
AdminClient localhost 80 deploy.wsdd
where local host would be the server where the Axis cpp server is hosted and 80 would be the port at which it runs.
With the WSDL2WS tool you have almost developed your client. What you have
to do next is write a file which has a main method and create an object of the
stub and invoke your methods on that.
1) Create a vc workspace.
2) Create a 'Win32 Console Application'.
3) Add files to this project from the above generated 'ClientOut' folder.
4) Set the include path to the include directory of the binary distribution.
5) Add the following libs to the library modules path of this project.
AXIS_EXTRACT/lib/axis/
Axisclient.lib
AxisServer.lib
AxisTransport.lib
AxisXMLParser.lib
6) Create a file with the main method which looks similar to the following
and add this file to this project.
#include "Calculator.h"
int main()
{
Calculator c;
int result = c.add(40, 20);
printf("result = %d", result);
return 0;
}
7) Now build and create the Client.exe
1) Restart Apache.
2) Run the Calculator.exe
SUCCESS ! If you get the result, you are done.
AxisTransport.dll should be placed in the path that's specified by axiscpp.conf (AXIS_FOLDER/axiscpp.conf).Or with the client.exe.AxisTransport.lib is in [CHECKOUT_ HOME]\c\vc\transport\axis\Release
AxisXMLParser.dll should be placed in the path that's specified by axiscpp.conf.Or with the client.exe.AxisXMLParser libs (libexpat.lib and xerces-c_2.lib(Release) or xerces-c_2D.lib (Debug)) should be in [CHECKOUT_ HOME]\c\lib
Axiscpp.conf file contains the following paths
AXISLOGPATH:XXXX
WSDDFILEPATH:YYYY
AXISTRANSPORT_HTTP:ZZZZ (Not necessary)
AXISXMLPARSER:WWWW
Where XXXX will be the path to a file named AxisLog (The log file)and YYYY
will be the path to the server.wsdd file.ZZZZ will be the path to AxisTransport_D.dll if it's a HTTP(if the selected transport is SMTP then should give that path.WWWW will be the path to AxisXMLParser_D.dll
i.e.
AXISLOGPATH:[APACHE_HOME]\Axis\logs\AxisLog.log
WSDDFILEPATH:[APACHE_HOME]\Axis\conf\server.wsdd
AXISTRANSPORT_HTTP:[APACHE_HOME]\Axis\libs\AxisTransport_D.dll
AXISXMLPARSER:[APACHE_HOME]\Axis\libs\AxisXMLParser_D.dll
Handlers are pluggable components in Axis C++. We have included a set of sample handlers for your reference. You could write your own handlers by following the instructions given for the sample Handlers.
Note: If you are using Client side Handlers you need to enter the following entry in the AXIS_FOLDER/axiscpp.conf configuration file.
CLIENTWSDDFILEPATH:Axis\conf\client.wsdd
After entering this entry to your AXIS_FOLDER/axiscpp.conf configuration file will look like:
AXISLOGPATH:Axis\logs\AxisLog.txt
WSDDFILEPATH:Axis\conf\server.wsdd
CLIENTWSDDFILEPATH:Axis\conf\client.wsdd
We have included the following sample Handlers for your reference.
1) echoStringHeaderHandler (A server side handler sample)
This sample handler will simply echo (i.e send back) the string which you send in the SOAP request.
2)testHandler (A client side handler sample)
This sample handler will simply add a SOAP Header to the generated SOAP request.
Please note that these are very primitive sample handlers and are presented here to give you an idea about writing your own Handlers.
echoStringHeaderHandler
Building the Sample Handlers in VC
The VC dsw file (ServerHandlers.dsw) is available at AXIS_EXTRACT/vc/samples/server/ ServerHandlers.dsw. Open this file and build the project echoStringHeaderHandler. Once the build is successful you will find the DLL (echoStringHeaderHandler.dll) at AXIS_EXTRACT/bin. If you see this DLL at the above location you are done with the first step.
Configuring the Handler
Now edit the AXIS_FOLDER /conf/server.wsdd to include the handler for a particular service.
<service name="Calculator" provider="CPP:RPC" description="Simple Calculator Axis C++ Service ">
<requestFlow name="CalculatorHandlers">
<handler name="ESHHandler" type=" AXIS_EXTRACT/bin/echoStringHeaderHandler.dll">
</handler>
</requestFlow>
<responseFlow name="CalculatorHandlers">
<handler name="ESHHandler" type=" AXIS_EXTRACT/bin/echoStringHeaderHandler.dll">
</handler>
</responseFlow>
<parameter name="allowedMethods" value="add sub mul div "/>
<parameter name="className" value="Axis\webservices\Calculator.dll" />
</service>
Note: Make sure you specify the correct path of the handler dll in the server.wsdd file.
Now you are almost done to run your server side handler.
Restart the Apache server and thats it.
Since this Handler is configured to the Calculator web service in the above step, this Handler will be executed when a client send a SOAP request to the Calculator web service.
testHandler
Building the Sample Handlers in VC
Building testHandler (A client side handler sample)
The VC dsw file (ServerHandlers.dsw) is available at AXIS_EXTRACT/vc/samples/client/ClientHandlers.dsw. Open this file and build the project TestHandler. Once the build is successful you will find the DLL (testHandler.dll) at AXIS_EXTRACT/bin. If you see this DLL at the above location you are done with the first step.
Configuring the Handler
Now edit the AXIS_FOLDER /conf/client.wsdd to include the handler for a particular service.
<service name="Calculator" provider="CPP:DOCUMENT" description="Calculator web service">
<requestFlow name="CalculatorHandlers">
<handler name="TestHandler" type=" AXIS_EXTRACT/bin/testHandler.dll">
</handler>
</requestFlow>
</service>
Note: Make sure you specify the correct path of the handler dll in the client.wsdd file.
Now you are almost done to run your client side handler.
Note: If you are using Client side Handlers you need to enter the CLIENTWSDDFILEPATH entry in the AXIS_FOLDER/axiscpp.conf configuration file. (See above)
Running the Handler
Since this Handler is configured to the Calculator web service in the above step, this Handler will be executed when you run the calculator web service client. (It is at AXIS_EXTRACT/bin/Calculator.exe)
Handler Notes:
1) You can see the Handler behavior through the TCP Monitor. (TCP Monitor is a Axis Java tool)
2) To get an idea of Handlers look at the Handler sample source files.
a. echoStringHeaderHandler (AXIS_EXTRACT/samples/server/echoStringHeaderHandler)
b. testHandler
(AXIS_EXTRACT/samples/client/testHandler)