Overview | Package | Class | Deprecated | Index | Help
| Groovy Documentation
| FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | METHOD | DETAIL: FIELD | METHOD

## org.gradle.api.artifacts.dsl
[Java] 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.
- 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.

     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 {
           name = 'someArtifact' //artifact name different than module name
           type = 'jar'
           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 2 notations supported for declaring a dependency on an external module. One is a String notation formatted this way: group:name:version

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

The other is a map notation:

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

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 'groovy' and 'compile' configuration for declaring dependencies

     dependencies {
       //we will use groovy that ships with Gradle:
       groovy localGroovy()

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

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

Authors:
  Hans Dockter

Method Summary
`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.
`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.
`Dependency` | `gradleApi()` Creates a dependency on the API of the current version of Gradle.
`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.
`Dependency` | `project(Map notation)` Creates a dependency on a project.

Method Detail

### add

    public 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

    public 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

    public 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

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

### gradleApi

    public Dependency gradleApi()

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

### localGroovy

    public Dependency localGroovy()

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

### module

    public 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

    public 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

    public Dependency project(Map notation)

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

Gradle API 1.1-rc-1