[Skip to content]
TRIEMAX Software
You are here: Home > Products > Jalopy >

## Chapter 4. Ant task

Describes the installation and usage of the Jalopy Ant Plug-in task.

Apache Ant is a Java-based build tool. In theory, it is kind of like Make, but without Make's wrinkles. Instead of a model where it is extended with shell-based commands, Ant is extended using Java classes. Instead of writing shell commands, the configuration files are XML-based, calling out a target tree where various tasks get executed. Each task is run by an object that implements a particular Task interface.

The Ant homepage can be reached under http://ant.apache.org/

## 4.1. Installation

Explains the steps involved in getting the Ant task up and running.

##### 4.1.1. System requirements

The Plug-in requires Ant 1.5 or later. See Section 1.1, "System requirements" for the basic requirements to run Jalopy.

##### 4.1.2. Installation

The Plug-in comes as an executable Jar Archive (Jar) that contains a graphical setup wizard to let you easily install the software. Wizard installation is recommended and explained in detail in Section 1.3, "Wizard Installation".

If you would rather install the Plug-in manually, you have to decompress and copy the appropriate files into the different application folders. To decompress the contents of the installer Jar, you can either use the Jar tool that ships with your Java distribution or any other software that can handle the ZIP compression format (e.g. 7Zip or WinZip).

If you're upgrading from a prior version and want to keep your settings, first copy or rename the current Jalopy settings directory to match the version number of the new release. For instance, if your current settings directory is `"C:\Documents and Settings\John Doo\.jalopy\1.0.4"` and you're about to install Jalopy 1.8, either copy the directory contents or rename it to `"C:\Documents and Settings\.jalopy\John Doo\1.8"`. Wizard installation can perform this step automatically.

Remove any `jalopy-1.8.jar` files from the `/lib` directory of your Ant installation.

Copy the files `jalopy-1.8.jar` and `jalopy-ant-1.8.jar` from the temporary directory into the `/lib` directory of your Ant installation.

If you don't have the Console Plug-in installed and want to be able to configure Jalopy from the command-line, copy the contents of the `/bin` folder from the temporary directory to the `/bin` directory of your Ant installation.

Before you can use the Jalopy Ant task in your build scripts, you have to add it to your system. Maybe the simplest way is to utilize the <taskdef> element in your build script as follows:

    <taskdef name="jalopy" classname="com.triemax.JalopyTask" />

## 4.2. Configuration

Although Jalopy ships with sensible default settings (mimicking the Sun Java coding convention), you most likely want to configure the formatter to match your needs (adding copyright headers, tune Javadoc handling and the like). For such, Jalopy comes with a graphical configuration tool that lets you interactively customize the settings. See Chapter 2, Configuration for an in-depth discussion of the available options.

To display the configuration tool, you should use the matching wrapper script for your platform. The wrapper scripts are called `jalopy.`xxx``.

Invoke the script with the `--configure` option.

    jalopy --configure

Or you can execute the Jar with

    java -jar jalopy-1.8.jar --configure

Of course, you can setup the classpath yourself by adding the `jalopy-1.8.jar` file as usual and then type

    java Jalopy --configure

## 4.3. Usage

The Jalopy task can take a few parameters to control the runtime behavior of Jalopy. If omitted, your current code convention settings will be used.

Nested <fileset> elements can and should be used to specify the source files and/or directories. You can also set user enironment variables for a run by using nested <variable> elements (See example below).

##### 4.3.1. Parameters

The valid parameters are listed in the table below.

Table 4.1. Jalopy Ant task parameters

Attribute | Type | Description | Since | Required
--- | --- | --- | --- | ---
backup | Boolean | Sets whether backup copies of all processed Java source files should be kept. If omitted, the corresponding code convention setting will be used (see Section 2.2.2.2, "Backup"). | 1.0 | No
classpathref | String | The classpath to setup the type repository with, given as a reference to a path defined elsewhere. If you want the import optimization or Insert Serial Version UID features to work, you have to specify the classpath reference you use to compile your sources here. The referenced path must contain all types that are needed by your project. Specifying the Java runtime classes is optional; if they are omitted, the runtime classes used by Ant will be automatically added. | 1.0 | No
convention | String | Sets the location to the code convention file to use - given either relative to the project's base directory or as an absolute local path or internet address (refer to Section 2.1.1.7, "Importing" for information how to export your settings). If omitted, the current settings are used, if available. Otherwise the Jalopy build-in defaults will be used. | 1.0 | No
destdir | String | Sets the destination directory to create/copy all formatting output into. If the given directory does not exist, it will be created. If omitted, all input files will simply be overridden. | 1.0 | No
encoding | String | Sets the encoding that controls how Jalopy interprets text files containing characters beyond the ASCII character set. Defaults to the platform default encoding. | 1.0 | No
failonerror | Boolean | Sets whether a run should be held if errors occurred. Defaults to "true". | 1.0 | No
file | String | Specifies a single source file to format. | 1.0 | Yes, if no fileset is specified
fileformat | String | Sets the file format of the output files. The file format controls what end of line character is used. Either one of "UNIX", "DOS", "DEFAULT" or "AUTO" can be used (case insensitive). Defaults to "AUTO". | 1.0 | No
force | Boolean | Sets whether the formatting of files should be forced, even if a file is up-to-date. Defaults to "false". | 1.0 | No
fork | Boolean | Sets whether the processing should be performed in a separate VM. Defaults to "false". | 1.0 | No
history | String | Sets the history policy to use. Either one of "ADLER32", "CRC32" or "NONE" can be used (case insensitive). If omitted, the corresponding code convention setting will used (see Section 2.2.2.1, "History"). | 1.0.3 | No
historyMethod | String | DEPRECATED. Same as history, see explanation there. | 1.0 | No
inputEncoding | String | Sets the character encoding that controls how Jalopy interprets input text files containing characters beyond the ASCII character set. Defaults to the platform default encoding. Please note that this setting always overrides encoding. | 1.6 | No
javadoc | String | Indicates whether Javadoc related messages should be printed. Defaults to "true". | 1.0 | No
loglevel | String | Specifies the logging level for message output. Either one of "ERROR", "WARN", "INFO" or "DEBUG" can be used (case insensitive). If omitted, the current code convention settings will be used (see Section 2.4.1, "Categories"). | 1.0 | No
log | String | Specifies the log file to use for logging output. The format of the logging output is determined by the extension of the given file. Valid extensions are `.log` for a custom plain text format, `.xml` for a plain XML format and `.html` for an hierarchial HTML report. If omitted, the current code convention setting will be used (see Section 2.4.2, "Logging"). | 1.0.3 | No
outputEncoding | String | Sets the character encoding Jalopy uses to write files. Defaults to the platform default encoding. Please note that this setting always overrides encoding. | 1.6 | No
profile | String | Sets the Jalopy profile that should be activated during the formatting run. (refer to the section called "Main window" for more information about profiles) The currently active profile will be restored after formatting. Please note that the profile must exist! | 1.5 | No
project | String | DEPRECATED. Same as profile, see explanation there. | 1.1 | No
repository | Boolean | Indicates whether the type repository should be used for type lookup. When disabled, this currently means that all dependent features despite the import optimization will be disabled! Only meaningful if classpathref has been set. You may want to use this option if you commonly format a single file or only a sets of files in order to avoid the maintenance overhead of the type repository. Defaults to "true". | 1.6 | No
style | String | DEPRECATED. Same as convention, see explanation there. | 1.0 | No
test | Boolean | Sets whether formatting output should actually be written to disk. If set to "true" no output will be written to disk. The default is "false". | 1.0 | No
threads | Integer | Specifies the number of processing threads to use. Integer between `1` - `8`. If omitted, the current code convention setting will be used. | 1.0 | No

##### 4.3.2. Parameters specified as nested elements

variable

Used to specify a user environment variable that shall be available during a run. If a variable with the given name already exists, its value will be overridden during the run and restored afterwards.

Table 4.2. Nested variable parameter

Attribute | Type | Description | Required
--- | --- | --- | ---
name | String | Specifies the name of the variable. | Yes
value | String | Specifies the value that should be assigned to the variable. | Yes

Since 1.0

#### 4.4. Example

The following example demonstrates how you can make use of the Jalopy Ant task.

Note that the "format" target depends on the "compile" target. This way we can be sure that the given classpathref does cover all types used in the sources.

Example 4.1. Example Ant build file

    <?xml version="1.0" ?>
    <project name="myProject" default="format" basedir="." >

      <property name="dir.compile" value="${basedir}/tmp~/build/classes" />
      <property name="dir.lib" value="${basedir}/lib" />
      <property name="dir.src.java" value="${basedir}/src/java" />

      <!-- ==================================================================== -->
      <!-- Defines the project classpath -->
      <!-- ==================================================================== -->
      <path id="project.classpath" >

        <!-- our compilation directory -->
        <pathelement location="${dir.compile}" />

        <!-- needed 3rd party libraries -->
        <fileset dir="${dir.lib}" >
          <include name="**/*.jar" />
        </fileset>
      </path>

      <!-- ==================================================================== -->
      <!-- Defines the Jalopy task -->
      <!-- ==================================================================== -->
      <taskdef name="jalopy" classname="com.triemax.JalopyTask" />

      <!-- ==================================================================== -->
      <!-- Compiles the project sources -->
      <!-- ==================================================================== -->
      <target name="compile">
        <javac destdir="${dir.compile}" fork="true">
          <classpath refid="project.classpath" />
          <src path="${dir.src.java}" />
        </javac>
      </target>

      <!-- ==================================================================== -->
      <!-- Formats the project source -->
      <!-- ==================================================================== -->
      <target name="format" depends="compile">

        <!--
          Invokes Jalopy as follows:

          - load the code convention from the given url
          - the import optimization feature will work (if enabled in the code
            convention), because a classpath reference is given
          - all formatted files will have unix file format (\n)
          - the processing will be performed in a separate VM
          - override the convention to use alder32 checksums of files as history
            policy
          - override the convention to use loglevel 'info'
          - the user environment variable 'author' is set and the value
            'John Doo' assigned

          Since Jalopy 1.3 an include pattern is no longer necessary if you want
          to format all supported source files of a directory structure
          -->
        <jalopy
            convention="http://www.foo.com/cisco-omg.xml"
            classpathref="project.classpath"
            fileformat="unix"
            fork="true"
            history="adler32"
            loglevel="info">
          <variable name="author" value="John Doo" />
          <fileset dir="${dir.src.java}">
            <include name="**/*.java" />
            <include name="**/*.sqlj" />
          </fileset>
        </jalopy>
      </target>
    </project>