Dependency Rule Types

Detailed examples of the syntax of rules are available in the Example Rules JSON page and the resolution rules repository.

Replace

Replace rules cause dependencies to be replaced with one at different coordinates, if both dependencies are present, avoiding class conflicts due to coordinate relocations.

Substitute

Dependency replaced with new coordinates, regardless if the new dependency is visible in the graph.

The module to be replaced may omit the version, or include a static or dynamic version selectors such as ranges. The replacement specified with with must include a version, but that version may be any type of version selector.

Minimum version rule

Support for ranges allow substitute rules to be used as a minimum version rule, for example:

"substitute": [
    {
        "module": "com.sun.jersey:jersey-bundle:(,1.18)",
        "with": "com.sun.jersey:jersey-bundle:1.18",
        ...
    }
]

This rule results in all jersey-bundle versions less than 1.18 being upgraded to 1.18.

Deny

Deny rules fail the build if the specified dependency is present, forcing consumers to make a decision about the replacement of a dependency.

Versions are optional, and access to an entire dependency can be denied. This is particularly useful for 'bundle' style dependencies, which fat jar dependencies without shading classes.

Reject

Reject rules prevent a dependency version from being considered by dynamic version or latest.* version calculation. It does not prevent that dependency from being used if it's explicitly requested by the project.

Exclude

Exclude rules excludes a dependency completely, similar to deny, but does not support a version and silently removes the dependency, rather than causing an error.

Align

Align rules allows the user to have a group of dependencies if present to have the same version. Example: if jersey-core and jersey-server are present make sure they use the same version.

Version selection

By default, alignment chooses the highest version of the dependencies matched by the rule. That behavior can be changed by using force to specify:

• Static version - the lowest forced version is used to align all dependencies included in the rule
• Dynamic versions - the highest force version matched by the most selective version specification, in this order:
  • Range version
  • Sub-version
  • Latest version

Includes and excludes

This rule has different options depending on your use case. includes and excludes are mutually exclusive, the plugin will error out if both are present in one rule.

Lock only a few dependencies in a group

{
    "align": [
        {
            "group": "example.foo",
            "includes": [ "bar", "baz" ]
        }
    ]
}

Lock most dependencies in a group, but exclude some

{
    "align": [
        {
            "name": "example",
            "group": "example.bar",
            "excludes": [ "qux", "thud" ]
        }
    ]
}

Lock all dependencies in a group matching a regular expression

{
    "align": [
        {
            "group": "example.foo.*",
        }
    ]
}

Lock all dependencies, including those matching a regular expression

{
    "align": [
        {
            "group": "example.foo",
            "includes": [ "(bar|baz)" ]
        }
    ]
}