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.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.
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.8.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 classpath 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.8.jar" as usual to your classpath.
For the Unix Bash shell, this means can be achieved using
export CLASSPATH=${CLASSPATH}:<JALOPY_HOME>/lib/jalopy-1.8.jar
For Windows, use something like
set CLASSPATH=%CLASSPATH%;<JALOPY_HOME>\lib\jalopy-1.8.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.xxx (available in the /bin folder of the distribution).
jalopy --configure
Jalopy comes as an exectuable JAR file, you therefore can make use of the -jar option of the Java launcher:
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
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.8.jar [-options] filespec...
Or use the Java launcher to call the main class
java -cp jalopy-1.8.jar Jalopy [-options] filespec...
Or manually configure the classpath and use the Java launcher to invoke the main class
java Jalopy [-options] filespec...
Table 5.1. Jalopy Console Plug-in command-line options
| Option | Long Option | Arguments | Description | Since |
|---|---|---|---|---|
| --classpath | <classpath> |
Specifies the classpath 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 specifiy the classpath used to compile your
file(s) here.
The classpath 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 | 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. "d:\dev\quality\otng-jalopy.xml". 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 is 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. | 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, defaults to "AUTO" | 1.0 |
| --force | Sets whether the formatting of files should be forced, even if a file is up-to-date. If omitted, defaults to "false" | 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 is 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 classpath. 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. Defaults to "false" | 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. Defaults to "false" | 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 is 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 refer to Section 2.3, "Environment" for more information about environment variables. | 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 | 1.2.1 |
| --project | <string> | DEPRECATED. Same as --profile. See explanation there | 1.0 | |
| -q | --quiet | Suppresses noncritical messages | 1.0 | |
| -r | --recursive | Recursively formats all files in the specified directories | 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. Defaults to "false". | 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 | 1.4 |
You can specify as many filespecs as you want, where filespec describes either file paths, directories or filter expressions. You can use any valid Perl5 (5.003) regular expression as a filter expression.
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 Java source files found in directory "/dev/foo/src/java" and all subdirectories.
jalopy -d /test/foo -f DOS myFile1.java myFile2.java
Formats the two files "myFile1.java" and "myFile2.java" 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 captial '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.