SOAP Development with TOMCAT

1. TOMCAT Installation and Configuration 1.1 RAMS Request for TOMCAT Go to https://rams.cognizant.com Click on Request Software Request Configure the Request Details as shown:
Request Details
Request Project Project ID ID Name Resource Category Resource Version Item Release Date Comments

*1

*2

*3

Open Source

Apache Tomcat

5.0.28 04/01/2012

Note: Seat mapping must be done before raising this request Details
*1 this is automatically generated when request is raised successfully. *2 this is automatically generated when *3 is selected from the project list. Check your assignment in https://peoplesoft ESA My Assignments Select the Resource Category, Resource Item, Version (your choice) as shown. (The soap development was done with the above version) Select your Asset No (your PC# no) and check the Check for Valid Asset box The release Date is the Required Till field. Check your Seat No. and click on Submit. Follow up the process after request is submitted successfully with NSS.

1.2 Checking the Configuration of TOMCAT Installation will be done by GSD-NSS people. In our case, let us consider that the TOMCAT is installed to D:\tomcat-5.0.28. This will be your <TOMCAT_HOME> directory. Go to <TOMCAT_HOME>\bin Run startup.bat script file. The output will be like Apr 20, 2011 9:34:52 AM org.apache.coyote.http11.Http11Protocol init INFO: Initializing Coyote HTTP/1.1 on http-8080 Apr 20, 2011 9:34:53 AM org.apache.catalina.startup.Catalina load INFO: Initialization processed in 3985 ms

Apr 20, 2011 9:34:55 AM org.apache.catalina.core.StandardService start INFO: Starting service Catalina Apr 20, 2011 9:34:55 AM org.apache.catalina.core.StandardEngine start INFO: Starting Servlet Engine: Apache Tomcat/5.0.28 Apr 20, 2011 9:34:55 AM org.apache.catalina.core.StandardHost start INFO: XML validation disabled Apr 20, 2011 9:34:55 AM org.apache.catalina.core.StandardHost getDeployer INFO: Create Host deployer for direct deployment ( non-jmx ) Apr 20, 2011 9:34:55 AM org.apache.catalina.core.StandardHostDeployer install INFO: Processing Context configuration file URL file:D:\tomcat-5.0.28\conf\Catal ina\localhost\admin.xml Apr 20, 2011 9:34:59 AM org.apache.struts.util.PropertyMessageResources <init> INFO: Initializing, config='org.apache.struts.util.LocalStrings', returnNull=tru e Apr 20, 2011 9:34:59 AM org.apache.struts.util.PropertyMessageResources <init> INFO: Initializing, config='org.apache.struts.action.ActionResources', returnNul l=true Apr 20, 2011 9:35:06 AM org.apache.struts.util.PropertyMessageResources <init> INFO: Initializing, config='org.apache.webapp.admin.ApplicationResources', retur nNull=true Apr 20, 2011 9:35:26 AM org.apache.catalina.core.StandardHostDeployer install INFO: Processing Context configuration file URL file:D:\tomcat-5.0.28\conf\Catal ina\localhost\balancer.xml Apr 20, 2011 9:35:27 AM org.apache.catalina.core.StandardHostDeployer install INFO: Processing Context configuration file URL file:D:\tomcat-5.0.28\conf\Catal ina\localhost\manager.xml Apr 20, 2011 9:35:42 AM org.apache.catalina.core.StandardHostDeployer install INFO: Installing web application at context path /soap from URL file:D:/tomcat-5 .0.28/webapps/soap Apr 20, 2011 9:35:42 AM org.apache.catalina.core.StandardHostDeployer install INFO: Installing web application at context path /jsp-examples from URL file:D:\ tomcat-5.0.28\webapps\jsp-examples Apr 20, 2011 9:35:45 AM org.apache.catalina.core.StandardHostDeployer install INFO: Installing web application at context path from URL file:D:\tomcat-5.0.28 \webapps\ROOT Apr 20, 2011 9:35:45 AM org.apache.catalina.core.StandardHostDeployer install INFO: Installing web application at context path /servlets-examples from URL fil e:D:\tomcat-5.0.28\webapps\servlets-examples Apr 20, 2011 9:35:47 AM org.apache.catalina.core.StandardHostDeployer install INFO: Installing web application at context path /tomcat-docs from URL file:D:\t omcat-5.0.28\webapps\tomcat-docs Apr 20, 2011 9:35:47 AM org.apache.catalina.core.StandardHostDeployer install INFO: Installing web application at context path /webdav from URL file:D:\tomcat -5.0.28\webapps\webdav Apr 20, 2011 9:35:47 AM org.apache.coyote.http11.Http11Protocol start INFO: Starting Coyote HTTP/1.1 on http-8080

Apr 20, 2011 9:35:49 AM org.apache.jk.common.ChannelSocket init INFO: JK2: ajp13 listening on /0.0.0.0:8009 Apr 20, 2011 9:35:49 AM org.apache.jk.server.JkMain start INFO: Jk running ID=0 time=157/609 config=D:\tomcat-5.0.28\conf\jk2.properties Apr 20, 2011 9:35:49 AM org.apache.catalina.startup.Catalina start INFO: Server startup in 55422 ms

The highlighted lines show that tomcat is listening to port 8080. So open your web browser and point to http://localhost:port/ where your port will be 8080, so the actual URL is http://localhost:8080/ . If you had installed successfully, you will see your tomcat homepage(i.e., index.jsp page) as shown below

Stop the Tomcat by running the script shutdown.bat found in <TOMCAT_HOME>\bin directory.

2. Configurating Apache-SOAP in TOMCAT 2.1 Deploying SOAP using TOMCAT Download the following SOAP v2.3.1 bin to a directory and extract its contents.
soap-bin-2.3.1.zip

You will find a soap.war file in <Soap-DIR>\webapps, soap documentation in <Soap-DIR>\docs\index.jsp, sample soap examples in <Soap-DIR>\samples directory and soap.jar file in <Soap-DIR>\lib directory where <Soap-DIR> is the extracted folder path.

Copy the soap.war file into <TOMCAT_HOME>\webapps\ directory.

2.2 Integrating components required to execute SOAP clients and services The following jars will be required by SOAP: soap.jar (available in the bin file, as pointed above) mail.jar activation.jar xerces.jar Additional jars that may be required by SOAP according to your implementation: xalan.jar serializer.jar xmlParserAPIs.jar xercesImpl.jar All the above jars must be copied to <TOMCAT_HOME>\common\lib\ directory. Note: Do not include both xerces.jar and xercesImpl.jar parser APIs. Include only either of them in the above directory Once the above set up is done, start your Tomcat server. This will automatically explode the war file in webapps directory into the soap directory. 2.3 Checking the Integration of SOAP in TOMCAT If SOAP is integrated properly into TOMCAT, you should be able to view the SOAP Web Application by pointing your Web Browser to http://localhost:8080/soap . You should see the following page

At this point of time, you should be able to use the SOAP admin tool by clicking on the Run link. In this, you can LIST, DEPLOY and UN-DEPLOY services, as well as view the details of each service. 3. Deploying SOAP Services Let us consider the path of exploded soap directory to be <SOAP_HOME>. To make your classes available, the path for classes to be published as soap service, as well as its client classes should be put in the directory <SOAP_HOME>\WEB-INF\classes\ . Note: copy only the compiled class files into this directory. Do not include java files. In order to publish a class as a SOAP service, we need to develop a Deployment Descriptor for that. This deployment descriptor xml is assumed to be saved in <SOAP_HOME>\WEB-INF\ directory to deploy the xmls from command line. 3.1 Introduction to custom batch scripts used for SOAP deployment The following custom batch scripts for deployment, un-deployment of services, as well as to run the clients can be used to facilitate the SOAPifying process.

soap_deploy.bat

soap_undeploy.bat

soap_query.bat

soap_client.bat

Copy the above batch scripts to the parent directory of tomcat, i.e. if tomcat is installed in D: drive, copy these to D:\ root directory. In order to edit the lines of the above batch scripts, open it with Notepad++ editor. The code snippet for soap_deploy.bat is as given below ================================================================= set CATALINA_HOME=D:\tomcat-5.0.28 set COMMON_LIB=%CATALINA_HOME%\common\lib if not "%CLASSPATH%"=="C:\Program Files\Java\jdk1.5.0_01\lib;" goto doneSetPath :beginSetPath set CLASSPATH=%COMMON_LIB%\activation.jar;%CLASSPATH% set CLASSPATH=%COMMON_LIB%\mail.jar;%CLASSPATH% set CLASSPATH=%COMMON_LIB%\xalan.jar;%CLASSPATH% set CLASSPATH=%COMMON_LIB%\serializer.jar;%CLASSPATH% set CLASSPATH=%COMMON_LIB%\xmlParserAPIs.jar;%CLASSPATH% set CLASSPATH=%COMMON_LIB%\xercesImpl.jar;%CLASSPATH% set CLASSPATH=%COMMON_LIB%\soap.jar;%CLASSPATH% echo New CLASSPATH is %CLASSPATH% :doneSetPath echo Setting CLASSPATH Done ================================================================== This part of the code snippet is almost the same in other batch scripts as well. The lines that will have to be changed in all the batch scripts are: set CATALINA_HOME=D:\tomcat-5.0.28 This CATALINA_HOME variable must point to your tomcat installation directory, i.e. <TOMCAT_HOME> directory as we had mentioned before. The lines between the labels :beginSetPath and :doneSetPath shows the CLASSPATH setting done for every jar that is additionally added by you in the <TOMCAT_HOME>\common\lib\ directory to run the SOAP service classes and their clients. So if any jar that is required is added to the above directory, please update the batch scripts by including a line like this set CLASSPATH=%COMMON_LIB%\your.jar;%CLASSPATH% anywhere before setting the CLASSPATH for parser APIs.

3.2 Deployment of SOAP with an example 3.2.1 SOAP Service For our listing, let us consider a Simple Calculator service as shown that can simply add and subtract numbers and return the results.
package calculator; public class CalcService { public int add(int p1, int p2) { return p1 + p2; } public int subtract(int p1, int p2) { return p1 - p2; } }

It defines two public methods, add() and subtract(), each with a parameter list containing two native ints. To make this class available, build and copy it into the <TOMCAT_HOME>/webapps/soap/WEB-INF/classes/calculator/ directory. 3.2.2 Deployment Descriptor The next step is to create a Deployment Descriptor for your SOAP service class. This description is required for the service to be published as an Apache SOAP service. The Deployment Descriptor for our Simple Calculator is as given below:
<isd:service xmlns:isd="http://xml.apache.org/xml-soap/deployment" id="urn:calcserver"> <isd:provider type="java" scope="Application" methods="add subtract"> <isd:java class="calculator.CalcService" static="false"/> </isd:provider> <isd:faultListener>org.apache.soap.server.DOMFaultListener</isd:faultListener> </isd:service>

The deployment descriptor for most of the service contains only three elements that we need to look at. The first element is the service element, which defines two attributes, the XML namespace and the unique ID of the service to be deployed. The ID defined in the service element must be unique, since this attribute is used to uniquely identify a published SOAP service.

The next element we need to examine is the provider element. It defines the actual implementation of the SOAP service. It does this with three attributes, each of which is defined as follows: Attributes of the Provider Element type The type attribute defines the implementation type of the SOAP service. We defined our service as a Java service. The other types are Script and User-Defined. scope The scope attribute defines the lifetime of the SOAP service. The possible values are Page, Request, Session, and Application. These scope values map one-to-one with the scope values defined by the JSP specification. methods The methods attribute defines the names of the methods that can be invoked on this service object. This list should be a space-separated list of method names.

The final element of the deployment descriptor is the java element. This element contains a single attribute, class, which names the fully qualified class of the named service. The additional element is the faultListener element. This defines the exception handling mechanism of SOAP. It handles all the exceptions related to SOAP service class as well as its client class, and wraps them in a SOAP Fault Message containing a base set of information about the error which occurred. The fault handler is for handling this fault is entered in the scope of this element. Apache SOAP provides two basic fault handlers: org.apache.soap.server.DOMFaultListener org.apache.soap.server.ExceptionFaultListner Both of these augment the SOAP Fault message with additional information about the fault; the first by adding a DOM element representing the root exception which occurred, and the second by wrapping the root exception in a Parameter. Most people will probably find the first to be more useful. 3.2.3 Running the Server-Side Admin Tool to Manage Services Now that we have defined our SOAP service and its deployment descriptor, we can publish it so that it can start servicing requests. To do this, you need to first compile the service and make sure it is in <TOMCAT_HOME>/webapps/soap/WEB-INF/classes/calculator/ directory. After you have compiled the service, you're ready to deploy it. The Apache SOAP Project is packaged with two administration tools -- a graphical tool and a command-line tool. They both allow you to easily deploy and undeploy services to the SOAP server.

The three functions provided by these tools are listed below: The deploy function allows you to deploy a new service to a SOAP server. The undeploy function removes an existing SOAP service from a SOAP server. The list function lists all deployed SOAP services. The Graphical tool for deployment

Open the SOAP Admin by pointing your browser to http://localhost:8080/soap/admin/ . If you click on list, it will list all the deployed services if any. To deploy a new service class, we need to create a Deployment descriptor for the class to be published as service. This graphical tool automatically generates the Deployment Descriptor based on the fields you enter in the Deploy screen. Click on the Deploy link to open up the deployment screen. This will have a Service Deployment Descriptor Template where you need to fill the required fields which are the attributes given in the deployment descriptor xml. Once done, click on deploy button at the end. To verify, click on List to see the deployed services. If you see the ID of the service deployed, then you have successfully deployed your service class SOAP service. Select a service to see its details.

To Un-deploy, click on Un-deploy and you will see a list of deployed services. Select a service to deploy, and you will see a message like OK, service named 'urn:calcserver' undeployed successfully! 3.2.4 Running the Command-Line Tool to Manage Services SOAP command-line management functions are implemented by the org.apache.soap.server.ServiceManagerClient class. We'll go through each of its functions in this section. As we cover the following commands, you should note that each command references a servlet named rpcrouter. This servlet is at the core of all SOAP actions. It performs all service management and execution.

List The list command lists all currently deployed services. To execute the list command, type the following line: java org.apache.soap.server.ServiceManagerClient http://localhost:8080/soap/servlet/rpcrouter list If you have not published any other SOAP services, you should get a response that shows no deployed services. If you examine this command, you see that it executes the Java application ServiceManagerClient with two parameters: the location of the SOAP server, and the command to perform (list, in this case).

Deploy The deploy command deploys our service to the SOAP server. This command also uses the ServiceManagerClient with the deployment descriptor describing the SOAP service. To deploy our service, execute the following command: java org.apache.soap.server.ServiceManagerClient http://localhost:8080/soap/servlet/rpcrouter deploy DeploymentDescriptor.xml This command takes three parameters: the URL to the SOAP server, the command deploy, and the file containing our deployment descriptor. After you have executed this command, execute the list command. You should now see output listing urn:calcserver, which is the unique ID of our service.

Undeploy The undeploy command removes a previously deployed service. To execute the undeploy command, type the following line: java org.apache.soap.server.ServiceManagerClient http://localhost:8080/soap/servlet/rpcrouter undeploy urn:calcserver The undeploy command takes three parameters: the location of the SOAP server, the actual command to perform (in this case, the undeploy command), and the name of the service to remove.

3.2.5 SOAP Client Now that we have a service defined and deployed, let's write a client that will execute one of the service's methods. The Apache SOAP Project provides a client-side API that makes it extremely simple to create SOAP clients. An example client, which we will use to execute the subtract method of our service, is shown here. package calculator; import java.net.URL; import java.util.Vector; import org.apache.soap.Constants; import org.apache.soap.Fault; import org.apache.soap.rpc.Call; import org.apache.soap.rpc.Parameter; import org.apache.soap.rpc.Response; public class CalcClient { public static void main(String[] args) throws Exception { //create a URL object which is a SOAP Handler referencing the rpcrouter URL url = new URL ("http://localhost:8080/soap/servlet/rpcrouter"); Integer p1 = new Integer(args[0]); Integer p2 = new Integer(args[1]); // Build the call. Call call = new Call();

call.setTargetObjectURI("urn:calcserver");// set the target Service Class to be executed call.setMethodName("subtract");// set the target Service Method to be executed call.setEncodingStyleURI(Constants.NS_URI_SOAP_ENC);// set the encoding style used in RPC call for the return value // create a parameter list Vector params = new Vector(); // add the parameter(s) to be passed to the named Service Method params.addElement(new Parameter("p1", Integer.class, p1, null)); params.addElement(new Parameter("p2", Integer.class, p2, null)); // add the parameter(s) to the Call object call.setParams (params); // make the call: note that the action URI is empty because the // XML-SOAP rpc router does not need this. This may change in the // future. Response resp = call.invoke(url, "" ); // check for fault in the method invocation if ( resp.generatedFault() ) { // if fault is generated, get the fault from the response Fault fault = resp.getFault (); System.out.println("The call failed: "); System.out.println("Fault Code = " + fault.getFaultCode()); System.out.println("Fault String = " + fault.getFaultString()); } else { // if there is no fault in the method invocation, get the result Parameter result = resp.getReturnValue();//get the parameter returned from the response System.out.println(result.getValue());//get the value of the parameter } } }

This client follows a simple process that is common to most SOAP RPC clients. It first creates a URL referencing the rpcrouter (which we noted earlier) on the HTTP server localhost. This is done in the following code snippet:

URL url = new URL ("http://localhost:8080/soap/servlet/rpcrouter"); The next step performed by the client application is to parse the arguments from the command line. These values will be passed to the SOAP service in a subsequent method. The values created will be integers. After the client has parsed to command-line arguments, it creates an instance of an org.apache.soap.rpc.RPCMessage.Call. The Call object is the main interface used when executing a SOAP RPC invocation.
Call call = new Call(); call.setTargetObjectURI("urn:calcserver"); call.setMethodName("subtract"); call.setEncodingStyleURI(Constants.NS_URI_SOAP_ENC); Vector params = new Vector(); params.addElement(new Parameter("p1", Integer.class, p1, null)); params.addElement(new Parameter("p2", Integer.class, p2, null)); call.setParams (params);

To use the Call object, we first tell it which service we want to use. We do this by calling the setTargetObjectURI, passing it the name of the service that we want to execute. We then set the name of the service method we want to execute using the setMethodName() method, with the name of the method we want to execute. The next step is to set the encoding style used in the RPC call. For most of the java types, encoding is used for returning value and the encoding style used is Constants.NS_URI_SOAP_ENC. For Element.class type, encoding style Constants.NS_URI_LITERAL_XML must be used for passing the parameter to the method and if the method is returning in Element.class type then we should specify the encoding style for that as well. The final step is to add the parameters that are expected when executing the named method. This is done by creating a Vector of Parameter objects and adding them to the Call object using the setParams() method. All of these steps are completed using the above code snippet. The next step performed by the client application is to call the service method that we are interested in. This is done using invoke() with the URL we created earlier. Here is the snippet of code calling the invoke() method: Response resp = call.invoke(url, "" ); You will notice the return value of the invoke() method is a Response object. The Response object returns two very important items -- an error code and the value returned from the executed service method. You check for an error by calling the generatedFault() method. This method will return true if there was an error returned; then you can check the getFault() method. If generatedFault() returns false, you can then get the value returned in the Response object,

using the Response.getReturnValue() method. The following code snippet shows how you should process the response of an invoke():
if ( resp.generatedFault() ) { Fault fault = resp.getFault(); System.out.println("The call failed: "); System.out.println("Fault Code = " + fault.getFaultCode()); System.out.println("Fault String = " + fault.getFaultString()); } else { Parameter result = resp.getReturnValue(); System.out.println(result.getValue()); }

Now to test your client and service, compile the client and execute it using the following command line:
java calculator.CalcClient 98 90

Note: At this point, you should have the CalcService deployed and Tomcat should be running. 3.2.6 Using the Batch Scripts to Deploy, Un-deploy and run the client The Prerequisites for using these scripts are: Copy the batch scripts to the parent directory of tomcat, i.e. if tomcat is installed in D: drive, copy these to D:\ root directory. Please refer to section 3.1 for more details All the Deployment descriptors must be saved in <TOMCAT_HOME>/webapps/soap/WEB-INF directory. All the compiled SOAP service classes and its client classes must be saved in <TOMCAT_HOME>/webapps/soap/WEB-INF/classes directory. Go to Start Run and type cmd. Change directory to D:\

To Deploy SOAP Service Type this command:

soap_deploy.bat DeploymentDescriptor.xml

To Un-Deploy SOAP Service Type this command:

soap_undeploy.bat urn:calcserver

enter the service ID as the second parameter as shown above. To Run the SOAP-Client

Type this command:

soap_client.bat calculator.CalcClient 98 90

where 98 90 are the arguments passed to the java class calculator.CalcClient