Axis Developer's Guide

Table of Contents

Introduction

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"
• When fixing a "Axis Bugzilla Bug" include the href of the bug in the cvs commit message.
• Incompatible changes to published Axis interfaces should be avoided where possible. When changes are necessary, for example to maintain or improve the overall modularity of Axis, the impact on users must be considered and, preferably, documented.
• If you are making a big change that may affect interoperability, please run the echotest2 round 2 interop test to ensure that your change does not result in any new interop failures. You will also need the client_deploy.wsdd. Here are the nightly interop test results.

Development Environment

• 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\\classes

-Dhttp.proxyHost=proxy.somewhere.com -Dhttp.proxyPort=80 -Dhttp.nonProxyHosts="localhost"

Logging/Tracing

Using the Logger SPI

To use the JCL SPI from a Java class, include the following import statements:

import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
 

public class CLASS
{
   private static Log log = LogFactory.getLog(CLASS.class);
   ...
 

Messages are logged to a logger, such as log by invoking a method corresponding to priority: The Log interface defines the following methods for use in writing log/trace messages to the log:

log.fatal(Object message);
log.fatal(Object message, Throwable t);
log.error(Object message);
log.error(Object message, Throwable t);
log.warn(Object message);
log.warn(Object message, Throwable t);
log.info(Object message);
log.info(Object message, Throwable t);
log.debug(Object message);
log.debug(Object message, Throwable t);
log.trace(Object message);
log.trace(Object message, Throwable t);

In addition to the logging methods, the following are provided:

log.isFatalEnabled();
log.isErrorEnabled();
log.isWarnEnabled();
log.isInfoEnabled();
log.isDebugEnabled();
log.isTraceEnabled();

Guidelines

Message Priorities

• fatal - Severe errors that cause the AXIS server to terminate prematurely. Expect these to be immediately visible on a console, and MUST be internationalized.

 
• error - Other runtime errors or unexpected conditions. Expect these to be immediately visible on a console, and MUST be internationalized.

 
• warn - Use of deprecated APIs, poor use of API, Almost errors, other runtime situations that are undesirable or unexpected, but not necessarily "wrong". Expect these to be immediately visible on a console, and MUST be internationalized.

 
• info - Interesting runtime events (startup/shutdown). Expect these to be immediately visible on a console, so be conservative and keep to a minimum. These MUST be internationalized.

 
• debug - detailed information on flow of through the system. Expect these to be written to logs only. These NEED NOT be internationalized, but it never hurts...

 
• trace - more detailed information. Expect these to be written to logs only. These NEED NOT be internationalized, but it never hurts...

Configuring the Logger

Configuration of the behavior of the JCL ultimately depends upon the logging toolkit being used. The JCL SPI (and hence AXIS) uses Log4J by default if it is available (in the CLASSPATH).

Log4J

Configure Log4J using system properties and/or a properties file:

• log4j.configuration=log4j.properties

Use this system property to specify the name of a Log4J configuration file. If not specified, the default configuration file is log4j.properties. A log4j.properties file is provided in axis.jar, but can be overridden (?verify this still works?) by placing a file of the same name so as to appear before axis.jar in the CLASSPATH.
 

• log4j.rootCategory=priority [, appender]*

Set the default (root) logger priority.
 

• log4j.logger.logger.name=priority

Set the priority for the named logger and all loggers hierarchically lower than, or below, the named logger. logger.name corresponds to the parameter of LogFactory.getLog(logger.name), used to create the logger instance. Priorities are: DEBUG, INFO, WARN, ERROR, or FATAL.

Log4J understands hierarchical names, enabling control by package or high-level qualifiers: log4j.logger.org.apache.axis.encoding=DEBUG will enable debug messages for all classes in both org.apache.axis.encoding and org.apache.axis.encoding.ser. Likewise, setting log4j.logger.org.apache.axis=DEBUG will enable debug message for all AXIS classes, but not for other Jakarta projects.
 

• log4j.appender.appender.Threshold=priority

Log4J appenders correspond to different output devices: console, files, sockets, and others. If appender's threshold is less than or equal to the message priority then the message is written by that appender. This allows different levels of detail to be appear at different log destinations.

For example: one can capture DEBUG (and higher) level information in a logfile, while limiting console output to INFO (and higher).

Compile and Run

• 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

 

cd xml-axis/java
ant compile

cd xml-axis/java
ant functional-tests

Please run ant functional-tests and ant all-tests before checking in new code.

Internationalization

1. 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).

 
2. The resource.properties file contains translation and usage instructions.  Here is an example message:

 

 
 
 
 
 

sample00=My name is {0}, and my title is {1}.
 

1. sample00 is the key that the code will use to access this message.
2. The text after the = is the message text.
3. The {number} syntax defines the location for inserts.

 
3. 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");
 

4. All keys in the properties file should use the syntax <string><2-digit-suffix>.

 
1. 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.

 
2. If a code change requires a change to a message, create a new entry with an incremented 2-digit suffix.

 
3. All new entries should be placed at the bottom of the file to ease translation.

Adding Testcases

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

1. Created a xml-axis/java/test/wsdl/sequence directory.

 
2. Created a SequenceTest.wsdl file defining the webservice.

 
3. Ran the Wsdl2java emitter to create java files:

 

java org.apache.axis.wsdl.Wsdl2java -t -s SequenceTest.wsdl
 

1. 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.
2. 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).
3. 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.

 
4. 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.
 

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

6. 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

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

tcpmon is described in more detail in the AXIS User's Guide.

Running a Single Functional Test

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

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

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

Turning on Debug Output

• Overriding Log4J properties

The log4j.properties file is packaged in axis.jar with reasonable default settings. Subsequent items presume changes to these settings. There are multiple options open to the developer, most of which involve extracting log4j.properties from axis.jar and modifying as appropriate.

• If you are building and executing java programs from a command line or script file, include the JVM option -Dlog4j.configuration=yourConfigFile.
• Set CLASSPATH such that your version of log4j.properties appears prior to axis.jar in the CLASSPATH.
• If you are building and executing your programs using ant (this includes building AXIS and running it's tests), set the environment variable ANT_OPTS to -Dlog4j.configuration=yourConfigFile.
• If you are building AXIS, you can change src/log4j.properties directly. Be sure NOT to commit your change(s).



• Turning on ALL DEBUG Output

• Set the log4j.rootCategory priority to DEBUG.
• Set the priority threshold for an appender to DEBUG (The log4j.properties file in AXIS defines two appenders: CONSOLE and LOGFILE).



• Selective DEBUG Output

• Set the log4j.rootCategory priority to INFO or higher.
• Set the log4j.logger.logger.name priority to DEBUG for the loggers that you are interested in.
• Set the priority threshold for an appender to DEBUG (The log4j.properties file in AXIS defines two appenders: CONSOLE and LOGFILE).
• If you are still seeing more than you want to see, you will need to use other tools to extract the information you are interested in from the log output. Use appropriate key words in log messages and use tools such as grep to search for them in log messages.

Writing Temporary Output

Developers may be tempted to use System.out.println while debugging or analyzing a system. If you choose to do this, you will need to disable the util/TestSrcContent test, which enforces avoidance of System.out.println and System.err.println. It follows that you will need to remove your statements before checking the code back in.

As an alternative, we strongly encourage you to take a few moments and introduce debug statements: log.debug("reasonably terse and meaningful message"). If a debug message is useful for understanding a problem now, it may be useful again in the future to you or a peer.