DependencyHandler (Gradle API 2.10)
Date: 2015-12-21

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 dependencyNotation1, dependencyNotation2, ...
       }

  Example shows a basic way of declaring dependencies.

       apply plugin: 'java'
       //so that we can use 'compile', 'testCompile' for dependencies

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

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

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

         //putting all jars from 'libs' onto compile classpath
         compile 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 'compile' dependencies

       dependencies {
         compile('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 'compile' dependencies

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

         //configuring dependency on 'someLib' module
         compile(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 'compile', 'testCompile' for dependencies

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

         //map notation:
         compile 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 'compile', 'testCompile' for dependencies

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

         //putting all jars from 'libs' onto compile classpath
         compile 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 'compile' configuration for declaring dependencies

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

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

         //we will use the Gradle test-kit to test build logic:
         testCompile 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

    Methods
    Modifier and Type | Method and 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` | `components(Action<? super ComponentMetadataHandler> configureAction)` Configures component metadata 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.
    `ComponentMetadataHandler` | `getComponents()` Returns the component metadata 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` | `project(Map<String,?> notation)` Creates a dependency on a project.

- - ### Method Detail

    - #### add

          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

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

    - #### getComponents

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

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

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

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

          @Incubating
          ArtifactResolutionQuery createArtifactResolutionQuery()

      Creates an artifact resolution query.
      Since:
        2.0