ResolutionStrategy (Gradle API 4.8)
Date: 2018-06-04

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:

       apply plugin: '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') with project(':api')
             substitute project(':util') with 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 and Description
    --- | ---
    `static class` | `ResolutionStrategy.SortOrder` Defines the sort order for components and artifacts produced by the configuration.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `ResolutionStrategy` | `activateDependencyLocking()` Activates dependency locking support in Gradle.
    `void` | `cacheChangingModulesFor(int value, String units)` Sets the length of time that changing modules will be cached, with units expressed as a String.
    `void` | `cacheChangingModulesFor(int value, TimeUnit units)` Sets the length of time that changing modules will be cached.
    `void` | `cacheDynamicVersionsFor(int value, String units)` Sets the length of time that dynamic versions will be cached, with units expressed as a String.
    `void` | `cacheDynamicVersionsFor(int value, TimeUnit units)` Sets the length of time that dynamic versions will be cached.
    `ResolutionStrategy` | `componentSelection(Action<? super ComponentSelectionRules> action)` The componentSelection block provides rules to filter or blacklist certain components from appearing in the resolution result.
    `ResolutionStrategy` | `dependencySubstitution(Action<? super DependencySubstitutions> action)` Configures the set of dependency substitution rules 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` | `failOnVersionConflict()` In case of conflict, Gradle by default uses the newest of conflicting versions.
    `ResolutionStrategy` | `force(Object... moduleVersionSelectorNotations)` Allows forcing certain versions of dependencies, including transitive dependencies.
    `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.
    `Set<ModuleVersionSelector>` | `getForcedModules()` Returns currently configured forced modules.
    `void` | `preferProjectModules()` Gradle can resolve conflicts purely by version number or prioritize project dependencies over binary.
    `ResolutionStrategy` | `setForcedModules(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:

           apply plugin: 'java' //so that there are some configurations

           configurations.all {
             resolutionStrategy.failOnVersionConflict()
           }

      Returns:
        this resolution strategy instance
      Since:
        1.0-milestone-6

    - #### preferProjectModules

          @Incubating
          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:

           apply plugin: 'java' //so that there are some configurations

           configurations.all {
             resolutionStrategy.preferProjectModules()
           }

      Since:
        3.2

    - #### activateDependencyLocking

          @Incubating
          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

    - #### force

          ResolutionStrategy force(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:

           apply plugin: '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(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:

           apply plugin: '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

          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

          @Incubating
          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 {
             compile.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,
                                       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,
                                       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,
                                       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,
                                       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

          @Incubating
          ComponentSelectionRules getComponentSelection()

      Returns the currently configured version selection rules object.
      Returns:
        the version selection rules
      Since:
        2.2

    - #### componentSelection

          @Incubating
          ResolutionStrategy componentSelection(Action<? super ComponentSelectionRules> action)

      The componentSelection block provides rules to filter or blacklist 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

          @Incubating
          DependencySubstitutions getDependencySubstitution()

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

    - #### dependencySubstitution

          @Incubating
          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') with project(':api')
               substitute project(':util') with module('org.gradle:util:3.0')

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

      Returns:
        this ResolutionStrategy instance
      Since:
        2.5
      See Also:
        `DependencySubstitutions`

    - #### sortArtifacts

          @Incubating
          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 it's dependencies.
      - `ResolutionStrategy.SortOrder.DEPENDENCY_FIRST` : Artifacts for a consuming component should appear after artifacts for it's 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