Axis Developer's Guide
Alpha 3 Version
Table of Contents
Introduction
General Guidelines
Development Environment
Compile and Run
Internationalization
Adding Testcases
Debugging
Introduction
This guide is a collection of topics related to developing code for Axis.
General Guidelines
Development Environment
The following packages are required for axis development:
-
ant - java based
build tool
-
junit - testing package
-
xerces - xml processor
-
Install Java 1.3.1 JDK (or later).
The axis jar files are built in the xml-axis/java/build/lib
directory. Here is an example CLASSPATH, which I use when developing
code:
D:\\xerces\\xerces-1_4_2\\xerces.jar
G:\\junit3.7\\junit.jar
G:\\xml-axis\\java\\build\\lib\\wsdl4j.jar
G:\\xml-axis\\java\\build\\lib\\axis.jar
G:\\xml-axis\\java\\build\\lib\\log4j-core.jar
G:\\xml-axis\\java\\build\\lib\\clutil.jar
G:\\xml-axis\\java\\build\\classes
If you access the internet via a proxy server, you'll need to set an environment
variable so that the Axis tests do the same. Set ANT_OPTS to, for example:
-Dhttp.proxyHost=proxy.somewhere.com
-Dhttp.proxyPort=80 -Dhttp.nonProxyHosts="localhost"
Compile and Run
The xml-axis/java/build.xml file is the primary 'make' file used
by ant to build the application and run the tests. The build.xml
file defines ant build targets. Read the build.xml file for
more information. Here are some of the useful targets:
-
compile -> compiles the source and creates xml-axis/java/build/lib/axis.jar
-
javadocs -> creates the javadocs in xml-axis/java/build/javadocs
-
functional-tests -> compiles and runs the functional tests
-
all-tests -> compiles and runs all of the tests
To compile the source code:
cd xml-axis/java
ant compile
To run the tests:
cd xml-axis/java
ant functional-tests
Note: these tests start a
server on port 8080. If this clashes with the port used by your web application
server (such as Tomcat), you'll need to change one of the ports or
stop your web application server when running the tests.
Please run ant functional-tests
and ant all-tests before checking
in new code.
Internationalization
If you make changes to the source code that results in the generation of
text (error messages or debug information), you must follow the following
guidelines to ensure that your text is properly translated.
-
Your text string should be added as a property to the resource.properties
file (xml-axis/java/src/org/apache/axis/utils/resource.properties).
Note that some of the utility applications (i.e. tcpmon) have their own
resource property files (tcpmon.properties).
-
The resource.properties file contains translation and usage instructions.
Here is an example message:
sample00=My name is {0}, and my title is {1}.
-
sample00 is the key that the code will use to access this message.
-
The text after the = is the message text.
-
The {number} syntax defines the location
for inserts.
-
The code should use the static method org.apache.axis.utils.JavaUtils.getMessage
method to obtain the text and add inserts. Here is an example usage:
JavaUtils.getMessage("sample00", "Rich Scheuerle",
"Software Developer");
-
All keys in the properties file should use the syntax
<string><2-digit-suffix>.
-
Never change the message text in the properties
file. The message may be used in multiple places in the code.
Plus translation is only done on new keys.
-
If a code change requires a change to a message,
create a new entry with an incremented 2-digit suffix.
-
All new entries should be placed at the bottom of
the file to ease translation.
Adding Testcases
Editor's Note: We need more effort to streamline
and simplify the addition of tests. We also need to think about categorizing
tests as the test bucket grows.
If you make changes to Axis, please add a test
that uses your change. Why?
-
The test validates that your new code works.
-
The test protects your change from bugs introduced
by future code changes.
-
The test is an example to users of the features of
Axis.
-
The test can be used as a starting point for new
development.
Some general principles:
-
Tests should be self-explanatory.
-
Tests should not generate an abundance of output
-
Tests should hook into the existing junit framework.
-
Each test or group of related tests should have its
own directory in the xml-axis/java/test directory
One way to build a test is to "cut and paste"
and existing tests, and then modify the test to suit your needs.
This approach is becoming more complicated as the different kinds of tests
grow.
Creating a WSDL Test
Here are the steps that I used to create the sequence
test, which generates code from a wsdl file and runs a sequence validation
test:
-
Created a xml-axis/java/test/sequence directory.
-
Created a SequenceTest.wsdl file defining
the webservice.
-
Ran the Wsdl2java emitter to create java files:
java org.apache.axis.wsdl.Wsdl2java -t
-s SequenceTest.wsdl
-
The -t option causes the emitter to generate a *TestCase.java
file that hooks into the test harness. This file is operational without
any additional changes. Copy the *TestCase.java file into the same
directory as your wsdl file. (Ideally only the java files that are
changed need to be in your directory. So this file is not needed,
but please make sure to modify your <wsdl2java ...> clause (described
below) to emit a testcase.
-
The -s option causes the emitter to generate a *SOAPBindingImpl.java
file. The java file contains empty methods for the service.
You probably want to fill them in with your own logic. Copy the *SOAPBindingImpl.java
file into the same directory as your wsdl file. (If no changes are
needed in the java file, you don't need to save it. But you will
need to make sure that your <wsdl2java ...> clause generates a skeleton).
-
Remove all of the java files that don't require modification.
So you should have three files in your directory (wsdl file, *TestCase.java,
and *SOAPBindingImpl.java). My sequence test has an another file
due to some additional logic that I needed.
-
In the build.xml file, locate the "buildTest" target.
You will need to add an <exclude .../> clause to prevent your two java
files from being compiled. (Note it would be nice if there was a
better way to prevent this.) Here is the exclude clause for the sequence
test:
<exclude name="test/sequence/*.java" />
-
The test/build_functional_tests.xml file
controls the building of the tests. Locate the "wsdl-setup" target.
You will see a clause that runs the Wsdl2java code:
<ant antfile="test/wsdl/Wsdl2javaTestSuite.xml"/>
Following this clause you will see some clauses
that copy java files from the test directories. If you have additional
files, you need to copy them over. Examine the clause that I added
to copy over SequenceInfo.java. (Note it would be nice if there was
a better way to do this.)
-
Now go to the test/wsdl/Wsdl2javaTestSuite.xml
file.
This file contains the clauses to run wsdl2java. Add a wsdl2java
clause. Here is the one for SequenceTest:
<!--
Sequence Test -->
<wsdl2java url="test/sequence/SequenceTest.wsdl"
output="build/work"
deployscope="session"
skeleton="yes"
messagecontext="no"
noimports="no"
verbose="no"
testcase="no">
<mapping namespace="urn:SequenceTest2" package="test.sequence"/>
</wsdl2java>
-
Done. Run ant
functional-tests to
verify. Check in your test.
Debugging
Using tcpmon to monitor functional-tests
Here is an easy way to monitor the messages while running functional-tests
(or all-tests).
Start up tcpmon listening on 8080 and forwarding to a different port:
java org.apache.axis.utils.tcpmon 8080 localhost 8011
Run your tests, but use the forwarded port for the SimpleAxisServer:
ant functional-tests -Dtest.functional.SimpleAxisPort=8011
The SOAP messages for all of the tests should appear in the tcpmon window.