Diagnostic Tests with Ant

by Koen Vervloesem
10/12/2005

Suppose you have developed your Java application and distributed it to your users. If all goes well, the application just works on every computer. But if there's a problem, you have to begin troubleshooting. Users will call for all sorts of installation problems, expecting you to fix them. Moreover, the same problems will often come back: the wrong version of Java, a deleted file, too-restrictive file permissions, etc. Most of these problems can be solved by creating a checklist. However, instead of wasting time asking new users the same questions on the checklist over and over, you can create a diagnostic test that goes through the checklist, providing users with the information they need to solve the problem. If users can't solve the problem themselves, they can show you a clear checklist, so you can take a look at what's going wrong without asking a bunch of questions first.

What problems can users expect? First, things can already go wrong during the installation process if the user doesn't follow the installation instructions accurately. Even if the installation succeeds, problems can appear later. Changes in configuration (like the JAVA_HOME environment variable) or changes in the directory structure can indeed break things. In this article, we will develop an Ant script to run diagnostic tests for a Java application. We will look at a list of possible problems and how to deal with them. For our approach to work, Ant has to be installed on the user's machine. This may mean that your installer will have to provide Ant.

System Configuration

The first thing you should know to troubleshoot is the system configuration--the operating system, Java version, classpath, etc. Implementing this is easy, because Ant provides access to all Java system properties. Here's an example (reformatted for the ONJava layout; each <echo> should be on one line):

<?xml version="1.0"?>
<project name="diagnostic" default="all" 
            basedir=".">

  <target name="systemProperties">
    <echo message="Java Runtime Environment 
        version: ${java.version}"/>
    <echo message="Java Runtime Environment 
        vendor: ${java.vendor}"/>
    <echo message="Java Runtime Environment 
        vendor URL: ${java.vendor.url}"/>
    <echo message="Java installation 
        directory: ${java.home}"/>
    <echo message="Java Virtual Machine 
        specification version: 
        ${java.vm.specification.version}"/>
    <echo message="Java Virtual Machine 
        specification vendor: 
        ${java.vm.specification.vendor}"/>
    <echo message="Java Virtual Machine 
        specification name: 
        ${java.vm.specification.name}"/>
    <echo message="Java Virtual Machine 
        implementation version: 
        ${java.vm.version}"/>
    <echo message="Java Virtual Machine 
        implementation vendor: 
        ${java.vm.vendor}"/>
    <echo message="Java Virtual Machine 
        implementation name: ${java.vm.name}"/>
    <echo message="Java Runtime Environment 
        specification version: 
        ${java.specification.version}"/>
    <echo message="Java Runtime Environment 
        specification vendor: 
        ${java.specification.vendor}"/>
    <echo message="Java Runtime Environment 
        specification name: 
        ${java.specification.name}"/>
    <echo message="Java class format version 
        number: ${java.class.version}"/>
    <echo message="Java class path: 
        ${java.class.path}"/>
    <echo message="List of paths to search when 
        loading libraries: ${java.library.path}"/>
    <echo message="Path of extension directory 
        or directories: ${java.ext.dirs}"/>
    <echo message="Default temp file path: 
        ${java.io.tmpdir}"/>
    <echo message="Operating system name: 
        ${os.name}"/>
    <echo message="Operating system 
        architecture: ${os.arch}"/>
    <echo message="Operating system version: 
        ${os.version}"/>
  </target>

  <target name="all" depends="systemProperties"/>

</project>

The example output looks like this (reformatted for this page):

$ ant -f diagnostic.xml
Buildfile: diagnostic.xml

systemProperties:
     [echo] Java Runtime Environment version: 
            1.4.2_05
     [echo] Java Runtime Environment vendor: 
            Apple Computer, Inc.
     [echo] Java Runtime Environment vendor URL: 
            http://apple.com/
     ...
     [echo] Default temp file path: /tmp
     [echo] Operating system name: Mac OS X
     [echo] Operating system architecture: ppc
     [echo] Operating system version: 10.3.9

Now, if something goes wrong, you might be able to see the source of the problem in the system properties: incorrect Java version, class path, etc.

Pages: 1, 2, 3, 4, 5

Next Page