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

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)	Deprecated. use registerTransform(Class, Action) instead.

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

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

Deprecated.

use registerTransform(Class, Action) instead.

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