Axis Developer's Guide
Alpha 3 Version
Table of Contents
Introduction
General Guidelines
Development Environment
Logging/Tracing
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"
Logging/Tracing
AXIS logging and tracing is based on the Logging component of the
Jakarta Commons
project, or the Jakarta Commons Logging (JCL) SPI.
The JCL provides a Log interface with thin-wrapper implementations for
other logging tools, including
Log4J,
Avalon LogKit,
and
JDK 1.4.
The interface maps closely to Log4J and LogKit.
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;
For each class definition, declare and initialize a
log
attribute as follows:
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);
While semantics for these methods are ultimately
defined by the implementation of the Log interface,
it is expected that the severity of messages is ordered
as shown in the above list.
In addition to the logging methods, the following are provided:
log.isFatalEnabled();
log.isErrorEnabled();
log.isWarnEnabled();
log.isInfoEnabled();
log.isDebugEnabled();
log.isTraceEnabled();
These are typically used to guard code that
only needs to execute in support of logging,
and that introduces undesirable runtime overhead
in the general case (logging disabled).
Guidelines
Message Priorities
It is important to ensure that log message are
appropriate in content and severity.
The following guidelines are suggested:
- 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...
The Jakarta Commons Logging (JCL) SPI
can be configured to use different logging toolkits.
To configure which logger is used by the JCL, see the
AXIS System Integration Guide.
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
As
Log4J
is the prefered/default logger for AXIS,
a few details are presented herein to get the developer going.
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
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.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>
-
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, 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.
tcpmon
is described in more detail in the
AXIS User's Guide.
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
Turning on Debug Output
This section is oriented to the AXIS default logger: Log4J.
For additional information on Log4J, see the section
Configuring the Logger.
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
Remember that AXIS is targetted for use in a number
of open-source and other web applications,
and so it needs to be a good citizen.
Writing output using System.out.println
or
System.err.println
should be avoided.
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.