# Getting started
The jSparrow Maven plugin (JMP) is a continuous integration tool to apply automatic refactorings. It supplies similar rules as the jSparrow Eclipse plugin, but works without user input.
- Maven 2.2.1+ (3.5.0+ for Java 11)
- Java 8 or 11
- Linux or Windows operating system
Maven projects themselves may have their Java source version set to an older version than 1.8 or 11 - this is not a problem. However, in this case, all rules requiring a newer source level will be ignored.
# Using the jSparrow Plugin Repository
In order to access jSparrow from the jSparrow plugin repository, you need to add it to Maven's
settings.xml or to the
pom.xml of the project you are using it. Both configuration options are listed below.
# Configuration via pom.xml
pluginRepository configuration via
<project> ... <pluginRepositories> <pluginRepository> <id>jsparrow-plugin-repository</id> <name>jSparrow Plugin Repository</name> <url>https://download.jsparrow.eu/maven2/</url> </pluginRepository> </pluginRepositories> ... </project>
# Configuration via settings.xml
Maven has two locations for the
- Global Maven settings:
- User Maven settings:
If both exist, the contents are getting merged, with the user settings being dominant (have a look at the Maven Settings Reference (opens new window) for more information.).
In contrast to the
pom.xml configuration, the configuration in
settings.xml needs additional
profile configuration, as seen below:
<settings> ... <profiles> ... <profile> <id>default</id> <pluginRepositories> <pluginRepository> <id>jsparrow-plugin-repository</id> <name>jSparrow Plugin Repository</name> <url>https://download.jsparrow.eu/maven2/</url> </pluginRepository> </pluginRepositories> </profile> </profiles> ... <activeProfiles> ... <activeProfile>default</activeProfile> ... </activeProfiles> ... </settings>
This section describes how to set up a project to use the jSparrow Maven plugin and how to use it.
# Feature Overview
- Fully automatic execution of jSparrow rules for a Maven project.
- Refactorings can be applied using the command line.
- For an overview over the supplied rules, use the
list-rulesgoal (see further below).
- Easy installation, no additional downloads required.
- Configuration using command line options, profiles or configuration files possible.
# Project Setup
To use the jsparrow-maven-plugin on a project, add the following code snippet to the project's
<build> <plugins> <plugin> <groupId>eu.jsparrow</groupId> <artifactId>jsparrow-maven-plugin</artifactId> <version>3.8.0</version> </plugin> </plugins> </build>
# Plugin Configuration
To configure which rules should be applied, use the configuration file (
jsparrow.yml). Place this file in your project's root directory.
The child projects will inherit the parent's configuration, unless another
jsparrow.yml is placed in their base directory. In this case, the parent's configuration is ignored completely. If the configuration file is not present, has errors or isn't inherited from a parent, an exception will be thrown and the JMP will terminate. If the
-DconfigFile option is specified, it will override all other configuration files.
jsparrow.yml file consists of three optional sections.
The first section contains the profiles definition.
To define a profile you should specify its name, the list of rules included in the profile and their configuration if any applies (e.g., configuration for LoggerRule and RenamingRule).
Any number of profiles can be defined. The profile to be used for refactoring should be designated with the
The second section contains a list of rules which will be used for refactoring if no profile is designated as
Similarly as in profile definition, the list of rules can be followed by the rule configuration if any is required.
The third section under
excludes node consists of the modules, packages and classes that shall not be refactored by JMP. If no
excludes are defined, JMP will refactor the entire main resources of the project.
This section will only be recognized in the
yml file in the root project, i.e., in any
yml file placed in child projects the
excludes section will be discarded.
The following is an example of a
jsparrow.yml configuration file:
# Specify one of the profiles declared below as the selected profile. # If the selectedProfile is not specified the rules in the “rules:” section # will be applied selectedProfile: profile1 # define profiles here profiles: - name: profile1 rules: - TryWithResource - MultiCatch - FieldRenaming - StandardLogger # The configuration for LoggerRule and RenamingRule can be placed together # with the profile in which the rules are included. If the configuration # within the profile is missing, then the default values are used. The # following is a configuration sample with default values loggerRule: systemOutReplaceOption: INFO systemErrReplaceOption: ERROR printStacktraceReplaceOption: ERROR systemOutPrintExceptionReplaceOption: INFO systemErrPrintExceptionReplaceOption: ERROR addMissingLoggingStatement: ERROR attachExceptionObject: true renamingRule: fieldTypes: - private - protected - package-protected - public underscoreReplacementOption: Upper dollarReplacementOption: Leave # The rules in this section will be executed, if no profile has been # specified as selectedProfile or via maven. To deactivate rules, they can be # commented with the #-sign. The configuration for RenamingRule and LoggerRule # in this section can be done the same way as in the configuration # in profiles, under the rules section. rules: - TryWithResource - MultiCatch - FieldRenaming - StandardLogger loggerRule: systemOutReplaceOption: INFO systemErrReplaceOption: ERROR printStacktraceReplaceOption: ERROR systemOutPrintExceptionReplaceOption: INFO systemErrPrintExceptionReplaceOption: ERROR addMissingLoggingStatement: ERROR attachExceptionObject: true renamingRule: fieldTypes: - private - protected - package-protected - public underscoreReplacementOption: Upper dollarReplacementOption: Leave # Define modules, classes and packages that you don't want to apply refactoring # to. Excluded modules can only be defined on the parent project and those modules # are then entirely ignored. If the module project has it's own yml file, it # overrides the entire configuration inherited from the yml configuration of # the parent project, unless it is an excluded module. excludes: excludeModules: - com.example.module1 excludePackages: - com.example.core - com.example.core.service excludeClasses: - com.example.core.Activator.java
Any configuration options in the YML file are case sensitive. Be careful how you type out things!
The rule IDs can be viewed using the list-rules-short-goal of the jsparrow-maven-plugin.
# Plugin Goals
The following plugin goals are supported:
This goal starts the refactoring process.
$ mvn jsparrow:refactor
You may add the following parameters:
| ||The specified configuration file will be used instead of the default (|
| ||The specified profile will be used. Make sure that either a |
| ||The specified Eclipse formatter file will be used when applying the Reformat Code rule. Have a look at Eclipse Formatter File for more information.|
| ||The built-in default configuration will be used for refactoring. If this parameter is set, the configuration in the root of the project will be ignored. |
It executes the following rules:
| ||Specify the license key to be used. This takes priority over a configuration via config file. In "Machine Configuration" the config file approach is described.|
| ||Specify the licensing server URL to use in case a local server should be used.|
| ||Specify the glob expression patterns (opens new window) relative to the project root directory for selecting the sources to refactor. Use line breaks to specify multiple glob patterns. If not specified, all Java sources in the project will be considered for refactoring. Examples: |
This goal starts jSparrow in "Report Mode". Similar to the
refactor goal, the
report goal analyzes the project and computes refactorings with the selected rules.
However, instead of committing the code changes to the original sources, jSparrow generates an HTML report with the findings of each rule, similar to our statistics (e.g., for jenkins-core).
No valid license is required and the source files are not affected.
$ mvn jsparrow:report
You may add the same parameters as in the
report goal does not require a license, this is a great way to see what the jSparrow Maven plugin has to offer for your project!
# List Rules
This goal lists rules with their IDs, names and descriptions.
$ mvn jsparrow:list-rules
You may add the following parameters:
| ||The rules with the given IDs will be listed. list-of-rule-ids is a comma-separated (,) list of rule ids.|
Per default all available rules will be listed.
# List Rules Short
This goal lists all rules in a table with ID and name
$ mvn jsparrow:list-rules-short
# License Info
This goal shows the licensing information.
$ mvn jsparrow:license-info
You may add the following parameters:
| ||The license key to be used|
| ||The licensing server to contact|
If the license key is not provided as a parameter, JMP will search for it in
This goal provides the plugin help.
$ mvn jsparrow:help
# Machine Configuration
It is possible to specify certain parameters using a configuration file in the users home directory, so it is not necessary to specify them using the command line for each run.
Currently only passing the license key and license server location using the configuration file is possible.
To pass the properties using the configuration file, create a file with the following contents in
key: <license-key> url: <http://somelocation.loc/>
In case of multi-module maven projects, the Field Renaming rule is limited to private fields only. The jSparrow Maven plugin will detect whether the project being refactored is part of a multi-module maven project and restrict the Field Renaming rule to be executed only on private fields.