org.gradle.apiConfigurationContainer Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of gradle-api Show documentation
Gradle 5.5.1 API redistribution.
There is a newer version: 8.6
/*
 * Copyright 2009 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.gradle.api.artifacts;

import groovy.lang.Closure;
import org.gradle.api.Action;
import org.gradle.api.NamedDomainObjectContainer;
import org.gradle.internal.HasInternalProtocol;

/**
 * A {@code ConfigurationContainer} is responsible for declaring and managing configurations. See also {@link Configuration}.
 *
 * You can obtain a {@code ConfigurationContainer} instance by calling {@link org.gradle.api.Project#getConfigurations()},
 * or using the {@code configurations} property in your build script.
 *
 * The configurations in a container are accessible as read-only properties of the container, using the name of the
 * configuration as the property name. For example:
 *
 *  * configurations.create('myConfiguration')
 * configurations.myConfiguration.transitive = false
 * 
 *
 * A dynamic method is added for each configuration which takes a configuration closure. This is equivalent to
 * calling {@link #getByName(String, groovy.lang.Closure)}. For example:
 *
 *  * configurations.create('myConfiguration')
 * configurations.myConfiguration {
 *     transitive = false
 * }
 * 
 *
 * Examples
 *
 * An example showing how to refer to a given configuration by name
 * in order to get hold of all dependencies (e.g. jars, but only)
 *  *   apply plugin: 'java' //so that I can use 'implementation', 'compileClasspath' configuration
 *
 *   dependencies {
 *       implementation 'org.slf4j:slf4j-api:1.7.26'
 *   }
 *
 *   //copying all dependencies attached to 'compileClasspath' into a specific folder
 *   task copyAllDependencies(type: Copy) {
 *     //referring to the 'compileClasspath' configuration
 *     from configurations.compileClasspath
 *     into 'allLibs'
 *   }
 * 
 *
 * An example showing how to declare and configure configurations
 *  * apply plugin: 'java' //so that I can use 'implementation', 'testImplementation' configurations
 *
 * configurations {
 *   //adding a configuration:
 *   myConfiguration
 *
 *   //adding a configuration that extends existing configuration:
 *   //(testImplementation was added by the java plugin)
 *   myIntegrationTestsCompile.extendsFrom(testImplementation)
 *
 *   //configuring existing configurations not to put transitive dependencies on the compile classpath
 *   //this way you can avoid issues with implicit dependencies to transitive libraries
 *   compileClasspath.transitive = false
 *   testCompileClasspath.transitive = false
 * }
 * 
 *
 * Examples on configuring the resolution strategy - see docs for {@link ResolutionStrategy}
 *
 * Please see the Managing Dependency Configurations User Manual chapter for more information.
 */
@HasInternalProtocol
public interface ConfigurationContainer extends NamedDomainObjectContainer {
    /**
     * {@inheritDoc}
     */
    Configuration getByName(String name) throws UnknownConfigurationException;

    /**
     * {@inheritDoc}
     */
    Configuration getAt(String name) throws UnknownConfigurationException;

    /**
     * {@inheritDoc}
     */
    Configuration getByName(String name, Closure configureClosure) throws UnknownConfigurationException;

    /**
     * {@inheritDoc}
     */
    @Override
    Configuration getByName(String name, Action configureAction) throws UnknownConfigurationException;

    /**
     * Creates a configuration, but does not add it to this container.
     *
     * @param dependencies The dependencies of the configuration.
     * @return The configuration.
     */
    Configuration detachedConfiguration(Dependency... dependencies);
}