[Skip to content]

Chapter 10. Maven 1 Plug-in

Describes the installation and usage of the Jalopy Maven 1 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.

Note

Maven 1 is in maintenance mode, i.e. development is restricted to support and bug fixes. You might be better of with the current release. Please refer to the main Maven site for further information

10.1. Installation

Explains the steps involved in getting the Maven 1 plug-in up and running.

10.1.1. System requirements

The plug-in requires Maven 1.0 - 1.1. See Section 1.1, “System requirements” for the basic requirements to run Jalopy. Please note that it won’t work with later versions. A different plug-in is available for more recent Maven versions (see Chapter 11, Maven 2 Plug-in).

10.1.2. Setup

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 highly 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 and/or settings folders. To decompress the contents of the installer JAR, you can often use the build-in support of your file manager (e.g. Nautilus) or any other software that can handle the ZIP compression format (e.g. 7Zip, WinZip or Stuffit Expander). If you don’t have access to one of the convenience tools, you might resort to the jar command-line application that ships with your Java distribution.

When 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:\Users\John Doo\.jalopy\1.9 and you’re about to install Jalopy 1.9.4, either copy the directory contents or rename it to C:\Users\John Doo\.jalopy\1.9.4.

Remove any jalopy-1.9.4.jar files from the /lib and /plugins directories of your Maven installation, e.g from /home/John Doo/apps/maven-1.0.2/lib/ and /home/John Doo/apps/maven-1.0.2/plugins/.

Copy the files jalopy-1.9.4.jar and jalopy-ant-1.9.4.jar from the temporary directory into the /lib folder of your Maven 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 folder of your Maven installation.

As a last step, copy the file jalopy-maven-1.9.4.jar from the temporary directory into the /plugins folder of your Maven installation.

10.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

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 executable JAR file:

% java -jar <path_to>\jalopy-1.9.4.jar --configure

Or you give the class path directly to the launcher

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

When you’re done configuring the settings, you should export the code convention as described in Section 2.1.1.11, “Export code convention”. The exported settings file is typically used as part of the Jalopy task configuration in the build script.

10.2.1. Properties

The plug-in allows some optional properties to control how formatting is applied.

Table 10.1. Jalopy Maven plug-in properties

PropertyTypeDescriptionSinceRequired
maven.jalopy.backupBoolean Sets whether backup copies of all processed source files should be kept. If omitted, the corresponding code convention setting will be used (see Section 2.2.2.2, “Backup”). 1.5No
maven.jalopy.conventionString 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.10, “Import code convention” 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.5No
maven.jalopy.destdirString Sets the destination directory to create/copy all formatting output into. It can either be given as an absolute path, or relative to the working directory. If the directory does not exist, it will be created. If omitted, all input files will be overridden. 1.5No
maven.jalopy.encodingString Sets the encoding that controls how Jalopy interprets text files containing characters beyond the ASCII character set. Defaults to the platform default encoding. 1.5No
maven.jalopy.failOnErrorBoolean Sets whether a run should be held if errors occurred. Defaults to “true”. 1.5No
maven.jalopy.fileFormatStringSets 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.5No
maven.jalopy. filesetIncludeString Comma- or space-separated list of patterns of source files that should be formatted. Defaults to “**/*.java”. 1.5No
maven.jalopy. filesetExcludeString Comma- or space-separated list of patterns of source files that should be excluded from formatting; no files (except default excludes) are excluded when omitted. The default is to format all source files. 1.5No
maven.jalopy.forceBooleanSets whether the formatting of files should be forced, even if a file is up-to-date. Defaults to “false”. 1.5No
maven.jalopy.forkBooleanSets whether the processing should be performed in a separate VM. Defaults to “false”. 1.5No
maven.jalopy.historyString 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.5No
maven.jalopy. inputEncodingString 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.6No
maven.jalopy.javadocStringIndicates whether Javadoc related messages should be printed. Defaults to “true”. 1.5No
maven.jalopy.logLevelString 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.6.1, “Categories”). 1.5No
maven.jalopy.logString 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.6.2, “Logging”). 1.5No
maven.jalopy. outputEncodingString Sets the character encoding Jalopy uses to write files. Defaults to the platform default encoding. Please note that this setting always overrides encoding. 1.6No
maven.jalopy.profileString Sets the Jalopy profile that should be activated during the formatting run (refer to Section 2.1.1.1, “Main window” for more information about profiles). The currently active profile will be restored after formatting. Please note that the profile must exist! 1.5No
maven.jalopy.repositoryBoolean Indicates whether the type repository should be used for type resolution. When disabled, an alternative implementation with different characteristics is used. You may want to use this option if you commonly format a single file or only a small set of files in order to avoid the maintenance overhead of the type repository. Please be aware that the import expansion feature requires the type repository. Defaults to “true”. 1.6No
maven.jalopy.src filesetIncludeBoolean For “src/java” directory. Comma- or space-separated list of patterns of source files that should be formatted. Defaults to “${maven.jalopy.filesetInclude}”. 1.5No
maven.jalopy.src. filesetExcludeBoolean For “src/java” directory. Comma- or space-separated list of patterns of source files that should be excluded from formatting. Defaults to “{maven.jalopy.filesetExclude}”. 1.5No
maven.jalopy.testBooleanSets 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.5No
maven.jalopy.test. filesetIncludeBoolean For “src/test” directory. Comma- or space-separated list of patterns of source files that should be formatted. Defaults to “${maven.jalopy.filesetInclude}”. 1.5No
maven.jalopy.test. filesetExcludeBoolean For “src/test” directory. Comma- or space-separated list of patterns of source files that should be excluded from formatting. Defaults to “${maven.jalopy.filesetExclude}”. 1.5No
maven.jalopy.threadsIntegerSpecifies the number of processing threads to use. Integer between 1 - 8. Defaults to '1'. 1.5No

10.3. Usage

The Jalopy plug-in provides a standard goal to format your sources. For example, to format all source files from the current project, run:

% maven triemax-jalopy

You’ll notice that all of the code is compiled before any formatting is applied. This is good practice in order to ensure valid input. If you want to bypass the compilation, you can use another goal:

% maven triemax-jalopy:format

10.3.1. Goals

Table 10.2. Jalopy Maven Jelly goals

GoalDescription
triemax-jalopyFormats the source files according to coding convention. The source files will be compiled before formatting takes place.
triemax-jalopy:formatFormats the source files according to coding convention.
triemax-jalopy:taskdefDefines the Jalopy task to Ant and Jelly.