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

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.
`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.
`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.
`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.
`void`
`registerTransform(Action<? super VariantTransform> registrationAction)`
Register an artifact transformation.

## Method Details

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

### attributesSchema

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

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

@Incubating void registerTransform(Action<? super VariantTransform> registrationAction)
Register an artifact transformation.

Since:
  3.5
See Also:
  - `ArtifactTransform`