Troubleshooting: Ant tasks and types fail to load or run due to missing classes

The build and deployment processes fail when Ant tasks and types that depend on external libraries fail to load or run.

Problem

Ant's class loader implementation is based on the standard Java ClassLoader, which uses a delegation model. Each class loader instance is associated with a parent class loader, with the topmost being the bootstrap class loader used by the JVM. When searching for a class, a class loader instance will first delegate the work to the parent class loader before the search is done within the instance itself. Such behaviour poses challenges in setting up the classpath to load Ant tasks and types that require external libraries, as the required classes might not be accessible at the same level of class loader. Since the Build and Deployment tool leverages Ant tasks and types that depend on external libraries, the following class loading strategies are employed to achieve a balance of classpath complexity:

  • For standard Ant tasks and types that depend on external libraries, and the Ant-Contrib tasks and types that are defined in a self-contained external library, the respective external libraries must be copied to the WCBD_installdir/lib directory, which will subsequently be copied into the lib directory of the deployment packages. The paths to these libraries are added to the CLASSPATH environment variable in the setenv script, so that Ant will add them to the bootstrap class loader for use.
  • For third-party Ant tasks or types that require multiple external libraries, such as SvnAnt, they are loaded by the taskdef or typedef Ant task with classpath defined in the common Ant build file. These libraries are omitted from the bootstrap class loader to ensure that all required classes can be located within the same class loader.
  • For the custom Ant tasks and types provided by the Build and Deployment tool that require libraries in the tool as well as WebSphere Application Server libraries, they are loaded by the taskdef Ant task with a classpath defined in the common Ant build file. These libraries are omitted from the bootstrap class loader to ensure that all required classes can be located within the same class loader.

The WebSphere Commerce Build and Deployment tool will fail to load Ant tasks and types if any of the strategies above are violated. Such violation are commonly caused by the following:

  • For standard Ant tasks and types that depend on external libraries, the libraries are not copied to the WCBD_installdir/lib directory, or they do not have the right file permission or ownership for use by the build and deployment processes on UNIX and Linux systems.
  • User copies libraries provided by the WebSphere Commerce Build and Deployment tool, such as wcbd-ant.jar, to the lib directory in the Apache Ant installation directory. This causes the taskdef or typedef task to load the custom Ant task and type classes from the core or bootstrap class loader that does not include other libraries, such as those from WebSphere Application Server, thereby resulting in class loading failures.
  • User sets the path of libraries provided by the Build and Deployment tool, such as wcbd-ant.jar, in the CLASSPATH environment variable, either in the setenv script or externally. This causes the taskdef task to load the custom Ant task and type classes from the bootstrap class loader that does not include other libraries, such as those from WebSphere Application Server, thereby resulting in class loading failures.

The Ant build will fail with one of the following errors:

  • A NoClassDefFoundError.
  • A ClassNotFoundException.
  • A task or type creation failure due to undefined name as reported by the taskdef or typedef task. For example:
    Problem: failed to create task or type svn
    Cause: The name is undefined.
    Action: Check the spelling.
    Action: Check that any custom tasks/types have been declared.
    Action: Check that any <presetdef>/<macrodef> declarations have taken place.
  • A definition loading failure due to missing resource as reported by the taskdef or typedef task. For example:
    [typedef] Could not load definitions from resource org/tigris/subversion/svnant/svnantlib.xml. It could not be found.

Solution

The build and deployment processes will load Ant tasks and types correctly if the following is done:

  • For standard Ant tasks and types that depend on external libraries, copy the libraries to the WCBD_installdir/lib directory and assign the appropriate file permission and ownership to them on UNIX and Linux systems.
  • Do not copy libraries that are provided by the Build and Deployment tool to the lib directory in the Apache Ant installation directory.
  • Do not sets the path of libraries provided by the Build and Deployment tool in the CLASSPATH environment variable.