Describes the installation and usage of the Console plug-in. The Console plug-in provides a powerful command-line interface for Jalopy.
Explains the steps involved to install the Console plug-in.
See Section 1.1, “System requirements” for the basic requirements to run Jalopy.
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.
Decompress the contents of the JAR file into a temporary directory.
Afterwards create the actual installation directory, e.g.
C:\Program Files\Jalopy or
/usr/local/java/jalopy whatever. Create a new
subfolder /lib and copy the file
jalopy-1.9.4.jar from
the temporary directory into the /lib folder.
Copy the /bin folder from the temporary
directory into the installation directory.
To invoke Jalopy, you can find wrapper scripts for the common platforms in the
/bin folder. You may want to add this folder to
your path. If your platform is not covered, you should make use of the
-jar or -cp options of the Java application
launcher (the java command), since this requires no class path
manipulation (see Section 5.3.1, “Synopsis” below).
But if you don’t want to use any of these options, you can add
jalopy-1.9.4.jar to your
class path as usual. For the Unix Bash shell, this means can be achieved using
% export CLASSPATH=${CLASSPATH}:<JALOPY_HOME>/lib/jalopy-1.9.4.jarFor Windows, use something like
% set CLASSPATH=%CLASSPATH%;<JALOPY_HOME>\lib\jalopy-1.9.4.jar
Please refer to your system documentation on how to apply these changes more permanently.
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 preferences dialog you should use the provided wrapper script for
your platform, called jalopy.xxx
(available in the /bin folder of the distribution).
% jalopy --configure
Jalopy comes as an executable JAR file, you therefore can make use of the
-jar option of the Java launcher:
% java -jar jalopy-1.9.4.jar --configure
Or you give the class path directly to the launcher
% java -cp jalopy-1.9.4.jar Jalopy --configure
Of course, you can externally configure the class path yourself by adding all
.jar files as usual and then type
% java Jalopy --configure
on the console. If you should have any of the other plug-ins described in this manual installed, you can of course use their corresponding feature, e.g. invoke the preferences dialog directly from within an IDE.
Presents the available command-line options along with some usage examples.
To start Jalopy from the command-line you may either use the provided launch script for your platform
% jalopy [-options] filespec...Or use the Java launcher to execute the Jalopy binary directly
% java -jar jalopy-1.9.4.jar [-options] filespec...Or use the Java launcher to call the main class
% java -cp jalopy-1.9.4.jar Jalopy [-options] filespec...Or manually configure the class path and use the Java launcher to invoke the main class
% java Jalopy [-options] filespec...
Please note that for certain features, access to the binary .class information is required
as mentioned in
Appendix A, “Type Resolution”.
In order to achieve the same output as with any of the IDE plug-ins, you should always
define the project dependencies via the --classpath option
The command-line interface provides many options to control runtime behavior.
Table 5.1. Jalopy Console plug-in command-line options
| Option | Long Option | Arguments | Description | Since |
|---|---|---|---|---|
| --classpath | <filepath> | Specifies the class path to use for type resolution. Entries are separated by semicolons. Please refer to Appendix A, “Type Resolution” for the list of features which require type resolution. If you don’t use any of these features, it’s not required to set anything here. Otherwise the class 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 of the running VM will be automatically added. As a special convenience, specifying a directory is considered equivalent to specifying a list of all the files in the directory with the extension .jar or .JAR | 1.1 | |
| --configure | Invokes the graphical configuration dialog | 1.0 | ||
| -c | --convention | <filepath> |
Specifies the absolute path to the exported code convention whose settings
should be used for formatting, e.g.
“/work/quality/otng-jalopy.xml”.
Please note that specifying an exported code convention impacts your local
profiles as Jalopy will import the code convention into the corresponding
profile. If no profile with the name stored in the exported code contention
exists, it will be created. Specifying a distinct profile to use via the
-p,--profile option is therefore
useless in this case. When omitted, the settings of the active profile will be used
| 1.0 |
| -d | --dest | <filepath> | Sets the destination directory to create/copy all formatting output into. Expects a valid directory name. If the specified directory does not exist, it will be created. When omitted, all input files will be overridden | 1.0 |
| -e | --encoding | <string> | Specifies the encoding that controls how Jalopy interprets text files containing characters beyond the ASCII character set. Expects a Java supported character encoding name (like “US-ASCII”, “ISO-8859-1” or “UTF-8”). Consult the release documentation for your Java implementation to see what encodings are supported. Please note that currently Jalopy does not support any “UTF-16” encoding. When omitted, the platform default encoding will be used | 1.0 |
| --filespec | <filepath> | Specifies the absolute path to a file that defines the filespecs to use for formatting (see below). The filespec strings must be separated by line delimiters. Empty lines are ignored. Please note that you can still define filespecs directly on the command-line. When omitted, the file specs defined on the command-line will be used | 1.7 | |
| -f | --format | <string> | Sets the file format of the output files. The file format controls what end-of-line character is used. Expects either one of “UNIX”, “DOS”, “MAC”, “DEFAULT” or “AUTO” (case insensitive). When omitted, the corresponding code convention setting will be used | 1.0 |
| --force | Sets whether the formatting of files should be forced, even if a file is up-to-date. When omitted, the corresponding code convention setting will be used | 1.0 | ||
| -h | --help | Displays a short help | 1.0 | |
| --history | <string> | Sets the history policy to use. Either one of “ADLER32”, “CRC32” or “NONE” can be used (case insensitive). When omitted, the corresponding code convention setting will used | 1.0 | |
| --input | <string> | Specifies the encoding that controls how Jalopy interprets input text files containing characters beyond the ASCII character set. Expects a Java supported character encoding name (like “US-ASCII”, “ISO-8859-1” or “UTF-8”). Consult the release documentation for your Java implementation to see what encodings are supported. Please note that Jalopy does not yet support any “UTF-16” encoding. When omitted, the platform default encoding will be used | 1.6 | |
| -l | --loglevel | <string> | Specifies the logging level for message output. Expects either one of “ERROR”, “WARN”, “INFO” or “DEBUG” (case insensitive). When omitted, the corresponding code convention settings will be used | 1.0 |
| --look | <string> |
Defines the Swing Look & Feel that should be used. Expects either the fully
qualified name of a Swing Look & Feel that can be found on the class path. Or
the abbreviation for some well known Look & Feels: Alloy, BlackStar,
GreenDream, Liquid, Metal, Motif, Nimbus, PGS, Plastic, Plastic3d, PlasticXP,
Synthetica, Windows (case-insensitive).
Only meaningful in combination
with the --configure option.
When omitted, the default Look & Feel will be used (varies from platform to
platform, but can be configured via the “swing.properties” preferences
file)
| 1.0 | |
| --nobackup | Indicates that no backup copies should be kept. When omitted, the corresponding code convention setting will be used | 1.0 | ||
| --nofail | Indicates that processing should not stop when an error occurred. When omitted, processing terminates when an error occurs | 1.0 | ||
| --norepository |
Indicates that an alternative implementation with different characteristics should used
for type resolution and the disk-based type repository disabled. Only meaningful
when --classpath is defined.
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 collapsing requires the type repository!
When omitted, the disk based type repository will be used
| 1.6 | ||
| --output | <string> | Specifies the character encoding that Jalopy uses to write text files. Expects a Java supported character encoding name (like “US-ASCII”, “ISO-8859-1” or “UTF-8”). Consult the release documentation for your Java implementation to see what encodings are supported. Please note that currently Jalopy does not support any “UTF-16” encoding. When omitted, the platform default encoding will be used | 1.6 | |
| -o | --override | <filepath> or <string> |
Specifies local environment variable overrides. The value might either be a file
path pointing to a properties file with key/value pairs. Or you may specify the
key/value pair(s) directly using a key=value notation where
the different pairs are separated by semicolons, e.g.
-o "author=John Doo;project=FOZZY"
Please note that when you want to specify several variables, the value string
must be enclosed with quotes! Please refer to Section 2.4, “Environment” for
more information about environment variables.
When omitted, only the environment variables defined in the code convention will
be used
| 1.6 |
| --priority | <integer> | Sets the priority to use for worker threads. Expects an integer between 1-10 (inclusive). Bigger number means higher priority. Defaults to 5 | 1.9.2 | |
| --p | --profile | <string> | Sets the Jalopy profile that should be activated during the formatting run. Expects the name of an existing profile, e.g. “default” for the default profile. The currently active profile will be restored after formatting. When omitted, the currently active profile will be used if no code convention is specified | 1.2.1 |
| --progress | <string> | Displays a progress bar during formatting. Runtime messages will be stored in the file “jalopy.log” in the current working directory | 1.9.2 | |
| -q | --quiet | Suppresses noncritical messages. When omitted, the message settings of the code convention will be used | 1.0 | |
| -r | --recursive | Recursively formats all files in the specified directories. When omitted, only the files in the specified directories will be formatted | 1.0 | |
| --test | <boolean> | Sets whether formatting output should actually be written to disk. If set to “true” no output will be written to disk. When omitted, all output will be written to disk | 1.0 | |
| -t | --thread | <integer> | Specifies the number of processing threads to use. Expects an integer argument between 1-8 (inclusive). When omitted, the corresponding code convention setting will be used | 1.0 |
| --track | <filepath> |
Specifies the absolute path to a file where Jalopy will keep track of those
files that would be actually formatted during a run. The file path strings will
be separated by the platform line delimiter. Implies
--test.
When omitted, no track file will be written
| 1.4 |
Filespecs define the source files and/or directories that should be formatted.
You can specify as many filespecs as you want, where
filespec describes either file paths, directories or
filter expressions. If no filespec is given and no
--filespec
option specified, Jalopy starts listening on STDIN.
You can use any valid regular expression as a filter expression. Jalopy uses Java’s build-in regular expression engine which is roughly equivalent with Perl 5 regular expressions. The syntax is explained here: http://java.sun.com/javase/6/docs/api/java/util/regex/Pattern.html. For a more precise description of the behavior of regular expression constructs consult Mastering Regular Expressions [Friedl97].
Formats all source files found in directory
/dev/foo/src/java and all subdirectories. The settings
from the active profile are used.
Formats the two files File1.java and
File2.java and writes the new files into
directory /test/foo. Uses the settings from the active
profile, but sets DOS as the file format used to write the files.
Formats all Java source files found in the current directory and all subfolders
whose name start with a capital 'A' and writes the new files into
directory /test/foo. The settings of the
code convention /quality/foo.xml are used.
Formats the file C:\Sources\Foo.java read from
STDIN and outputs its formatted contents to the file
Foo.java in the current directory using the active
profile.
Example 5.5. Sample command-line usage
% java -cp /usr/local/jalopy/jalopy-1.9.4.jar Jalopy \ --convention=/usr/local/jalopy/jalopy.xml --norepository \ --filespec=/tmp/3bD0W8.lst --track=/tmp/tXO7tE.lst
Formats all files specified in /tmp/3bD0W8.lst
according to the given code convention, uses classpath type resolution, and writes the
paths of all files that were actually modified to the track file
/tmp/tXO7tE.lst.lst. This is the typical invocation
pattern when using Jalopy in a SCM pre-commit trigger to verify that all files have been
formatted prior to check-in.