Using Apache Axis With Sun ONE Application Server 7
By Alan Beecraft and David Nicholson
(May, 2003)
We want to hear from you! Send us your
FEEDBACK.
Please note our legal disclaimers.
Introduction
The purpose of this article is to explain how to deploy and run Apache Axis
on Sun ONE Application Server 7, to assist with the interoperability testing of
Web services deployed on Sun ONE Application Server 7. Please note that
Sun ONE Application Server 7 already provides high performance Web services
support, so the use of an alternative SOAP implementation, like Apache Axis,
is not officially supported by Sun.
For further information on developing Web services with Sun ONE Application
Server 7, please refer to "Learning More" below.
Sun ONE Application Server 7
Sun ONE Application Server 7 has several benefits for deploying Web
services:
- The Java Web Services Developer Pack is integrated,
including all the Java XML APIs.
- The runtime support to map the APIs to the underlying XML technologies,
such as the Simple Object Access Protocol (SOAP), is optimized for
high performance.
- The Web Services Description Language (WSDL) is supported.
The use of standard protocols and technologies for Web services, such
as SOAP and WSDL, should ensure that loosely-coupled Web services can
interoperate across heterogeneous platforms. However, the standards and
technologies for Web services are evolving rapidly, and this increases the
risk that different implementations may not interoperate exactly
as expected.
Although it is not realistic to test interoperability with all of the
available implementations, it is sensible to attempt some form of
interoperability testing. One alternative implementation of SOAP that
can be used for such testing is Apache Axis, which can be downloaded for free.
Apache Axis
Apache Axis is Copyright © 1999-2001, The Apache Software Foundation.
Axis is simply an implementation of SOAP which can be
deployed on an application server, and which can host Web services.
If you read through the Axis documentation you will find that a lot of it
assumes that Axis is deployed on the Jakarta Tomcat server, but we are
interested in testing Web services deployed on Sun ONE Application
Server 7, not Tomcat.
Therefore, this article explains how to deploy and run Axis on Sun ONE
Application Server 7.
Apache Axis Installation and Setup
These instructions assume that you already have Sun ONE Application Server 7,
with Web services support, installed on your system.
The instructions provided here have been tested using the Solaris Operating Environment (OE),
and on Microsoft Windows XP Professional.
The software versions used during preparation of this article were:
- Java 2 Platform, Standard Edition (J2SE), version 1.4.1_02
- Apache Axis 1.1 Release Candidate 2
- Sun ONE Application Server 7, Standard Edition
As these are the versions we tested with, we recommend that these are the
minimum levels that you should use.
-
Begin by downloading the latest release of Axis from
http://ws.apache.org/axis.
The version used when producing this article was Axis 1.1 Release Candidate 2.
- Install Axis into a directory we shall refer to as
AXIS_HOME
for the remainder of this article:
-
On Microsoft Windows, unzip the downloaded file into a directory, for example
C:\axis-1_1RC2.
-
In the Solaris OE, decompress and untar the downloaded file into a directory,
for example
/opt/axis-1_1RC2.
-
To allow use of the
SOAPMonitor applet, which is supplied with
Axis for monitoring Web services, change to the
AXIS_HOME/webapps/axis directory and compile the applet,
as follows:
javac -classpath WEB-INF/lib/axis.jar SOAPMonitorApplet.java
-
Edit the Sun ONE Application Server's Java 2 Platform, Enterprise Edition (J2EE)
policy file
(
server.policy), to grant certain permissions required by Axis.
This needs to be done before Axis is deployed.
The recommended way to do this is using the J2SE policytool
utility. The policy file can be found in the config directory
for the application server instance, as follows:
You need to create an entry in the policy file similar to the following:
grant codeBase <CODEBASE_URL> {
permission java.lang.RuntimePermission "getClassLoader";
permission java.lang.RuntimePermission "createClassLoader";
permission java.net.SocketPermission "*", "connect,accept,resolve";
permission java.io.FilePermission "<>", "read,write,delete";
};
You need to replace <CODEBASE_URL> with a quoted string
that reflects where the Axis Web module will be deployed, for example:
CAUTION: It is important that the entry in the server.policy
file reflects the correct location of the deployed Axis web module.
If you ever need to redeploy the Axis Web module, you should "undeploy"
the original version first; otherwise the module location may change
from axis_1 to axis_2, and the entry in the policy
file will no longer match.
-
Start (or restart) the Sun ONE Application Server instance to ensure that
the policy file amendments are in place before you deploy the Axis Web module.
-
You are now ready to deploy Axis on the Sun ONE Application Server instance.
For ease of deployment, we strongly recommend that you deploy Axis as a
Web module, so change to the
AXIS_HOME/webapps/axis directory
and generate the war file for the Web module:
jar -cvf axis.war *
You have a choice as to how you deploy the Axis Web module. This article will
describe how to deploy the module using both the browser-based
Administration Interface, and the command line:
-
To deploy using the Administration Interface, specify the URL of the
administration server in the browser and log in with the administrator
username and password.
When the administration interface appears, go to the Domains panel
on the left side and expand the node for the application server instance,
for example server1. Next, expand the Applications
node and click the Web Apps node. Switch to the panel on the
right side and click the button labeled Deploy....
Next, enter the File Path for the axis.war file,
for example AXIS_HOME/webapps/axis/axis.war, or use the
button labeled Browse... to locate the file. Finally, start
the deployment of the Web module by clicking the button labeled
OK and then clicking the OK
button on the following panel.
-
To deploy using the command line, change to the
AXIS_HOME/webapps/axis directory and specify the command to
deploy the Axis Web module as follows:
asadmin deploy --user admin_user --password
admin_password --host admin_host --port
admin_port --type web --instance instance_name axis.war
You need to replace the variables with the correct values for your installation,
as indicated below:
admin_user is the administrative user for the administration server.
admin_password is the administrative password corresponding to
the administrative user.
admin_host is the host name of the machine hosting the
administration server, for example localhost.
admin_port is the administrative port number associated
with the administration server, for example 4848.
instance_name is the name of the server instance that the
web module is to be deployed to, for example server1.
-
Providing that Axis deployed successfully, you should be able to validate the
installation:
Start at the Axis Welcome page by specifying the
following URL in your Web browser:
http://host:port/axis/index.html
You need to replace the variables with the correct values for your installation,
as indicated below:
host is the host name of the machine hosting the
application server instance, for example localhost.
port is the port number used by the HTTP listener
for the application server instance, for example 80.
To validate the Axis installation, Axis supplies a test page, called
happyaxis.jsp which verifies that the Axis installation
can find the libraries it requires.
To invoke happyaxis, click the link labeled "Validate the
local installation's configuration".
If successful, the Axis Happiness Page should confirm that all
needed components have been found, as in this example output:
Found SAAJ API (javax.xml.soap.SOAPMessage)
Found JAX-RPC API (javax.xml.rpc.Service)
Found Apache-Axis (org.apache.axis.transport.http.AxisServlet)
Found Jakarta-Commons Discovery (org.apache.commons.discovery.Resource)
Found Jakarta-Commons Logging (org.apache.commons.logging.Log)
Found Log4j (org.apache.log4j.Layout)
Found IBM's WSDL4Java (com.ibm.wsdl.factory.WSDLFactoryImpl)
Found JAXP implementation (javax.xml.parsers.SAXParserFactory)
Found Activation API (javax.activation.DataHandler)
You should be able to click any of the links from the Axis Welcome page
to exercise different features of the Axis installation.
-
If the installation passed the validation testing, you are ready to deploy
a sample Web service. Axis supplies several examples, documented
in the Axis User's Guide. You are encouraged to read the User's Guide and
try any of the examples that interest you.
However, to avoid merely repeating the material in the User's Guide, the
remainder of this article will show how to use the SOAPMonitor
applet to monitor an example Web service.
For the example Web service, we selected
AXIS_HOME/samples/userguide/example3
because it is a Java platform RPC service, and because it also uses the Axis Web
Service Deployment Descriptor (WSDD) format.
Before you start deploying the Web services, we recommend that you set an
environment variable, which we shall call AXISCLASSPATH, to
include the jar files needed to run the examples, as follows:
AXIS_HOME/lib/axis.jar
AXIS_HOME/lib/jaxrpc.jar
AXIS_HOME/lib/saaj.jar
AXIS_HOME/lib/commons-logging.jar
AXIS_HOME/lib/commons-discovery.jar
AXIS_HOME/lib/wsdl4j.jar
A JAXP-1.1 compliant XML parser (see Note below).
Note: Apache Axis recommends their own Xerces parser, but Sun ONE
Application Server 7 already includes a suitable parser that you can use:
-
In the Solaris OE, the install location of the parser is typically
/usr/share/lib, so add the following to the
AXISCLASSPATH:
/usr/share/lib/xercesImpl.jar:/usr/share/lib/dom.jar
-
On Microsoft Windows, the install location of the parser is typically
C:\Sun\AppServer7\share\lib, so add the following to the
AXISCLASSPATH:
C:\Sun\AppServer7\share\lib\xercesImpl.jar;C:\Sun\AppServer7\share\lib\dom.jar
-
The first service you will deploy is the
SOAPMonitor service
that will be used to monitor the SOAP messages sent and received by the
MyService example Web service.
To deploy the SOAPMonitor service, change to a temporary
directory and create a Web Service Deployment Descriptor for the
SOAPMonitor service, which is typically called
deploy.wsdd.
This file should contain the following:
<deployment xmlns="http://xml.apache.org/axis/wsdd/"
xmlns:java="http://xml.apache.org/axis/wsdd/providers/java">
<handler name="soapmonitor"
type="java:org.apache.axis.handlers.SOAPMonitorHandler">
<parameter name="wsdlURL"
value="/axis/SOAPMonitorService-impl.wsdl"/>
<parameter name="namespace"
value="http://tempuri.org/wsdl/2001/12/SOAPMonitorService-impl.wsdl"/>
<parameter name="serviceName" value="SOAPMonitorService"/>
<parameter name="portName" value="Demo"/>
</handler>
<service name="SOAPMonitorService" provider="java:RPC">
<parameter name="allowedMethods" value="publishMessage"/>
<parameter name="className"
value="org.apache.axis.monitor.SOAPMonitorService"/>
<parameter name="scope" value="Application"/>
</service>
</deployment>
-
You are now ready to deploy the
SOAPMonitor Web service using the
Axis AdminClient:
You need to replace the variables with the correct values for your installation,
as indicated below:
host is the host name of the machine hosting the
application server instance, for example localhost.
port is the port number used by the HTTP listener
for the application server instance, for example 80.
With the service deployed you can access the applet from your Web browser,
using the same values for host and
port. For example:
http://host:port/axis/SOAPMonitor
-
In order to monitor the
MyService example Web service, it is
necessary to set up request and response flows that go through the
SOAPMonitor handler. To do this, change to the
AXIS_HOME/samples/userguide/example3
directory and edit the deploy.wsdd file for the
the Web service to add the flows, as follows:
- Before:
...
<service name="MyService" provider="java:RPC">
<parameter name="className" value="samples.userguide.example3.MyService"/>
<parameter name="allowedMethods" value="*"/>
...
- After:
...
<service name="MyService" provider="java:RPC">
<requestFlow>
<handler type="soapmonitor"/>
</requestFlow>
<responseFlow>
<handler type="soapmonitor"/>
</responseFlow>
<parameter name="className" value="samples.userguide.example3.MyService"/>
<parameter name="allowedMethods" value="*"/>
...
-
You are now ready to deploy the
MyService example Web service
with the Axis AdminClient:
You need to replace the host and port
with the correct values for the machine running the application server instance
that you are connecting to.
-
You can also confirm that the deployment was successful with the Axis
AdminClient:
You need to replace the host and port
with the correct values for the machine running the application server instance
that you are connecting to.
You should see entries for the SOAPMonitor and
MyService Web services in the output.
-
Finally, you are ready to test the Web service. Change directories to
AXIS_HOME and invoke the MyService example
Web service, as follows:
- In the Solaris OE, enter the following command on one line:
java -classpath $AXISCLASSPATH:. samples.userguide.example3.Client -lhttp://host:
port/axis/services/MyService "Successful Test"
- On Microsoft Windows, enter the following command on one line:
java -classpath %AXISCLASSPATH%;. samples.userguide.example3.Client -lhttp://hosy:
port/axis/services/MyService "Successful Test"
You need to replace the host and port
with the correct values for the machine running the application server instance
that you are connecting to.
If successful, you should see your input echoed back, similar to this:
You typed : Successful Test
In addition, the SOAPMonitor display in your Web browser
should show the SOAP request and response messages from the
MyService Web service.
Conclusion
This article has provided instructions on how to install, deploy and run Apache
Axis to assist with the interoperability testing of Web services deployed
on Sun ONE Application Server 7.
The actual format and content of your interoperability testing is ultimately
dependent on the nature of the Web services to be deployed. For further
information on the development, deployment and testing of Web services you
are encouraged to investigate the example Web services supplied with
Sun ONE Application Server 7 and Apache Axis.
For further information on developing Web services with Sun ONE Application
Server 7, use the following:
For further information on Apache Axis, use the following:
|
