SakerEnvironment

public interface SakerEnvironment

Core environment for the build system.

Tasks can access features of the build system which outlive the time of a build execution.

The environment provides features for querying properties, caching data between executions, and is parameterizable using user parameters.

The lifetime of the environment outlives the build executions.

The environmenmt always resides on the machine which is used to execute the task. This is important to keep in mind when designing tasks for remote execution.

Methods

public <DataType> DataType	getCachedData(CacheKey<DataType, ?> key) Gets a cached data from the environment.
public ClassPathLoadManager	getClassPathManager() Gets the object which is used to manage the classpath loading for the build environment.
public UUID	getEnvironmentIdentifier() Gets the unique identifier of this environment.
public Path	getEnvironmentJarPath() Gets the path to the JAR which was used to load the build system related classes.
public <T> T	getEnvironmentPropertyCurrentValue(EnvironmentProperty<T> environmentproperty) Gets the current value of an environment property.
public ThreadGroup	getEnvironmentThreadGroup() Gets the base thread group for the environment.
public Map<String, String>	getUserParameters() Gets the user parameters which were used to instantiate this environment.

public abstract <DataType> DataType getCachedData(CacheKey<DataType, ?> key) throws Exception

Gets a cached data from the environment.

The build system manages a cache for the keys. Each key uniquely identifies a cache entry, and it is used to calculate the cached data. The cache stores objects in a resource-data pair, which is used for proper deallocation of the resources. More information in the documentation of CacheKey.

DataTypeThe type of the data the cache key generates.

keyThe cache key to identify and compute the data.

The computed cached data.

ExceptionAny exception thrown during the allocation of the data.

public abstract ClassPathLoadManager getClassPathManager()

Gets the object which is used to manage the classpath loading for the build environment.

Clients should only use this when caching data via getCachedData(CacheKey<DataType, ?>), or make sure that clients always unload the loaded class path. (The manager uses garbage collection for loaded classpaths, but it is non-deterministic, and should not be relied upon.)

The classpath loading manager.

public abstract UUID getEnvironmentIdentifier() throws UnsupportedOperationException

Gets the unique identifier of this environment.

Each environment that exists have an unique UUID identifier. They are automatically generated when the environment is constructed. Callers should not rely on these identifiers being the same between two build executions. The identifiers may change between different invocations of a build.

The identifier can be used in some build system features to uniquely identify environments to run operations on.

This method may throw UnsupportedOperationException when it is called in an inappropriate time. Currently the only one is when the suitability of an environment is being determined by tasks to execute on. See TaskExecutionEnvironmentSelector for more information.

The unique identifier of this environment.

UnsupportedOperationExceptionIf the method is being called in an inappropriate time.

public abstract Path getEnvironmentJarPath()

Gets the path to the JAR which was used to load the build system related classes.

For example this JAR can be used to start external processes which require the build system classes on their classpath.

The path to the JAR for the build system.

public abstract <T> T getEnvironmentPropertyCurrentValue(EnvironmentProperty<T> environmentproperty) throws NullPointerException, PropertyComputationFailedException

Gets the current value of an environment property.

Environment properties are cached and only calculated once for each property that equals.

Any exception thrown during property calculation is relayed to the caller.

TThe type of the returned property.

environmentpropertyThe property.

The current value of the property.

NullPointerExceptionIf the property is null.

PropertyComputationFailedExceptionIf the argument property throws an exception during the computation of its value. The thrown exception is available through the cause.

public abstract ThreadGroup getEnvironmentThreadGroup()

Gets the base thread group for the environment.

Callers can use this threadgroup to start threads which outlives the lifetime of an execution. They should not start threads arbitrarily, but only when they are caching data via getCachedData(CacheKey<DataType, ?>).

If tasks need to start threads for cached data, they are required to start these on the environment thread group. If they don't, then an exception will be thrown when the corresponding build execution finishes. The build environment may call ThreadGroup.destroy() on the build execution thread group to ensure that task executions do not leak threads. If any alive threads remain in the build execution thread group, the build may be considered failed.

This thread group will be destroyed when the build environment is closed.

The base thread group.

public abstract Map<String, String> getUserParameters()

Gets the user parameters which were used to instantiate this environment.

This is not the same user parameters used during build execution.

The map contains arbitrarily specified key-value pairs by the user. Values may be null.

An unmodifiable map of user parameters.