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\\commons-discovery.jar
G:\\xml-axis\\java\\build\\lib\\commons-logging.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.image package demonstrates both a factory, and supporting classes for different image tools used by AXIS. This is representative of a pluggable component that uses external tooling, isolating it behind a 'thin' wrapper to AXIS that provides only a limited interface to meet AXIS minimal requirements. This allows future designers and implementors to gain an explicit understanding of the AXIS's specific 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.

  This properties file can sometimes be overridden by placing a file of the same name so as to appear before axis.jar in the CLASSPATH. However, the precise behaviour depends on the classloader that is in use at the time, so we don't recommend this technique.

  A safe way of overriding the properties file is to replace it in axis.jar. However, this isn't very convenient, especially if you want to tweak the properties during a debug session to filter out unwanted log entries. A more convenient alternative is to use an absolute file path to specify the properties file. This will even ignore web app's and their classloaders. So, for example on Linux, you could specify the system property:

  log4j.configuration=file:/home/fred/log4j.props
  

• log4j.debug A good way of telling where log4j is getting its configuration from is to set this system property and look at the messages on standard output.
   
• 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.

  A combination of settings will enable you to see the log events that you are interested in and omit the others. For example, the combination:

  log4j.logger.org.apache.axis=DEBUG 
  log4j.logger.org.apache.axis.encoding=INFO
  log4j.logger.org.apache.axis.utils=INFO
  log4j.logger.org.apache.axis.message=INFO
  

  cuts down the number of a log entries produced by a single request to a manageable number.
   
• 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.

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

Developer Guidelines

1. Your text string should be added as a property to the resource.properties file (xml-axis/java/src/org/apache/axis/i18n/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.  Entries in a message resource file are of the form <key>=<message>. 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.i18n.Messages.getMessage to obtain the text and add inserts.  Here is an example usage:

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

 
4. We may occasionally want to trim the properties file of old data, but this should only be done on major releases.

Example

        if ( operationName == null )
            throw new AxisFault( "No operation name specified" );

We will add an entry into org/apache/axis/i18n/resource.properties:

       noOperation=No operation name specified.

And change the code to read:

        if ( operationName == null )
            throw new AxisFault(Messages.getMessage("noOperation"));

Interface

public static java.util.ResourceBundle getResourceBundle();

public static String getMessage(String key) throws java.util.MissingResourceException;

public static String getMessage(String key, String var) throws java.util.MissingResourceException;

public static String getMessage(String key, String var1, String var2) throws java.util.MissingResourceException;

public static String getMessage(String key, String[] vars) throws java.util.MissingResourceException;

AXIS programmers can work with the resource bundle directly via a call to Messages.getResourceBundle(), but the getMessage() methods should be used instead for two reasons:

1. It's a shortcut. It is cleaner to call
Messages.getMessage("myMsg00");
than
Messages.getResourceBundle().getString("myMsg00");


2. The getMessage methods enable messages with variables.

The getMessage methods

myMsg00=This is a string.

Messages.getMessage("myMsg00");

If you have a message with variables, use the syntax "{X}" where X is the number of the variable, starting at 0. For example:

myMsg00=My {0} is {1}.

Messages.getMessage("myMsg00","name", "Russell");

You could also call the String array version of getMessage:

Messages.getMessage("myMsg00", new String[] {"name", "Russell"});

The String array version of getMessage is all that is necessary, but the vast majority of messages will have 0, 1 or 2 variables, so the other getMessage methods are provided as a convenience to avoid the complexity of the String array version.

Note that the getMessage methods throw MissingResourceException if the resource cannot be found.  And ParseException if there are more {X} entries than arguments.  These exceptions are RuntimeException's, so the caller doesn't have to explicitly catch them.

The resource bundle properties file is org/apache/axis/i18n/resource.properties.

Extending Message Files

Adding Testcases

See Also: Test and Samples Structure

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.

A good "non-wsdl" test for reference is test/saaj.

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/wsdl/sequence/build.xml file controls the building of this test.  Locate the "compile" target.  Add a clause that runs the Wsdl2java code. I would recommend stealing something from the test/wsdl/roundtrip/build.xml file (it does a LOT of wsdl2java and java2wsdl calls). Here is the one for SequenceTest:

    <!-- Sequence Test -->
    <wsdl2java url="${axis.home}/test/wsdl/sequence/SequenceTest.wsdl"
               output="${axis.home}/build/work"
               deployscope="session"
               skeleton="yes"
               messagecontext="no"
               noimports="no"
               verbose="no"
               testcase="no">
        <mapping namespace="urn:SequenceTest2" package="test.wsdl.sequence"/>
    </wsdl2java>


5. Enable the run target in the new build.xml file. You need to choose from the execute-Component and the (soon to be introduced) execute-Simple-Test target. These control HOW the test is invoked when run as a single component. The execute-Component sets up the tcp-server and http-server prior to running the test, as well as handles deploying and services that may be needed. The execute-Simple-test simply invokes the raw test class file.
   
   
6. Done.  Run ant functional-tests to verify.  Check in your test.