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. Please Note: Version 1.5 OR HIGHER is required
• 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-1.2.4.jar
G:\\xml-axis\\java\\build\\classes

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

Pluggable-Components

Discovery

org.apache.axis.components.<componentType>.<factoryClassName>

The org.apache.axis.components.bytecode package demonstrates both a factory, and supporting classes for different bytecode tools used by axis. This is representative of a pluggable component that uses external tooling, but isolates them behind a 'thin' wrapper to AXIS, providing only the limited interface required by AXIS. This allows future designers and implementors to gain an explicit understanding of the AXIS's requirements on these tools.

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.axis.components.logger.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).

Configuration Properties

Using this central point of access will allow the global configuration system to be redesigned to better support multiple AXIS engines in a single JVM.

A getGlobalProperty() method has also been added to BasicHandler. Handlers (ancestors of BasicHandler) should use this local method rather than accessing AxisEngine.getGlobalProperty.

Exception Handling

These guidelines are fundamentally independent of programming language. They are based on experience, but proper credit must be given to More Effective C++, by Scott Meyers, for opening the eyes of the innocent(?) many years ago.

Finally, these are guidelines. There will always be exceptions to these guidelines, in which case all that can be asked (as per these guidelines) is that they be logged in the form of comments in the code.

• Primary Rule: Only Catch An Exception If You Know What To Do With It

If code catches an exception, it should know what to do with it at that point in the program. Any exception to this rule must be documented with a GOOD reason. Code reviewers are invited to put on their vulture beaks and peck away...

There are a few corrollaries to this rule.

• Handle Specific Exceptions in Inner Code

Inner code is code deep within the program. Such code should catch specific exceptions, or categories of exceptions (parents in exception hierarchies), if and only if the exception can be resolved and normal flow restored to the code. Note that behaviour of this sort may be significantly different between non-interactive code versus an interactive tool.

• Catch All Exceptions in Outermost Flow of Control

Ultimately, all exceptions must be dealt with at one level or another. For command-line tools, this means the main method or program. For a middleware component, this is the entry point(s) into the component. For AXIS this is AxisServlet or equivalent.

After catching specific exceptions which can be resolved internally, the outermost code must ensure that all internally generated exceptions are caught and handled. While there is generally not much that can be done, at a minimum the code should log the exception. In addition to logging, the AXIS Server wraps all such exceptions in AxisFaults and returns them to the client code.

This may seem contrary to the primary rule, but in fact we are claiming that AXIS does know what to do with this type of exception: exit gracefully.

• Catching and Logging Exceptions

When an Exception is going to cross a component boundry (client/server, or system/business logic), the exception must be caught and logged by the throwing component. It may then be rethrown, or wrapped, as described below.

When in doubt, log the exception.

• Catch and Throw

If an exception is caught and rethrown (unresolved), logging of the exception is at the discretion of the coder and reviewers. If any comments are logged, the exception should also be logged.

When in doubt, log the exception and any related local information that can help to identify the complete context of the exception.

Log the exception as an error (log.error()) if it is known to be an unresolved or unresolvable error, otherwise log it at the informative level (log.info()).

• Catch and Wrap

When exception e is caught and wrapped by a new exception w, log exception e before throwing w.

Log the exception as an error (log.error()) if it is known to be an unresolved or unresolvable error, otherwise log it at the informative level (log.info()).

• Catch and Resolve

When exception e is caught and resolved, logging of the exception is at the discretion of the coder and reviewers. If any comments are logged, the exception should also be logged (log.info()). Issues that must be balanced are performance and problem resolvability.

Note that in many cases, ignoring the exception may be appropriate.

• Respect Component Boundries

There are multiple aspects of this guideline. On one hand, this means that business logic should be isolated from system logic. On the other hand, this means that client's should have limited exposure/visibility to implementation details of a server - particularly when the server is published to outside parties. This implies a well designed server interface.

• Isolate System Logic from Business Logic

Exceptions generated by the AXIS runtime should be handled, where possible, within the AXIS runtime. In the worst case the details of an exception are to be logged by the AXIS runtime, and a generally descriptive Exception raised to the Business Logic.

Exceptions raised in the business logic (this includes the server and AXIS handlers) must be delivered to the client code.

• Protect System Code from User Code

Protect the AXIS runtime from uncontrolled user business logic. For AXIS, this means that dynamically configurable handlers, providers and other user controllable hook-points must be guarded by catch(Exception ...). Exceptions generated by user code and caught by system code should be:
• Logged, and
• Delivered to the client program

• Isolate Visibility into Server from Client

Specific exceptions should be logged at the server side, and more a general exception thrown to the client. This prevents clues as to the nature of the server (such as handlers, providers, etc) from being revealed to client code. The AXIS component boundries that should be respected are:
• Client Code <--> AxisClient
• AxisClient <--> AxisServlet (AxisServer/AxisEngine)
• AxisServer/AxisEngine <--> Web Service

• Throwing Exceptions in Constructors

Before throwing an exception in a constructor, ensure that any resources owned by the object are cleaned up. For objects holding resources, this requires catching all exceptions thrown by methods called within the constructor, cleaning up, and rethrowing the exceptions.

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

 

Adding Source Code Checks

If a convention can be reduced to a regular expression match, it can be enforced at build time by updating java/test/utils/TestSrcContent.java.

All that is necessary is to add a pattern to the static FileNameContentPattern array. Each pattern has three parameters:

1. a pattern that matches filenames that are to be checked,
2. a pattern to be searched for in the chosen files, and
3. a boolean indicating whether the pattern is to be allowed (typically false indicating not allowed).

A reasonable summary of the regular expression notation is provided in the Jakarta ORO javadocs.

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.

Running the JAX-RPC Compatibility Tests

The kit comes as a zip file which you should unzip into a directory of your choosing. The installation instructions are in the JAX-RPC Release Notes document which is stored in the docs directory. If you open the index.html file in the docs directory using a web browser, you'll see a list of all the documents supplied with the kit.

Note that the kit includes the JavaTest test harness which is used for running the compatibility tests.

If any more information is needed about running these tests, please add it here!