# Getting started

Installation
- Requirements
- Using the jSparrow Plugin Repository
Usage
Plugin Goals
Machine Configuration
Limitations

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.

Important

We are currently only offering Maven licenses on request

# Installation

# Requirements

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

URL

https://download.jsparrow.eu/maven2 (opens new window)

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

The pluginRepository configuration via pom.xml:

<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 settings.xml:

Global Maven settings: ${maven.home}/conf/settings.xml
User Maven settings: ${user.home}/.m2/settings.xml

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>

# Usage

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-rules goal (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 pom.xml:

<build>
  <plugins>
    <plugin>
      <groupId>eu.jsparrow</groupId>
      <artifactId>jsparrow-maven-plugin</artifactId>
      <version>3.20.0</version>
    </plugin>
  </plugins>
</build>

Note

Use the artifactId jsparrow-4jdk8-maven-plugin if the runtime environment is restricted to Java 8.

# 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.

The 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 selectedProfile key.

The second section contains a list of rules which will be used for refactoring if no profile is designated as selectedProfile. 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

Important

Any configuration options in the YML file are case sensitive. Be careful how you type out things!

Note

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:

# Refactor

This goal starts the refactoring process.

$ mvn jsparrow:refactor

You may add the following parameters:

Parameter	Description
`-DconfigFile=<config-file-path>`	The specified configuration file will be used instead of the default (`jsparrow.yml`).
`-Dprofile=<selected-profile-id>`	The specified profile will be used. Make sure that either a `jsparrow.yml` is in the root directory or `-DconfigFile=<config-file-path>` is specified. The given profile ID will be compared to the declared profiles in the configuration file. If the given profile ID is not declared, an error will be thrown.
`-Dformatter=<formatter-file-path>`	The specified Eclipse formatter file will be used when applying the Reformat Code rule. Have a look at Eclipse Formatter File for more information.
`-DdefaultConfiguration`	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: Reformat Code Remove Explicit Type Argument Replace For-Loop with Iterable::forEach Replace For-Loop with Enhanced-For-Loop Use Stream::filter Use Multi Catch Remove Redundant Close Replace Request Mapping Annotation Replace Wrong Class for Logger Use Try-With-Resource Replace While-Loop with Enhanced For-Loop
`-Dlicense=<license-key>`	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.
`-Durl=<url>`	Specify the licensing server URL to use in case a local server should be used.
`-DselectedSources=<glob-patterns>`	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: `"core/"` Select the Java sources defined in the `core` package. The subpackages are not* included. `"core/"` Select the Java sources defined in the `core` package and in all** subpackages recursively. `"core/Application.java"` Select a single Java source. `"core/Application.java \n service/Order.java"` Select individual Java sources separated by line breaks. `"$(git diff-tree --no-commit-id --name-only -r HEAD)"` Select the sources modified in the last git commit. `""` No source is selected. No refactoring takes place.
`-DtempWorkspace='...'`	Specify the location for the temporal Eclipse workspace to import the project during jSparrow execution. This should an absolute path of an empty directory with read, write, and execute permissions. If not provided, jSparrow will use the Java temp directory for creating the workspace.

# Report

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 refactor goal. Additionally, the report goal offers a parameter to specify the location of the generated reports

Parameter	Description
`-Ddestination='path'`	Specify the location to generate the jSparrow reports into. The default value is the path of the project's build directory which is typically the target folder in the project root.

Note

Since 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:

Parameter	Description
`-Drules=<rule1,rule2...>`	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:

Parameter	Description
`-Dlicense=<license-key>`	The license key to be used
`-Durl=<url>`	The licensing server to contact

If the license key is not provided as a parameter, JMP will search for it in ~/.config/jsparrow-standalone/config.yml.

# Help

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 $HOME/.config/jsparrow-standalone/config.yml:

key: <license-key>
url: <http://somelocation.loc/>

# Limitations

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.

Local License Server →

Support