Package org.gradle.api.artifacts.dsl

## Interface DependencyHandler

- All Superinterfaces:
    `ExtensionAware`

      public interface DependencyHandler
      extends ExtensionAware

  A `DependencyHandler` is used to declare dependencies. Dependencies are grouped into configurations (see `Configuration`).

  To declare a specific dependency for a configuration you can use the following syntax:

       dependencies {
           configurationName dependencyNotation
       }

  Example shows a basic way of declaring dependencies.

       plugins {
           id 'java' // so that we can use 'implementation', 'testImplementation' for dependencies
       }

       dependencies {
         //for dependencies found in artifact repositories you can use
         //the group:name:version notation
         implementation 'commons-lang:commons-lang:2.6'
         testImplementation 'org.mockito:mockito:1.9.0-rc1'

         //map-style notation:
         implementation group: 'com.google.code.guice', name: 'guice', version: '1.0'

         //declaring arbitrary files as dependencies
         implementation files('hibernate.jar', 'libs/spring.jar')

         //putting all jars from 'libs' onto compile classpath
         implementation fileTree('libs')
       }

  ## Advanced dependency configuration

  To do some advanced configuration on a dependency when it is declared, you can additionally pass a configuration closure:

       dependencies {
           configurationName(dependencyNotation){
               configStatement1
               configStatement2
           }
       }

  Examples of advanced dependency declaration including:
  - Forcing certain dependency version in case of the conflict.
  - Excluding certain dependencies by name, group or both. More details about per-dependency exclusions can be found in docs for `ModuleDependency.exclude(java.util.Map)`.
  - Avoiding transitive dependencies for certain dependency.

       plugins {
           id 'java' // so that I can declare 'implementation' dependencies
       }

       dependencies {
         implementation('org.hibernate:hibernate:3.1') {
           //in case of versions conflict '3.1' version of hibernate wins:
           force = true

           //excluding a particular transitive dependency:
           exclude module: 'cglib' //by artifact name
           exclude group: 'org.jmock' //by group
           exclude group: 'org.unwanted', module: 'iAmBuggy' //by both name and group

           //disabling all transitive dependencies of this dependency
           transitive = false
         }
       }

  More examples of advanced configuration, useful when dependency module has multiple artifacts:
  - Declaring dependency to a specific configuration of the module.
  - Explicit specification of the artifact. See also `ModuleDependency.artifact(groovy.lang.Closure)`.

       plugins {
           id 'java' // so that I can declare 'implementation' dependencies
       }

       dependencies {
         //configuring dependency to specific configuration of the module
         implementation configuration: 'someConf', group: 'org.someOrg', name: 'someModule', version: '1.0'

         //configuring dependency on 'someLib' module
         implementation(group: 'org.myorg', name: 'someLib', version:'1.0') {
           //explicitly adding the dependency artifact:
           artifact {
             //useful when some artifact properties unconventional
             name = 'someArtifact' //artifact name different than module name
             extension = 'someExt'
             type = 'someType'
             classifier = 'someClassifier'
           }
         }
       }

  ## Dependency notations

  There are several supported dependency notations. These are described below. For each dependency declared this way, a `Dependency` object is created. You can use this object to query or further configure the dependency.

  You can also always add instances of `Dependency` directly:

  `configurationName <instance>`

  Dependencies can also be declared with a `Provider` that provides any of the other supported dependency notations.

  ### External dependencies

  There are two notations supported for declaring a dependency on an external module. One is a string notation formatted this way:

  `configurationName "group:name:version:classifier@extension"`

  The other is a map notation:

  `configurationName group: group, name: name, version: version, classifier: classifier, ext: extension`

  In both notations, all properties, except name, are optional.

  External dependencies are represented by a `ExternalModuleDependency`.

       plugins {
           id 'java' // so that we can use 'implementation', 'testImplementation' for dependencies
       }

       dependencies {
         //for dependencies found in artifact repositories you can use
         //the string notation, e.g. group:name:version
         implementation 'commons-lang:commons-lang:2.6'
         testImplementation 'org.mockito:mockito:1.9.0-rc1'

         //map notation:
         implementation group: 'com.google.code.guice', name: 'guice', version: '1.0'
       }

  ### Project dependencies

  To add a project dependency, you use the following notation:

  `configurationName project(':some-project')`

  The notation `project(':project-a')` is similar to the syntax you use when configuring a projectA in a multi-module gradle project.

  By default, when you declare dependency to projectA, you actually declare dependency to the 'default' configuration of the projectA. If you need to depend on a specific configuration of projectA, use map notation for projects:

  `configurationName project(path: ':project-a', configuration: 'someOtherConfiguration')`

  Project dependencies are represented using a `ProjectDependency`.

  ### File dependencies

  You can also add a dependency using a `FileCollection`:

  `configurationName files('a file')`

       plugins {
           id 'java' // so that we can use 'implementation', 'testImplementation' for dependencies
       }

       dependencies {
         //declaring arbitrary files as dependencies
         implementation files('hibernate.jar', 'libs/spring.jar')

         //putting all jars from 'libs' onto compile classpath
         implementation fileTree('libs')
       }

  File dependencies are represented using a `SelfResolvingDependency`.

  ### Dependencies to other configurations

  You can add a dependency using a `Configuration`.

  When the configuration is from the same project as the target configuration, the target configuration is changed to extend from the provided configuration.

  When the configuration is from a different project, a project dependency is added.

  ### Gradle distribution specific dependencies

  It is possible to depend on certain Gradle APIs or libraries that Gradle ships with. It is particularly useful for Gradle plugin development. Example:

       //Our Gradle plugin is written in groovy
       plugins {
           id 'groovy'
       }
       // now we can use the 'implementation' configuration for declaring dependencies

       dependencies {
         //we will use the Groovy version that ships with Gradle:
         implementation localGroovy()

         //our plugin requires Gradle API interfaces and classes to compile:
         implementation gradleApi()

         //we will use the Gradle test-kit to test build logic:
         testImplementation gradleTestKit()
       }

  ### Client module dependencies

  To add a client module to a configuration you can use the notation:

       configurationName module(moduleNotation) {
           module dependencies
       }

  The module notation is the same as the dependency notations described above, except that the classifier property is not available. Client modules are represented using a `ClientModule`.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods Deprecated Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `Dependency` | `add​(String configurationName, Object dependencyNotation)` | Adds a dependency to the given configuration.
    `Dependency` | `add​(String configurationName, Object dependencyNotation, Closure configureClosure)` | Adds a dependency to the given configuration, and configures the dependency using the given closure.
    `<T> void` | `addProvider​(String configurationName, Provider<T> dependencyNotation)` | Adds a dependency provider to the given configuration.
    `<T,​U extends ExternalModuleDependency> void` | `addProvider​(String configurationName, Provider<T> dependencyNotation, Action<? super U> configuration)` | Adds a dependency provider to the given configuration, eventually configures the dependency using the given action.
    `void` | `artifactTypes​(Action<? super ArtifactTypeContainer> configureAction)` | Configures the artifact type definitions for this handler.
    `AttributesSchema` | `attributesSchema​(Action<? super AttributesSchema> configureAction)` | Configures the attributes schema.
    `void` | `components​(Action<? super ComponentMetadataHandler> configureAction)` | Configures component metadata for this project.
    `void` | `constraints​(Action<? super DependencyConstraintHandler> configureAction)` | Configures dependency constraint for this project.
    `Dependency` | `create​(Object dependencyNotation)` | Creates a dependency without adding it to a configuration.
    `Dependency` | `create​(Object dependencyNotation, Closure configureClosure)` | Creates a dependency without adding it to a configuration, and configures the dependency using the given closure.
    `ArtifactResolutionQuery` | `createArtifactResolutionQuery()` | Creates an artifact resolution query.
    `Dependency` | `enforcedPlatform​(Object notation)` | Declares a dependency on an enforced platform.
    `Dependency` | `enforcedPlatform​(Object notation, Action<? super Dependency> configureAction)` | Declares a dependency on an enforced platform.
    `Provider<MinimalExternalModuleDependency>` | `enforcedPlatform​(Provider<MinimalExternalModuleDependency> dependencyProvider)` | Configures this dependency provider to select the enforced-platform variant of the target component
    `default Provider<MinimalExternalModuleDependency>` | `enforcedPlatform​(ProviderConvertible<MinimalExternalModuleDependency> dependencyProviderConvertible)` | Configures this dependency provider to select the enforced-platform variant of the target component
    `ArtifactTypeContainer` | `getArtifactTypes()` | Returns the artifact type definitions for this handler.
    `AttributesSchema` | `getAttributesSchema()` | Returns the attributes schema for this handler.
    `ComponentMetadataHandler` | `getComponents()` | Returns the component metadata handler for this project.
    `DependencyConstraintHandler` | `getConstraints()` | Returns the dependency constraint handler for this project.
    `ComponentModuleMetadataHandler` | `getModules()` | Returns the component module metadata handler for this project.
    `Dependency` | `gradleApi()` | Creates a dependency on the API of the current version of Gradle.
    `Dependency` | `gradleTestKit()` | Creates a dependency on the Gradle test-kit API.
    `Dependency` | `localGroovy()` | Creates a dependency on the Groovy that is distributed with the current version of Gradle.
    `Dependency` | `module​(Object notation)` | Creates a dependency on a client module.
    `Dependency` | `module​(Object notation, Closure configureClosure)` | Creates a dependency on a client module.
    `void` | `modules​(Action<? super ComponentModuleMetadataHandler> configureAction)` | Configures module metadata for this project.
    `Dependency` | `platform​(Object notation)` | Declares a dependency on a platform.
    `Dependency` | `platform​(Object notation, Action<? super Dependency> configureAction)` | Declares a dependency on a platform.
    `default Provider<MinimalExternalModuleDependency>` | `platform​(Provider<MinimalExternalModuleDependency> dependencyProvider)` | Configures this dependency provider to select the platform variant of the target component
    `default Provider<MinimalExternalModuleDependency>` | `platform​(ProviderConvertible<MinimalExternalModuleDependency> dependencyProviderConvertible)` | Configures this dependency provider to select the platform variant of the target component
    `Dependency` | `project​(Map<String,​?> notation)` | Creates a dependency on a project.
    `<T extends TransformParameters> void` | `registerTransform​(Class<? extends TransformAction<T>> actionType, Action<? super TransformSpec<T>> registrationAction)` | Registers an artifact transform.
    `void` | `registerTransform​(Action<? super VariantTransform> registrationAction)` | Deprecated. use `registerTransform(Class, Action)` instead.
    `Dependency` | `testFixtures​(Object notation)` | Declares a dependency on the test fixtures of a component.
    `Dependency` | `testFixtures​(Object notation, Action<? super Dependency> configureAction)` | Declares a dependency on the test fixtures of a component and allows configuring the resulting dependency.
    `default Provider<MinimalExternalModuleDependency>` | `testFixtures​(Provider<MinimalExternalModuleDependency> dependencyProvider)` | Configures this dependency provider to select the test fixtures of the target component
    `default Provider<MinimalExternalModuleDependency>` | `testFixtures​(ProviderConvertible<MinimalExternalModuleDependency> dependencyProviderConvertible)` | Configures this dependency provider to select the test fixtures of the target component
    `Provider<MinimalExternalModuleDependency>` | `variantOf​(Provider<MinimalExternalModuleDependency> dependencyProvider, Action<? super ExternalModuleDependencyVariantSpec> variantSpec)` | Allows fine-tuning what variant to select for the target dependency.
    `default Provider<MinimalExternalModuleDependency>` | `variantOf​(ProviderConvertible<MinimalExternalModuleDependency> dependencyProviderConvertible, Action<? super ExternalModuleDependencyVariantSpec> variantSpec)` | Allows fine-tuning what variant to select for the target dependency.

    - ### Methods inherited from interface org.gradle.api.plugins.ExtensionAware

      `getExtensions`

- - ### Method Detail

    - #### add

          @Nullable
          Dependency add​(String configurationName,
                         Object dependencyNotation)

      Adds a dependency to the given configuration.
      Parameters:
        `configurationName` - The name of the configuration.
        `dependencyNotation` - The dependency notation, in one of the notations described above.
      Returns:
        The dependency.

    - #### add

          Dependency add​(String configurationName,
                         Object dependencyNotation,
                         Closure configureClosure)

      Adds a dependency to the given configuration, and configures the dependency using the given closure.
      Parameters:
        `configurationName` - The name of the configuration.
        `dependencyNotation` - The dependency notation, in one of the notations described above.
        `configureClosure` - The closure to use to configure the dependency.
      Returns:
        The dependency.

    - #### addProvider

          @Incubating
          <T,​U extends ExternalModuleDependency> void addProvider​(String configurationName,
                                                                        Provider<T> dependencyNotation,
                                                                        Action<? super U> configuration)

      Adds a dependency provider to the given configuration, eventually configures the dependency using the given action.
      Parameters:
        `configurationName` - The name of the configuration.
        `dependencyNotation` - The dependency provider notation, in one of the notations described above.
        `configuration` - The action to use to configure the dependency.
      Since:
        6.8

    - #### addProvider

          @Incubating
          <T> void addProvider​(String configurationName,
                               Provider<T> dependencyNotation)

      Adds a dependency provider to the given configuration.
      Parameters:
        `configurationName` - The name of the configuration.
        `dependencyNotation` - The dependency provider notation, in one of the notations described above.
      Since:
        7.0

    - #### create

          Dependency create​(Object dependencyNotation)

      Creates a dependency without adding it to a configuration.
      Parameters:
        `dependencyNotation` - The dependency notation, in one of the notations described above.
      Returns:
        The dependency.

    - #### create

          Dependency create​(Object dependencyNotation,
                            Closure configureClosure)

      Creates a dependency without adding it to a configuration, and configures the dependency using the given closure.
      Parameters:
        `dependencyNotation` - The dependency notation, in one of the notations described above.
        `configureClosure` - The closure to use to configure the dependency.
      Returns:
        The dependency.

    - #### module

          Dependency module​(Object notation)

      Creates a dependency on a client module.
      Parameters:
        `notation` - The module notation, in one of the notations described above.
      Returns:
        The dependency.

    - #### module

          Dependency module​(Object notation,
                            Closure configureClosure)

      Creates a dependency on a client module. The dependency is configured using the given closure before it is returned.
      Parameters:
        `notation` - The module notation, in one of the notations described above.
        `configureClosure` - The closure to use to configure the dependency.
      Returns:
        The dependency.

    - #### project

          Dependency project​(Map<String,​?> notation)

      Creates a dependency on a project.
      Parameters:
        `notation` - The project notation, in one of the notations described above.
      Returns:
        The dependency.

    - #### gradleApi

          Dependency gradleApi()

      Creates a dependency on the API of the current version of Gradle.
      Returns:
        The dependency.

    - #### gradleTestKit

          Dependency gradleTestKit()

      Creates a dependency on the Gradle test-kit API.
      Returns:
        The dependency.
      Since:
        2.6

    - #### localGroovy

          Dependency localGroovy()

      Creates a dependency on the Groovy that is distributed with the current version of Gradle.
      Returns:
        The dependency.

    - #### getConstraints

          DependencyConstraintHandler getConstraints()

      Returns the dependency constraint handler for this project.
      Returns:
        the dependency constraint handler for this project
      Since:
        4.5

    - #### constraints

          void constraints​(Action<? super DependencyConstraintHandler> configureAction)

      Configures dependency constraint for this project.

      This method executes the given action against the `DependencyConstraintHandler` for this project.

      Parameters:
        `configureAction` - the action to use to configure module metadata
      Since:
        4.5

    - #### getComponents

          ComponentMetadataHandler getComponents()

      Returns the component metadata handler for this project. The returned handler can be used for adding rules that modify the metadata of depended-on software components.
      Returns:
        the component metadata handler for this project
      Since:
        1.8

    - #### components

          void components​(Action<? super ComponentMetadataHandler> configureAction)

      Configures component metadata for this project.

      This method executes the given action against the `ComponentMetadataHandler` for this project.

      Parameters:
        `configureAction` - the action to use to configure module metadata
      Since:
        1.8

    - #### getModules

          ComponentModuleMetadataHandler getModules()

      Returns the component module metadata handler for this project. The returned handler can be used for adding rules that modify the metadata of depended-on software components.
      Returns:
        the component module metadata handler for this project
      Since:
        2.2

    - #### modules

          void modules​(Action<? super ComponentModuleMetadataHandler> configureAction)

      Configures module metadata for this project.

      This method executes the given action against the `ComponentModuleMetadataHandler` for this project.

      Parameters:
        `configureAction` - the action to use to configure module metadata
      Since:
        2.2

    - #### createArtifactResolutionQuery

          ArtifactResolutionQuery createArtifactResolutionQuery()

      Creates an artifact resolution query.
      Since:
        2.0

    - #### attributesSchema

          AttributesSchema attributesSchema​(Action<? super AttributesSchema> configureAction)

      Configures the attributes schema. The action is passed a `AttributesSchema` instance.
      Parameters:
        `configureAction` - the configure action
      Returns:
        the configured schema
      Since:
        3.4

    - #### getAttributesSchema

          AttributesSchema getAttributesSchema()

      Returns the attributes schema for this handler.
      Returns:
        the attributes schema
      Since:
        3.4

    - #### getArtifactTypes

          ArtifactTypeContainer getArtifactTypes()

      Returns the artifact type definitions for this handler.
      Since:
        4.0

    - #### artifactTypes

          void artifactTypes​(Action<? super ArtifactTypeContainer> configureAction)

      Configures the artifact type definitions for this handler.
      Since:
        4.0

    - #### registerTransform

          @Deprecated
          void registerTransform​(Action<? super VariantTransform> registrationAction)

      Deprecated.
      use `registerTransform(Class, Action)` instead.
      Registers an artifact transform.
      Since:
        3.5
      See Also:
        `ArtifactTransform`

    - #### registerTransform

          <T extends TransformParameters> void registerTransform​(Class<? extends TransformAction<T>> actionType,
                                                                 Action<? super TransformSpec<T>> registrationAction)

      Registers an artifact transform.

      The registration action needs to specify the `from` and `to` attributes. It may also provide parameters for the transform action by using `TransformSpec.parameters(Action)`.

      For example:

           // You have a transform action like this:
           abstract class MyTransform implements TransformAction<Parameters> {
               interface Parameters extends TransformParameters {
                   @Input
                   Property<String> getStringParameter();
                   @InputFiles
                   ConfigurableFileCollection getInputFiles();
               }

               void transform(TransformOutputs outputs) {
                   // ...
               }
           }

           // Then you can register the action like this:

           def artifactType = Attribute.of('artifactType', String)

           dependencies.registerTransform(MyTransform) {
               from.attribute(artifactType, "jar")
               to.attribute(artifactType, "java-classes-directory")

               parameters {
                   stringParameter.set("Some string")
                   inputFiles.from("my-input-file")
               }
           }

      Since:
        5.3
      See Also:
        `TransformAction`

    - #### platform

          Dependency platform​(Object notation)

      Declares a dependency on a platform. If the target coordinates represent multiple potential components, the platform component will be selected, instead of the library.
      Parameters:
        `notation` - the coordinates of the platform
      Since:
        5.0

    - #### platform

          Dependency platform​(Object notation,
                              Action<? super Dependency> configureAction)

      Declares a dependency on a platform. If the target coordinates represent multiple potential components, the platform component will be selected, instead of the library.
      Parameters:
        `notation` - the coordinates of the platform
        `configureAction` - the dependency configuration block
      Since:
        5.0

    - #### enforcedPlatform

          Dependency enforcedPlatform​(Object notation)

      Declares a dependency on an enforced platform. If the target coordinates represent multiple potential components, the platform component will be selected, instead of the library. An enforced platform is a platform for which the direct dependencies are forced, meaning that they would override any other version found in the graph.
      Parameters:
        `notation` - the coordinates of the platform
      Since:
        5.0

    - #### enforcedPlatform

          Dependency enforcedPlatform​(Object notation,
                                      Action<? super Dependency> configureAction)

      Declares a dependency on an enforced platform. If the target coordinates represent multiple potential components, the platform component will be selected, instead of the library. An enforced platform is a platform for which the direct dependencies are forced, meaning that they would override any other version found in the graph.
      Parameters:
        `notation` - the coordinates of the platform
        `configureAction` - the dependency configuration block
      Since:
        5.0

    - #### testFixtures

          Dependency testFixtures​(Object notation)

      Declares a dependency on the test fixtures of a component.
      Parameters:
        `notation` - the coordinates of the component to use test fixtures for
      Since:
        5.6

    - #### testFixtures

          Dependency testFixtures​(Object notation,
                                  Action<? super Dependency> configureAction)

      Declares a dependency on the test fixtures of a component and allows configuring the resulting dependency.
      Parameters:
        `notation` - the coordinates of the component to use test fixtures for
      Since:
        5.6

    - #### variantOf

          @Incubating
          Provider<MinimalExternalModuleDependency> variantOf​(Provider<MinimalExternalModuleDependency> dependencyProvider,
                                                              Action<? super ExternalModuleDependencyVariantSpec> variantSpec)

      Allows fine-tuning what variant to select for the target dependency. This can be used to specify a classifier, for example.
      Parameters:
        `dependencyProvider` - the dependency provider
        `variantSpec` - the variant specification
      Returns:
        a new dependency provider targeting the configured variant
      Since:
        6.8

    - #### variantOf

          @Incubating
          default Provider<MinimalExternalModuleDependency> variantOf​(ProviderConvertible<MinimalExternalModuleDependency> dependencyProviderConvertible,
                                                                      Action<? super ExternalModuleDependencyVariantSpec> variantSpec)

      Allows fine-tuning what variant to select for the target dependency. This can be used to specify a classifier, for example.
      Parameters:
        `dependencyProviderConvertible` - the dependency provider convertible that returns the dependency provider
        `variantSpec` - the variant specification
      Returns:
        a new dependency provider targeting the configured variant
      Since:
        7.3

    - #### platform

          @Incubating
          default Provider<MinimalExternalModuleDependency> platform​(Provider<MinimalExternalModuleDependency> dependencyProvider)

      Configures this dependency provider to select the platform variant of the target component
      Parameters:
        `dependencyProvider` - the dependency provider
      Returns:
        a new dependency provider targeting the platform variant of the component
      Since:
        6.8

    - #### platform

          @Incubating
          default Provider<MinimalExternalModuleDependency> platform​(ProviderConvertible<MinimalExternalModuleDependency> dependencyProviderConvertible)

      Configures this dependency provider to select the platform variant of the target component
      Parameters:
        `dependencyProviderConvertible` - the dependency provider convertible that returns the dependency provider
      Returns:
        a new dependency provider targeting the platform variant of the component
      Since:
        7.3

    - #### enforcedPlatform

          @Incubating
          Provider<MinimalExternalModuleDependency> enforcedPlatform​(Provider<MinimalExternalModuleDependency> dependencyProvider)

      Configures this dependency provider to select the enforced-platform variant of the target component
      Parameters:
        `dependencyProvider` - the dependency provider
      Returns:
        a new dependency provider targeting the enforced-platform variant of the component
      Since:
        7.3

    - #### enforcedPlatform

          @Incubating
          default Provider<MinimalExternalModuleDependency> enforcedPlatform​(ProviderConvertible<MinimalExternalModuleDependency> dependencyProviderConvertible)

      Configures this dependency provider to select the enforced-platform variant of the target component
      Parameters:
        `dependencyProviderConvertible` - the dependency provider convertible that returns the dependency provider
      Returns:
        a new dependency provider targeting the enforced-platform variant of the component
      Since:
        7.3

    - #### testFixtures

          @Incubating
          default Provider<MinimalExternalModuleDependency> testFixtures​(Provider<MinimalExternalModuleDependency> dependencyProvider)

      Configures this dependency provider to select the test fixtures of the target component
      Parameters:
        `dependencyProvider` - the dependency provider
      Returns:
        a new dependency provider targeting the test fixtures of the component
      Since:
        6.8

    - #### testFixtures

          @Incubating
          default Provider<MinimalExternalModuleDependency> testFixtures​(ProviderConvertible<MinimalExternalModuleDependency> dependencyProviderConvertible)

      Configures this dependency provider to select the test fixtures of the target component
      Parameters:
        `dependencyProviderConvertible` - the dependency provider convertible that returns the dependency provider
      Returns:
        a new dependency provider targeting the test fixtures of the component
      Since:
        7.3