Chapter 1. Working with the Axiom source code

Table of Contents

Importing the Axiom source code into Eclipse
Testing
Unit test organization
Testing Axiom with different StAX implementations

Importing the Axiom source code into Eclipse

Use the following steps to import the Axiom source code into Eclipse Neon (4.6.0):

  1. Install AJDT using the following update site:

    http://download.eclipse.org/tools/ajdt/46/dev/update

    Only the "AspectJ Development Tools" feature is required.

  2. Install Workspace Mechanic using the following update site:

    https://alfsch.github.io/eclipse-updates/workspacemechanic

  3. Import the Axiom sources as "Existing Maven Projects" into a new Eclipse workspace. M2Eclipse will propose to install additional Maven plugin connectors; make sure that you install them all.

  4. Configure Workspace Mechanic using the files under etc/workspacemechanic and accept the proposed preference changes.

Testing

Unit test organization

Historically, all unit tests were placed in the axiom-tests project. One specific problem with this is that since all tests are in a common Maven module which depends on both axiom-impl and axiom-dom, it is not rare to see DOOM tests that accidentally use the LLOM implementation (which is the default). The project description in axiom-tests/pom.xml indicates that it was the intention to split the axiom-tests project into several parts and make them part of axiom-api, axiom-impl and axiom-dom. This reorganization is not complete yet[1]. For new test cases (or when refactoring existing tests), the following guidelines should be applied:

  1. Tests that validate the code in axiom-api and that do not require an Axiom implementation to execute should be placed in axiom-api. This primarily applies to tests that validate utility classes in axiom-api.

  2. The code of unit tests that apply to all Axiom implementations and that check conformance to the specifications of the Axiom API should be added to axiom-api and executed in axiom-impl and axiom-dom. Currently, the recommended way is to create a base class in axiom-api (with suffix TestBase) and to create subclasses in axiom-impl and axiom-dom. This makes sure that the DOOM tests never accidentally use LLOM (because axiom-impl is not a dependency of axiom-dom).

  3. Tests that check integration with other libraries should be placed in axiom-integration. Note that this is the only module that requires Java 1.5 (so that e.g. integration with JAXB2 can be tested).

  4. Tests related to code in axiom-api and requiring an Axiom implementation to execute, but that don't fall into category 2 should stay in axiom-tests.

Testing Axiom with different StAX implementations

The following StAX implementations are available to test compatibility with Axiom:

Woodstox

This is the StAX implementation that Axiom uses by default.

Sun Java Streaming XML Parser (SJSXP)

This implementation is available as Maven artifact com.sun.xml.stream:sjsxp:1.0.1.

StAX Reference Implementation

The reference implementation was written by BEA and is available as Maven artifact stax:stax:1.2.0. The homepage is http://stax.codehaus.org/Home. Note that the JAR doesn't contain the necessary files to enable service discovery. Geronimo's implementation of the StAX API library will not be able to locate the reference implementation unless the following system properties are set:

javax.xml.stream.XMLInputFactory=com.bea.xml.stream.MXParserFactory
javax.xml.stream.XMLOutputFactory=com.bea.xml.stream.XMLOutputFactoryBase
XL XP-J

XL XML Processor for Java is IBM's implementation of StAX 1.0 and is part of IBM's JRE/JDK v6. Note that due to an agreement between IBM and Sun, IBM's Java implementation for the Windows platform is not available as a separate download, but only bundled with another IBM product, e.g. WebSphere Application Server for Developers.

On the other hand, the JDK for Linux can be downloaded as a separate package from the developerWorks site. There are versions for 32-bit x86 (xSeries) and 64-bit AMD. They are available as RPMs and tarballs. To install the JDK properly on a Debian based system (including Ubuntu), follow the instructions given in the section called “Installing IBM's JDK on Debian Linux”.



[1] See AXIOM-311.