Describes the installation and usage of the Console Plug-in.
The Console application 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 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.9.1, either copy the directory contents or rename it to
"C:\Documents and Settings\.jalopy\John
Doo\1.9.1". Wizard installation can perform this step
automatically.
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.1.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 have to add
"jalopy-1.9.1.jar" as usual to your
class path.
For the Unix Bash shell, this means can be achieved using
% export CLASSPATH=${CLASSPATH}:<JALOPY_HOME>/lib/jalopy-1.9.1.jar
For Windows, use something like
% set CLASSPATH=%CLASSPATH%;<JALOPY_HOME>\lib\jalopy-1.9.1.jar
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 settings dialog you should use the provided wrapper script for
your platform, called jalopy.
(available in the xxx/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 <path_to>\jalopy-1.9.1.jar --configure
Or you give the class path directly to the launcher
% java -cp <path_to>\jalopy-1.9.1.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.
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
% jalopy [-options] filespec...
Or use the Java launcher to execute the Jalopy binary directly
% java -jar jalopy-1.9.1.jar [-options] filespec...
Or use the Java launcher to call the main class
% java -cp jalopy-1.9.1.jar Jalopy [-options] filespec...
Or manually configure the class path and use the Java launcher to invoke the main class
% java Jalopy [-options] filespec...
The command-line interface provides many (optional) 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 lookup. Entries are separated by semi
colons. If you want to have either one of the Optimize imports, Insert Serial Version UID or Ignore runtime exceptions
features working, you need to specify the class path used to compile your
project here.
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. If 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.
If 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.
If 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.
If 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).
If 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.
If 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).
If 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 currently
Jalopy does not support any "UTF-16" encoding.
If 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).
If 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, Pgs, Plastic, Plastic3D, PlasticXP, Substance,
Synthetica, Trendy, Windows (case-insensitive). Only meaningful in combination
with the --configuration option.
If 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.
If omitted, the corresponding code convention setting will be used | 1.0 | ||
--nofail |
Indicates that processing should not stop when an error occurred.
If omitted, processing terminates when an error occurs | 1.0 | ||
--norepository |
Indicates that the type repository should not be used for type lookup. Please
note that this currently means that all dependent features despite the import optimization will be disabled! Only
meaningful if --classpath has been set. You may want to
use this option if you commonly format a single file or only a small portion of
files in order to avoid the maintenance overhead of the type repository.
If 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.
If 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 semi colons, 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. If omitted, only the environment variables defined in the code convention will be used | 1.6 |
--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.
If omitted, the currently active profile will be used if no code convention is specified | 1.2.1 |
--project | <string> | DEPRECATED. Same as --profile. See explanation there | 1.0 | |
-q | --quiet |
Suppresses noncritical messages
If omitted, the message settings of the code convention will be used | 1.0 | |
-r | --recursive |
Recursively formats all files in the specified directories
If 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.
If 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.
If 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.
If 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. 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/j2se/1.4.2/docs/api/java/util/regex/Pattern.html.
For a more precise description of the behavior of regular expression constructs
consult Mastering Regular Expressions [Friedl97].
If no filespec is given and no --filespec option specified, Jalopy starts listening on STDIN.
Example 5.1. Sample command-line usage
% jalopy -r /dev/foo/src/java
Formats all source files found in directory
"/dev/foo/src/java"
and all subdirectories.
% jalopy -d/test/foo-f DOSmyFile.java myFile.html
Formats the two files "myFile.java" and
"myFile.html" and writes the new files into
directory "/test/foo". Uses DOS as the file
format of the new files.
% jalopy -c /quality/foo.xml -r -d /test/foo ^A.*java
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" will be used.
% type f:\test\in.java | jalopy > out.java
Formats the file "f:\test\in.java" read from
STDIN and outputs its formatted contents to the file
"out.java" in the current directory.