|< Free Open Study >|| |
The Apache project provides two different Java SOAP servers - Apache SOAP and Axis. We will use both of them in this chapter but we'll begin with the older (and for the time being, more stable) Apache SOAP.
First, download Apache SOAP from http://xml.apache.org/soap/. The Apache SOAP download includes a web archive named soap.war. Copy this file into %CATALINA_HOME%/webapps. Then expand the archive (making sure that you preserve the directory structure). This will create a soap directory. For Apache SOAP to run correctly the web application needs access to the following JAR files:
mail.jar - available from http://java.sun.com/products/javamail/
activation.jar - available from http://java.sun.com/products/beans/glasgow/jaf.html
xerces.jar - available from http://xml.apache.org
We can either place these JAR files in %CATALINA_HOME%/webapps/soap/WEB-INF/lib or we can place them in the server classpath by copying them to %CATALINA_HOME%/common/lib.
Now we're ready to go. We can test our installation by starting Tomcat and navigating to http://localhost:8080/soap/servlet/rpcrouter. If Apache SOAP is working correctly we will see this message:
With Apache SOAP installed, we're ready to deploy our web service.
We have a choice of two methods to use to deploy web services (such as our Exchange Rate service) to the server. In both cases, we need to tell the server what methods of which class we want to expose as web services. In our case we want to expose the getExchangeRate() method of ExchangeRate.
First we'll deploy the service using a deployment descriptor. Save the following as SoapDeploy.xml:
<isd:service xmlns:isd="http://xml.apache.org/xml-soap/deployment" >
The <service> element assigns a name to the service (set in the id attribute). This is the name our clients will use to reference the service. We use SoapExchangeRate.
A <provider> element tells the server what is to be exposed as a service. Apache SOAP can expose services written in languages other than Java, so we use the type attribute to tell it we want to expose a Java class. The scope attribute indicates the lifetime of the object. There are three supported lifetimes:
Request - the object will be removed after this request has completed
Session - the object will last for the current lifetime of the HTTP session
Application - the object will last until the servlet servicing the requests is terminated
We will use Request. The methods attribute provides the name of the method(s) we want to expose, in our case getExchangeRate():
<isd:provider type="java" scope="Request" methods="getExchangeRate">
The next element identifies the Java class that implements the method:
<isd:java /> </isd:provider> <isd:faultListener> org.apache.soap.server.DOMFaultListener </isd:faultListener> </isd:service>
The next step is to copy the ExchangeRate.class file into the %CATLALINA_HOME%/webapps/soap/WEB-INF/classes directory and to restart Tomcat. Then, to deploy the service we run the following command:
java org.apache.soap.server.ServiceManagerClient http://localhost:8080/soap/servlet/rpcrouter deploy SoapDeploy.xml
The classpath of our command prompt (not the server) must include soap.jar, xerces.jar, mail.jar, and activation.jar. The following command will list all the deployed services:
java org.apache.soap.server.ServiceManagerClient http://localhost:8080/soap/servlet/rpcrouter list
We can use this command to check that our service has been successfully deployed:
It is also possible to deploy a service by using a browser based service manager. This can be accessed at http://localhost:8080/soap/admin/index.html:
Selecting the Deploy option offers a form that prompts for the same information that we have entered in the deployment descriptor. While this web interface may seem to be easier to use, it quickly gets tiresome if you need to re-deploy the service several times. However, the web interface does provide a convenient means of listing and removing deployed services:
Axis is the next generation SOAP server being developed by the Apache project. Although it is in the very early stages of availability Axis already has some significant strengths, foremost of which is the ease of deployment of a Java class as web service.
For the next (very quick) exercise you will need to Axis installed in %CATLALINA_HOME%/webapps/axis. Axis can be downloaded from http://xml.apache.org/axix/ and be is installed easily by following the installation instructions included with the download.
To deploy our web service we only need to rename ExchangeRate.java as ExchangeRate.jws and copy it to the %CATLAINA_HOME%/webapps/axis directory. That's all there is to it. Once the axis web application is running clients can access our Axis based service at http://localhost:8080/axis/ExchangeRate.jws.
Now that we've seen how we can create and deploy web services, we're ready to create some agents that can interact with them.
|< Free Open Study >|| |