To edit an existing profile, select the profile in the list and press the Edit... button.

If the selected profile is not the currently active one, the selected profile will be automatically activated. If the settings of the priorly activated profile have been altered, you will be asked whether you want to have your changes persisted before switching.

Figure 2.2. Save Profile Changes

Press the Save button, if your settings should be saved. Otherwise press Don't save to ignore any chances that were made to the profile.

The configuration window finally appears along with the preview window, and here you can alter all available options to configure formatting output. Any changes you make are directly reflected in the preview window.

The configuration window is explained in detail in the section called "Configuration window" below.

To add a new profile click the Add... button. A dialog will appear that lets you create the new profile.

Figure 2.3. Add new Profile Dialog

You need to enter the profile name, might add an optional informative description and if a profile is currently selected in the profiles view, you can choose whether you want to create a nested profile by selecting the parent profile. A nested profile will automatically adapt any changes made to its parent profile(s).

Name

The profile name needs to be unique and will be used as the name of the disk folder where all profile information will be stored. Therefore, you should avoid characters that your platform does not allow to be used in file paths.

As as convenience, when invoked from within one of the supported IDE's, the dialog provides a combo box with the names of all projects currently available in the IDE that have no corresponding Jalopy profile.

Figure 2.4. Add new Profile from within IDE Plug-in

Description

The optional description must be no longer than 256 characters and can be freely chosen. It will be displayed in a tool tip when the mouse is moved over an entry.

Name and description are available for inclusion in templates. See Section 2.3.3, "Local variables" for more information.

Parent Profile

In order to provide the ability to easily manage profiles that largely share the same settings, you can create nested profiles. A nested profile will automatically adapt any changes made to its parent profile(s).

The typcial example would be a number of different projects that should receive the same formatting style, but require different headers. In order to setup such a scenario, you would create a master profile where you configure all shared settings, and afterwards create different nested profiles for each project where you define the individual headers. Later on, if you want to apply any changes to the formatting style of all projects, you would only alter the master profile and the changes will be propagated to the nested profiles automatically.

In order to create a nested profile, simply choose the parent profile here. If you choose "None", the new profile will be created as a root profile. Please note that this option is only available when a profile is currently selected in the list view.

When you add a new profile, the settings of the currently selected profile will be used to create the new profile. If you create a nested profile, the selected profile will be the parent profile.

This feature is only available with Jalopy 1.7 or later.

For every profile you define, a new subdirectory is created below the main settings directory where all related files will be stored.

To remove an existing profile, select an entry or multiple entries in the list and press the Delete button. The profile folders will be removed on disk and the selected entries disappear. A profile may only be removed if it is not active. The default profile cannot be removed.

Please note that if a selected profile contains any nested profiles, removing the profile will cause all nested profiles to be removed as well!

To activate an existing profile, select an entry in the list and press the Activate button. The stored settings will become active and the preferences dialog updated accordingly.

Depending on the type and size of your projects and the provisions of your IDE, it might be necessary to create several project modules in order to manage your codebase efficiently. In such a case all related modules should still receive the same code style.

To achieve and manage such a uniform style easily, you can map modules to one (logical) Jalopy profile that defines the code style. Make sure that the Auto-switch feature (see below) is enabled and Jalopy will automatically use the correct settings for each module.

Say you have a project "foo" which consists of three modules.

Figure 2.5. Sample Project With 3 Modules

To map these modules to one Jalopy profile, choose the target profile in the list and press the Aliases... button. A dialog will be displayed that shows all defined aliases for the profile and lets you alter the alias definitions.

Figure 2.6. Profile Aliases Dialog

Press the Add... button to add a new alias for the profile.

Figure 2.7. Add new Profile Alias

You can either add the names of all modules as new aliases or when the modules share a common prefix - like in our example - use a wildcard alias to point to all modules in just one step. Simply put the * wildcard after the prefix and press the Add button.

The alias is then displayed on the list, but has not yet been created. You need to explicitly press the Save button to have your changes applied and any new aliases created or existing aliases removed!

Figure 2.8. Profile Aliases

Press the Save button to save your changes or Cancel if you you don't want to save your changes at this point.

Please note that the alias information of a profile is displayed as part of the tooltip (in square brackets). Move the mouse over a list entry, and the tooltip will appear shortly.

Since 1.2

Use the Export... button to save your settings as a new code convention.

Just select the profiles that should be exported in the list, and press the Export... button to choose a file to export to. You may select multiple profiles that should be exported into just one file.

Please note that if a nested profile is selected, by default all parent and child profiles will be exported as well. If you really only want to export the profiles that have been selected in the list, hold down the Ctrl key when pressing the Export... button.

In order to be able to share settings across different systems and users, file paths should be stored relative to make the code convention portable. Jalopy therefore exports all file paths below its settings directory as relative file paths. History, backup and message log directories are by default set to a paths below the Jalopy settings directory and are therefore correctly handled by the export. If you should have specified custom file paths here, you should make sure that these paths are checked and adjusted when necessary, after a code convention has been imported!

Please note that exporting only covers the actual code convention settings. All other profile data (history, backup, logs, reports) is ignored. If you really need to share all profiles data, just copy the whole settings directory or selected profile folders over.

Use the Import... button to import an already-saved code convention. Since version 1.6, Jalopy also supports importing of Checkstyle configurations (version 3.5 or later).

Jalopy is able to import code conventions from both local and distributed locations. Just specify a valid Internet address (either starting with "http://", "https://" or "www.") for the latter.

Since Jalopy 1.7, exported code conventions store the names of their profile. During import it is therefore possible to recreate the profile structure. When importing a single profile and the original profile does not already exist, you will be asked whether it should be created and the exported settings imported into this profile. Otherwise, the settings will be imported into the currently active profile. Checkstyle configurations will always be imported into the currently active profile. Importing a file that contains several code conventions, will always recreate the original profiles if they should not already exist.

Versions prior to 1.0b8 stored the backup directory always as an absolute file. Therefore after importing a very old code convention, you should check whether this directory points to your preferred backup directory. This advice holds true even for later versions in case you've changed any of the default directories (backup, history, message log).

Importing Checkstyle configurations

Importing Checkstyle configurations only means a best effort. There is no guarantee that the resulting Jalopy code convention exactly matches your style preferences because some Checkstyle modules might be ambiguous or missing at all.

E.g. take the following "ParenPad" module configuration:

<module name="ParenPad">
    <property name="tokens" value="METHOD_CALL"/>
    <property name="option" value="nospace"/>
</module>

It only defines a white space check for method call parentheses, but does not express the preference for other parentheses. It could be "space" or "nospace". In such a case, Jalopy will assume the default value Checkstyle uses when no token is defined ("nospace" in the example).

Another common case is the <whitespaceAfter> module. Without any tokens defined, it will check for white space after three tokens (comma, semi, type cast parenthesis). But what if you limit the check to only two tokens (comma, semi)? Does it mean that no white space should appear after the right parenthesis of type casts? Or should it be allowed? Checkstyle accepts both, but Jalopy will assume that you don't want white space after the token in such a case.

The same problem appears when a Checkstyle module is not contained in your configuration. Jalopy can't interfere any preferences in a such case and assumes the default settings of an empty module config.

In general importing works better the more Checkstyle modules are defined.

It is recommended that you test the resulting Jalopy code convention against the Checkstyle configuration after importing. Just format some source files into a temporary directory and run Checkstyle to check for any style violations. This way you can be sure that the import covered all your preferences.

To import a Checkstyle configuration you need to press the Import... button and enter or select the configuration file that should be imported. The file dialog provides a file filter for Checkstyle configurations, but because all configuration files use the .xml extension, it actually doesn't matter what file filter is selected.

Figure 2.9. Choose Checkstyle Configuration

After the import has finished, a confirmation dialog appears that lets you display a report of the imported modules.

Figure 2.10. Import Checkstyle Configuration Confirmation