org.gradle.api.provider.ValueSource Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of gradle-api Show documentation
Gradle 6.9.1 API redistribution.
There is a newer version: 8.11.1
/*
 * Copyright 2019 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.provider;

import org.gradle.api.Action;
import org.gradle.api.file.RegularFile;

import javax.annotation.Nullable;
import javax.inject.Inject;

/**
 * Represents an external source of information used by a Gradle build.
 *
 * Examples of external sources include client environment variables,
 * system properties, configuration files, shell commands, network services,
 * among others.
 *
 * 
 * Representing external sources as {@link ValueSource}s allows Gradle to transparently manage
 * the configuration cache
 * as values obtained from those sources change.
 * For example, a build might run a different set of tasks depending on whether the {@code CI}
 * environment variable is set or not.
 * 
 *
 * 
 * To integrate a new type of value source, create an abstract subclass of this interface
 * and use {@link ProviderFactory#of(Class, Action)} to get a provider to a configured source.
 * The returned {@link org.gradle.api.provider.Provider} can be passed to tasks or queried
 * by build logic during the configuration phase. In the latter case, the source would be automatically
 * considered as an input to the work graph cache.
 * 
 * 
 * It is possible to have some Gradle services to be injected
 * into the implementation, similar to tasks and plugins.
 * It can be done by adding a parameter to the constructor and annotating the
 * constructor with the {@code @Inject} annotation:
 * 
 * public abstract class MyValueSource implements ValueSource<String, ValueSourceParameters.None> {
 *     private final ExecOperations execOperations;
 *
 *     {@literal @}Inject
 *     public MyValueSource(ExecOperations execOperations) {
 *         this.execOperations = execOperations;
 *     }
 *
 *     // ...
 * }
 * 
 * Currently, only a small subset of services is supported:
 * 
 *     {@link org.gradle.process.ExecOperations} provides means to execute external processes.
 *     It is possible to use this service even at configuration time. However, as the
 *     returned value is used to check the configuration cache, the {@link #obtain()} method will
 *     be called during each build. Calling slow commands here will slow things down.
 * 
 *
 * 
 * A value source implementation will most likely take parameters. To do this create a
 * subtype of {@link ValueSourceParameters} and declare this type as the type parameter
 * to the value source implementation.
 * 
 *
 * 
 * A value source implementation doesn't have to be thread-safe, as the single call
 * to {@link #obtain()} is synchronized.
 * 
 *
 * 
 * A value source implementation is exempt from the automatic detection of work graph cache inputs.
 * For example, if the {@link #obtain()} method calls {@code System.getenv("FOO")} then changes to
 * the {@code FOO} environment variable only invalidate the cache if the value returned by the
 * {@code obtain()} method itself changes. The same applies to reading files or system properties.
 * Starting an external process with a standard API (for example, {@code java.lang.ProcessBuilder}) is
 * also allowed.
 * 
 *
 * Implementations of ValueSource are subject to the following constraint:
 * 
 *     Do not implement {@link #getParameters()} in your class, the method will be implemented by Gradle.
 * 
 *
 * @param  The type of value obtained from this source.
 * @param  The source specific parameter type.
 * @see ProviderFactory#environmentVariable(String)
 * @see ProviderFactory#systemProperty(String)
 * @see ProviderFactory#fileContents(RegularFile)
 * @see ProviderFactory#of(Class, Action)
 * @see Configuration Cache
 * @since 6.1
 */
public interface ValueSource {

    /**
     * The object provided by {@link ValueSourceSpec#getParameters()} when creating a provider from the value source.
     *
     * 

     * Do not implement this method in your subclass.
     * Gradle provides the implementation when creating a provider from the value source via {@link ProviderFactory#of(Class, Action)}.
     * 
     */
    @Inject
    P getParameters();

    /**
     * Obtains the value from the source. The returned value must be effectively immutable.
     * The implementation is exempt from the automatic detection of work graph cache inputs.
     *
     * This method must be implemented in the subclass.
     * This method is only called if the provider value is requested and only once in that case.
     *
     * @return the value obtained or {@code null} if the value is not present.
     */
    @Nullable
    T obtain();
}