Axis Developer's Guide

Alpha 3 Version

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

Axis specific information (cvs repository access, mailing list info, etc.) can be found on the Axis Home Page.
Axis uses the Jakarta Project Guidelines.
Code changes should comply with "Code Conventions for the Java Programming Language"

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/wsdl/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.

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 may need to copy them over. Examine the clause that I added to copy over SequenceInfo.java.

Now go to the test/wsdl/Wsdl2javaTestSuite.xmlfile. This file contains the clauses to run wsdl2java. Add a wsdl2java clause. Here is the one for SequenceTest:


    <wsdl2java url="test/wsdl/sequence/SequenceTest.wsdl"
               output="build/work"
               deployscope="session"
               skeleton="yes"
               messagecontext="no"
               noimports="no"
               verbose="no"
               testcase="no">
        <mapping namespace="urn:SequenceTest2" package="test.wsdl.sequence"/>
    </wsdl2java>

Done. Run ant functional-teststo 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, and indicate that functional-tests should continue if a failure occurs.

ant functional-tests -Dtest.functional.SimpleAxisPort=8011 -Dtest.functional.fail=no

The SOAP messages for all of the tests should appear in the tcpmon window.

Running a single functional test

In one window start the server:

java org.apache.axis.transport.http.SimpleAxisServer -p 8080

In another window, first deploy the service you're testing:

java org.apache.axis.client.AdminClient deploy.wsdd

Then bring up the JUnit user interface with your test. For example, to run the the multithread test case:

java junit.swingui.TestRunner -noloading test.wsdl.multithread.MultithreadTestCase