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

## Chapter 12. Maven 2.x Plug-in

Describes the installation and usage of the Jalopy Maven 2.x Plug-in.

Maven is a software project management and comprehension tool. Based on the concept of a project object model (POM), Maven can manage a project's build, reporting and documentation from a central piece of information.

The Maven homepage can be reached under http://maven.apache.org/

## 12.1. Installation

Explains the steps involved in getting the Maven 2.x Plug-in up and running.

##### 12.1.1. System requirements

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

Please note that the Plug-in won't work with prior versions. A different Plug-in is available for older Maven releases (see Chapter 11, Maven 1.x Plug-in).

##### 12.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.

First copy the Jalopy Maven Plug-in folder `triemax` from the temporary directory into the Maven 2.x repository directory. This might either be the local repository (e.g. `"C:\Documents And Settings\John Doo\.m2\repository\"`) or the repository directory of your internal repository in case you're using a shared repository for your organization.

Copy the file `jalopy-1.8.jar` below the `triemax/jalopy/1.8/` folder in your Maven repository, and `jalopy-maven-1.8.jar` from the temporary directory into the `triemax/jalopy-maven/1.8/` folder of your Maven 2.x repository.

After all steps have been performed, you should have a folder structure like the following:

    ..
      repository
        [...]
        triemax
          jalopy
            1.8
              jalopy-1.8.jar
              jalopy-1.8.pom
          jalopy-maven
            1.8
              jalopy-maven-1.8.jar
              jalopy-maven-1.8.pom
            maven-metadata-central.xml
            maven-metadata-local.xml
         [...]

## 12.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 install the Console Plug-in and use the matching wrapper script for your platform. The wrapper scripts are called `jalopy.`xxx`` and can be found in the `/bin` folder of the Console installation directory.

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

    jalopy --configure

If you don't want to install the Console Plug-in, you can make use of the -jar option of the Java launcher, as Jalopy comes as an exectuable JAR file:

    java -jar <path_to>\jalopy-1.8.jar --configure

Or you give the classpath directly to the launcher

    java -cp <path_to>\jalopy-1.8.jar Jalopy --configure

Of course, you can externally configure the classpath yourself by adding all `.jar` files as usual and then type

    java Jalopy --configure

## 12.3. Usage

In order to integrate Jalopy into your build process, you need to edit your `pom.xml` under the plugins section:

    <project>
      [...]
      <plugins>
        <plugin>
          <groupId>triemax</groupId>
          <artifactId>jalopy-maven</artifactId>
          <configuration>
            [...]
          </configuration>
          <executions>
            <execution>
              <phase>process-classes</phase>
              <goals>
                <goal>format</goal>
              </goals>
            </execution>
          </executions>
        </plugin>
      </plugins>
    </project>

This would execute Jalopy during the process-classes phase. Please note that you should always apply formatting after the compile phase has finished in order to ensure that the project is clean, but you're otherwise free to choose the phase that best suits your needs. For more information about the Maven build lifecycle, please refer to the "Maven Build Lifecycle Guide". It contains a reference of the available build phases.

##### Configuration

Naturally the Plug-in provides a few parameters to configure its behavior.

Table 12.1. Jalopy Maven Plug-in parameters

Property | 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.7 | No
classpathElements | List | Defines the classpath to use for type lookup. By default, the project classpath (${project.compileClasspathElements}) is used and it should seldom be necessary to override it. | 1.7 | 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.7 | 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.7 | 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.7 | No
environment | Map | Defines temporary environment variables overrides. | 1.7 | No
excludes | List | A list of exclusion filters. Uses the standard Maven pattern syntax. Please note that Jalopy ignores all files it cannot format by default, so exclusions are only necessary if you want to omit formatting for certain files, like e.g. test data files etc. | 1.7 | No
failOnError | Boolean | Sets whether a run should be held if errors occurred. Defaults to "true". | 1.7 | No
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.7 | No
force | Boolean | Sets whether the formatting of files should be forced, even if a file is up-to-date. Defaults to "false". | 1.7 | No
fork | Boolean | Sets whether the processing should be performed in a separate VM. Defaults to "false". | 1.7 | 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.7 | No
includes | List | A list of inclusion filters for the compiler. Uses the standard Maven pattern syntax. Please note that Jalopy ignores all files it cannot format by default, so inclusions are only necessary if you want to omit formatting for certain files, like e.g. test data files etc. | 1.7 | No
inputEncoding | String | Sets the encoding that controls how Jalopy interprets text files containing characters beyond the ASCII character set. Defaults to the platform default encoding. Please note that this setting always overrides encoding. | 1.7 | No
javadoc | String | Indicates whether Javadoc related messages should be printed. Defaults to "true". | 1.7 | 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.7 | No
logFile | 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 hierarchical HTML report. If omitted, the current code convention setting will be used (see Section 2.4.2, "Logging"). | 1.7 | 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.7 | 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.7 | No
`repository` | Boolean | Indicates whether the disk-based type repository should be used for type lookup. When disabled, this currently means that all dependent features despite the import optimization will be disabled! You may want to use this option if you commonly format a single file or only a small sets of files in order to avoid the maintenance overhead of the type repository. Defaults to "true". | 1.7 | No
sources | List | The source directories containing the sources to be formatted. When omitted, uses the directories defined for the compiler (${project.compileSourceRoots}) instead. | 1.7 | 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.7 | No
threads | Integer | Specifies the number of processing threads to use. Integer between `1` - `8`. Defaults to "1". | 1.7 | No

To configure the Plug-in, you specify elements named after the available parameters where the contents of an element is the value to be assigned to the parameter.

    <plugin>
      <groupId>triemax</groupId>
      <artifactId>jalopy-maven</artifactId>
      <configuration>
        <threads>4</threads>
        <profile>test</profile>
      </configuration>
      [...]
    </plugin>

For parameters of type List you would use multiple element tags to map the different values to the list.

    <plugin>
      <groupId>triemax</groupId>
      <artifactId>jalopy-maven</artifactId>
      <configuration>
        <includes>
          <include>com/foo/siri/**</include>
          <include>com/foo/lana/**</include>
        </includes>
        <excludes>
          <exclude>**/*.sqlj</exclude>
          <exclude>**/*Test/**</exclude>
        </excludes>
      </configuration>
      [...]
    </plugin>

Configuring Maps works similar: elements are named after the keys and the element contents is the value to be assigned to the key.

    <plugin>
      <groupId>triemax</groupId>
      <artifactId>jalopy-maven</artifactId>
      <configuration>
        <environment>
          <lead>John Doo</lead>
          <office>Alta Nova</office>
        </environment>
      </configuration>
      [...]
    </plugin>

For a complete example, please refer to Section 12.4, "Example" below.

## 12.4. Example

Below you find a complete POM that performs formatting after each compile run finished successfully, disables logging of Javadoc related messages, only displays messages with warning severity or higher, activates the profile "test" during formatting and imports a code convention from a shared server. Formatting is applied to all Java source files of the project that are not located below the "testdata" folder.

Example 12.1. Maven POM

    <project>
      <modelVersion>4.0.0</modelVersion>
      <groupId>testing</groupId>
      <artifactId>test</artifactId>
      <packaging>jar</packaging>
      <version>1.0-SNAPSHOT</version>
      <name>Maven Quick Start Archetype</name>
      <url>http://maven.apache.org</url>
      <build>
      <plugins>
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-compiler-plugin</artifactId>
          <configuration>
            <source>1.5</source>
            <target>1.5</target>
          </configuration>
        </plugin>
        <plugin>
          <groupId>triemax</groupId>
          <artifactId>jalopy-maven</artifactId>
          <configuration>
            <javadoc>false</javadoc>
            <logLevel>warn</logLevel>
            <profile>test</profile>
            <convention>http://tools/jalopy/config/foo.xml</convention>
            <includes>
              <include>**/*.java</include>
            </includes>
            <excludes>
              <exclude>**/testdata/**</exclude>
            </excludes>
            <environment>
            </environment>
          </configuration>
          <executions>
            <execution>
              <phase>process-classes</phase>
              <goals>
                <goal>format</goal>
              </goals>
            </execution>
          </executions>
        </plugin>
      </plugins>
      </build>
      <dependencies>
        <dependency>
          <groupId>junit</groupId>
          <artifactId>junit</artifactId>
          <version>3.8.1</version>
          <scope>test</scope>
        </dependency>
      </dependencies>
    </project>