Package org.gradle.api.artifacts

Interface ResolutionStrategy

public interface ResolutionStrategy

Defines the strategies around dependency resolution. For example, forcing certain dependency versions, substitutions, conflict resolutions or snapshot timeouts.

Examples:

 plugins {
     id 'java' // so that there are some configurations
 }

 configurations.all {
   resolutionStrategy {
     // fail eagerly on version conflict (includes transitive dependencies)
     // e.g. multiple different versions of the same dependency (group and name are equal)
     failOnVersionConflict()

     // prefer modules that are part of this build (multi-project or composite build) over external modules
     preferProjectModules()

     // force certain versions of dependencies (including transitive)
     //  *append new forced modules:
     force 'asm:asm-all:3.3.1', 'commons-io:commons-io:1.4'
     //  *replace existing forced modules with new ones:
     forcedModules = ['asm:asm-all:3.3.1']

     // add dependency substitution rules
     dependencySubstitution {
       substitute module('org.gradle:api') using project(':api')
       substitute project(':util') using module('org.gradle:util:3.0')
     }

     // cache dynamic versions for 10 minutes
     cacheDynamicVersionsFor 10*60, 'seconds'
     // don't cache changing modules at all
     cacheChangingModulesFor 0, 'seconds'
   }
 }
 

Since:

1.0-milestone-6

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static class	ResolutionStrategy.SortOrder	Defines the sort order for components and artifacts produced by the configuration.

Method Summary

Modifier and Type	Method	Description
ResolutionStrategy	activateDependencyLocking()	Activates dependency locking support in Gradle.
void	cacheChangingModulesFor(int value, java.lang.String units)	Sets the length of time that changing modules will be cached, with units expressed as a String.
void	cacheChangingModulesFor(int value, java.util.concurrent.TimeUnit units)	Sets the length of time that changing modules will be cached.
void	cacheDynamicVersionsFor(int value, java.lang.String units)	Sets the length of time that dynamic versions will be cached, with units expressed as a String.
void	cacheDynamicVersionsFor(int value, java.util.concurrent.TimeUnit units)	Sets the length of time that dynamic versions will be cached.
ResolutionStrategy	capabilitiesResolution(Action<? super CapabilitiesResolution> action)	Configures the capabilities resolution strategy.
ResolutionStrategy	componentSelection(Action<? super ComponentSelectionRules> action)	The componentSelection block provides rules to filter or prevent certain components from appearing in the resolution result.
ResolutionStrategy	deactivateDependencyLocking()	Deactivates dependency locking support in Gradle.
ResolutionStrategy	dependencySubstitution(Action<? super DependencySubstitutions> action)	Configures the set of dependency substitution rules for this configuration.
ResolutionStrategy	disableDependencyVerification()	Deactivates dependency verification for this configuration.
ResolutionStrategy	eachDependency(Action<? super DependencyResolveDetails> rule)	Adds a dependency substitution rule that is triggered for every dependency (including transitive) when the configuration is being resolved.
ResolutionStrategy	enableDependencyVerification()	Enabled dependency verification for this configuration.
ResolutionStrategy	failOnChangingVersions()	If this method is called, Gradle will make sure that no changing version participates in resolution.
ResolutionStrategy	failOnDynamicVersions()	If this method is called, Gradle will make sure that no dynamic version was used in the resulting dependency graph.
ResolutionStrategy	failOnNonReproducibleResolution()	Configures Gradle to fail the build is the resolution result is expected to be unstable, that is to say that it includes dynamic versions or changing versions and therefore the result may change depending on when the build is executed.
ResolutionStrategy	failOnVersionConflict()	In case of conflict, Gradle by default uses the newest of conflicting versions.
ResolutionStrategy	force(java.lang.Object... moduleVersionSelectorNotations)	Allows forcing certain versions of dependencies, including transitive dependencies.
CapabilitiesResolution	getCapabilitiesResolution()	Returns the capabilities resolution strategy.
ComponentSelectionRules	getComponentSelection()	Returns the currently configured version selection rules object.
DependencySubstitutions	getDependencySubstitution()	Returns the set of dependency substitution rules that are set for this configuration.
java.util.Set<ModuleVersionSelector>	getForcedModules()	Returns currently configured forced modules.
Property<java.lang.Boolean>	getUseGlobalDependencySubstitutionRules()	Gradle implicitly registers dependency substitution rules for all configurations in the whole build tree to find projects in other included builds.
void	preferProjectModules()	Gradle can resolve conflicts purely by version number or prioritize project dependencies over binary.
ResolutionStrategy	setForcedModules(java.lang.Object... moduleVersionSelectorNotations)	Allows forcing certain versions of dependencies, including transitive dependencies.
void	sortArtifacts(ResolutionStrategy.SortOrder sortOrder)	Specifies the ordering for resolved artifacts.

Method Detail

failOnVersionConflict

ResolutionStrategy failOnVersionConflict()

In case of conflict, Gradle by default uses the newest of conflicting versions. However, you can change this behavior. Use this method to configure the resolution to fail eagerly on any version conflict, e.g. multiple different versions of the same dependency (group and name are equal) in the same Configuration. The check includes both first level and transitive dependencies. See example below:

 plugins {
     id 'java' // so that there are some configurations
 }

 configurations.all {
   resolutionStrategy.failOnVersionConflict()
 }
 

Returns:

this resolution strategy instance

Since:

1.0-milestone-6

failOnDynamicVersions

ResolutionStrategy failOnDynamicVersions()

If this method is called, Gradle will make sure that no dynamic version was used in the resulting dependency graph. In practice, it means that if the resolved dependency graph contains a module and that the versions participating in the selection of that module contain at least one dynamic version, then resolution will fail if the resolution result can change because of this version selector. This can be used in cases you want to make sure your build is reproducible, without relying on dependency locking.

Returns:

this resolution strategy

Since:

6.1

failOnChangingVersions

ResolutionStrategy failOnChangingVersions()

If this method is called, Gradle will make sure that no changing version participates in resolution. This can be used in cases you want to make sure your build is reproducible, without relying on dependency locking.

Returns:

this resolution strategy

Since:

6.1

failOnNonReproducibleResolution

ResolutionStrategy failOnNonReproducibleResolution()

Configures Gradle to fail the build is the resolution result is expected to be unstable, that is to say that it includes dynamic versions or changing versions and therefore the result may change depending on when the build is executed. This method is equivalent to calling both failOnDynamicVersions() and failOnChangingVersions().

Returns:

this resolution strategy

Since:

6.1

preferProjectModules

void preferProjectModules()

Gradle can resolve conflicts purely by version number or prioritize project dependencies over binary. The default is by version number.

This applies to both first level and transitive dependencies. See example below:

 plugins {
     id 'java' // so that there are some configurations
 }

 configurations.all {
   resolutionStrategy.preferProjectModules()
 }
 

Since:

3.2

activateDependencyLocking

ResolutionStrategy activateDependencyLocking()

Activates dependency locking support in Gradle. Once turned on on a configuration, resolution result can be saved and then reused for subsequent builds. This enables reproducible builds when using dynamic versions.

Returns:

this resolution strategy instance

Since:

4.8

deactivateDependencyLocking

ResolutionStrategy deactivateDependencyLocking()

Deactivates dependency locking support in Gradle.

Returns:

this resolution strategy instance

Since:

6.0

disableDependencyVerification

ResolutionStrategy disableDependencyVerification()

Deactivates dependency verification for this configuration. You should always be careful when disabling verification, and in particular avoid disabling it for verification of plugins, because a plugin could use this to disable verification itself.

Since:

6.2

enableDependencyVerification

ResolutionStrategy enableDependencyVerification()

Enabled dependency verification for this configuration.

Since:

6.2

force

ResolutionStrategy force(java.lang.Object... moduleVersionSelectorNotations)

Allows forcing certain versions of dependencies, including transitive dependencies. Appends new forced modules to be considered when resolving dependencies.

It accepts following notations:

• String in a format of: 'group:name:version', for example: 'org.gradle:gradle-core:1.0'
• instance of ModuleVersionSelector
• any collection or array of above will be automatically flattened

Example:

 plugins {
     id 'java' // so that there are some configurations
 }

 configurations.all {
   resolutionStrategy.force 'asm:asm-all:3.3.1', 'commons-io:commons-io:1.4'
 }
 

Parameters:

moduleVersionSelectorNotations - typically group:name:version notations to append

Returns:

this ResolutionStrategy instance

Since:

1.0-milestone-7

setForcedModules

ResolutionStrategy setForcedModules(java.lang.Object... moduleVersionSelectorNotations)

Allows forcing certain versions of dependencies, including transitive dependencies. Replaces existing forced modules with the input.

For information on notations see force(Object...)

Example:

 plugins {
     id 'java' // so that there are some configurations
 }

 configurations.all {
   resolutionStrategy.forcedModules = ['asm:asm-all:3.3.1', 'commons-io:commons-io:1.4']
 }
 

Parameters:

moduleVersionSelectorNotations - typically group:name:version notations to set

Returns:

this ResolutionStrategy instance

Since:

1.0-milestone-7

getForcedModules

java.util.Set<ModuleVersionSelector> getForcedModules()

Returns currently configured forced modules. For more information on forcing versions see force(Object...)

Returns:

forced modules

Since:

1.0-milestone-7

eachDependency

ResolutionStrategy eachDependency(Action<? super DependencyResolveDetails> rule)

Adds a dependency substitution rule that is triggered for every dependency (including transitive) when the configuration is being resolved. The action receives an instance of DependencyResolveDetails that can be used to find out what dependency is being resolved and to influence the resolution process. Example:

 configurations {
   compileClasspath.resolutionStrategy {
     eachDependency { DependencyResolveDetails details ->
       //specifying a fixed version for all libraries with 'org.gradle' group
       if (details.requested.group == 'org.gradle') {
         details.useVersion '1.4'
       }
     }
     eachDependency { details ->
       //multiple actions can be specified
       if (details.requested.name == 'groovy-all') {
          //changing the name:
          details.useTarget group: details.requested.group, name: 'groovy', version: details.requested.version
       }
     }
   }
 }
 

The rules are evaluated in order they are declared. Rules are evaluated after forced modules are applied (see force(Object...)

Returns:

this

Since:

1.4

cacheDynamicVersionsFor

void cacheDynamicVersionsFor(int value,
                             java.lang.String units)

Sets the length of time that dynamic versions will be cached, with units expressed as a String.

A convenience method for cacheDynamicVersionsFor(int, java.util.concurrent.TimeUnit) with units expressed as a String. Units are resolved by calling the valueOf(String) method of TimeUnit with the upper-cased string value.

Parameters:

value - The number of time units

units - The units

Since:

1.0-milestone-6

cacheDynamicVersionsFor

void cacheDynamicVersionsFor(int value,
                             java.util.concurrent.TimeUnit units)

Sets the length of time that dynamic versions will be cached.

Gradle keeps a cache of dynamic version => resolved version (ie 2.+ => 2.3). By default, these cached values are kept for 24 hours, after which the cached entry is expired and the dynamic version is resolved again.

Use this method to provide a custom expiry time after which the cached value for any dynamic version will be expired.

Parameters:

value - The number of time units

units - The units

Since:

1.0-milestone-6

cacheChangingModulesFor

void cacheChangingModulesFor(int value,
                             java.lang.String units)

Sets the length of time that changing modules will be cached, with units expressed as a String.

A convenience method for cacheChangingModulesFor(int, java.util.concurrent.TimeUnit) with units expressed as a String. Units are resolved by calling the valueOf(String) method of TimeUnit with the upper-cased string value.

Parameters:

value - The number of time units

units - The units

Since:

1.0-milestone-6

cacheChangingModulesFor

void cacheChangingModulesFor(int value,
                             java.util.concurrent.TimeUnit units)

Sets the length of time that changing modules will be cached.

Gradle caches the contents and artifacts of changing modules. By default, these cached values are kept for 24 hours, after which the cached entry is expired and the module is resolved again.

Use this method to provide a custom expiry time after which the cached entries for any changing module will be expired.

Parameters:

value - The number of time units

units - The units

Since:

1.0-milestone-6

getComponentSelection

ComponentSelectionRules getComponentSelection()

Returns the currently configured version selection rules object.

Returns:

the version selection rules

Since:

2.2

componentSelection

ResolutionStrategy componentSelection(Action<? super ComponentSelectionRules> action)

The componentSelection block provides rules to filter or prevent certain components from appearing in the resolution result.

Parameters:

action - Action to be applied to the ComponentSelectionRules

Returns:

this ResolutionStrategy instance

Since:

2.2

getDependencySubstitution

DependencySubstitutions getDependencySubstitution()

Returns the set of dependency substitution rules that are set for this configuration.

Since:

2.5

dependencySubstitution

ResolutionStrategy dependencySubstitution(Action<? super DependencySubstitutions> action)

Configures the set of dependency substitution rules for this configuration. The action receives an instance of DependencySubstitutions which can then be configured with substitution rules.

Examples:

 // add dependency substitution rules
 configurations.all {
   resolutionStrategy.dependencySubstitution {
     // Substitute project and module dependencies
     substitute module('org.gradle:api') using project(':api')
     substitute project(':util') using module('org.gradle:util:3.0')

     // Substitute one module dependency for another
     substitute module('org.gradle:api:2.0') using module('org.gradle:api:2.1')
   }
 }
 

Returns:

this ResolutionStrategy instance

Since:

2.5

See Also:

DependencySubstitutions

getUseGlobalDependencySubstitutionRules

Property<java.lang.Boolean> getUseGlobalDependencySubstitutionRules()

Gradle implicitly registers dependency substitution rules for all configurations in the whole build tree to find projects in other included builds. These rules are always active by default. There are however cases, where a certain configuration should not apply these rules when resolving. For example, if a binary version of a module should be discovered that is also represented by a project in another build. This property may be used to deactivate these global substitution rules.

Since:

7.4

sortArtifacts

void sortArtifacts(ResolutionStrategy.SortOrder sortOrder)

Specifies the ordering for resolved artifacts. Options are:

• ResolutionStrategy.SortOrder.DEFAULT : Don't specify the sort order. Gradle will provide artifacts in the default order.
• ResolutionStrategy.SortOrder.CONSUMER_FIRST : Artifacts for a consuming component should appear before artifacts for its dependencies.
• ResolutionStrategy.SortOrder.DEPENDENCY_FIRST : Artifacts for a consuming component should appear after artifacts for its dependencies.

A best attempt will be made to sort artifacts according the supplied ResolutionStrategy.SortOrder, but no guarantees will be made in the presence of dependency cycles. NOTE: For a particular Gradle version, artifact ordering will be consistent. Multiple resolves for the same inputs will result in the same outputs in the same order.

Since:

3.5

capabilitiesResolution

ResolutionStrategy capabilitiesResolution(Action<? super CapabilitiesResolution> action)

Configures the capabilities resolution strategy.

Parameters:

action - the configuration action.

Returns:

this resolution strategy

Since:

5.6

getCapabilitiesResolution

CapabilitiesResolution getCapabilitiesResolution()

Returns the capabilities resolution strategy.

Since:

5.6