DependencySubstitutions (Gradle API 2.11)
Date: 2016-02-08

Package: org.gradle.api.artifacts

## [Java] Interface DependencySubstitutions

- Allows replacing dependencies with other dependencies.

  Since:
    2.5

- - ### Nested Class Summary

    Nested classes
    Modifiers | Name | Description
    --- | --- | ---
    `interface` | `DependencySubstitutions.Substitution` | Provides a DSL-friendly mechanism for specifying the target of a substitution.

  - ### Methods Summary

    Methods
    Type | Name and description
    --- | ---
    `DependencySubstitutions` | `all(Action<? super DependencySubstitution> rule)` Adds a dependency substitution rule that is triggered for every dependency (including transitive) when the configuration is being resolved.
    `ComponentSelector` | `module(String notation)` Create a ModuleComponentSelector from the provided input string.
    `ComponentSelector` | `project(String path)` Create a ProjectComponentSelector from the provided input string.
    `DependencySubstitutions.Substitution` | `substitute(ComponentSelector substitutedDependency)` DSL-friendly mechanism to construct a dependency substitution for dependencies matching the provided selector.

- - ### Method Detail

    - #### public DependencySubstitutions all(Action<? super DependencySubstitution> 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 DependencySubstitution that can be used to find out what dependency is being resolved and to influence the resolution process.

      Example:

           configurations { main }
           // add dependency substitution rules
           configurations.main.resolutionStrategy.dependencySubstitution {
             // Use a rule to change the dependency module while leaving group + version intact
             all { DependencySubstitution dependency ->
               if (dependency.requested instanceof ModuleComponentSelector && dependency.requested.name == 'groovy-all') {
                 dependency.useTarget details.requested.group + ':groovy:' + details.requested.version
               }
             }
             // Use a rule to replace all missing projects with module dependencies
             all { DependencySubstitution dependency ->
              if (dependency.requested instanceof ProjectComponentSelector) {
                 def targetProject = findProject(":${dependency.requested.path}")
                 if (targetProject == null) {
                   dependency.useTarget "org.myorg:" + dependency.requested.path + ":+"
                 }
               }
             }
           }

      The rules are evaluated in order they are declared. Rules are evaluated after forced modules are applied (see ResolutionStrategy.force
      Returns:
        this

    - #### public ComponentSelector module(String notation)

      Create a ModuleComponentSelector from the provided input string. Strings must be in the format "{group}:{module}:{version}".

    - #### public ComponentSelector project(String path)

      Create a ProjectComponentSelector from the provided input string. Strings must be in the format ":path".

    - #### public DependencySubstitutions.Substitution substitute(ComponentSelector substitutedDependency)

      DSL-friendly mechanism to construct a dependency substitution for dependencies matching the provided selector.

      Examples:

           configurations { main }
           configurations.main.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')
           }