Package org.gradle.api.artifacts.dsl

## Interface DependencyHandler

-     public interface DependencyHandler

  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.

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

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

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

  ### 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`.

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

  The notation `project(':projectA')` 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: ':projectA', configuration: 'someOtherConfiguration')`

  Project dependencies are represented using a `ProjectDependency`.

  ### File dependencies

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

  `configurationName files('a file')`

       apply plugin: '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
       apply plugin: '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
    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.
    `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.
    `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.
    `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 without a parameter object.
    `void` | `registerTransform​(Action<? super VariantTransform> registrationAction)` | Registers an artifact transform.

- - ### 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.

    - #### 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

          @Incubating
          DependencyConstraintHandler getConstraints()

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

    - #### constraints

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

          @Incubating
          ArtifactTypeContainer getArtifactTypes()

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

    - #### artifactTypes

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

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

    - #### registerTransform

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

      Registers an artifact transform.
      Since:
        3.5
      See Also:
        `ArtifactTransform`

    - #### registerTransform

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

      Registers an artifact transform without a parameter object.
      Since:
        5.3
      See Also:
        `TransformAction`

    - #### platform

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

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

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

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