ExecutionContext

package saker.build.runtime.execution

public interface ExecutionContext extends ExecutionDirectoryContext, ExecutionDirectoryPathContext

saker.build.runtime.execution.ExecutionContext

saker.build.runtime.execution.ExecutionDirectoryContext

saker.build.runtime.execution.ExecutionDirectoryPathContext

Provides access to executional services provided by the build runtime.

Execution context is to be considered as a parent of TaskContext, it is created for each build execution.

The execution context provides the following functionalities:

Accessing the build configuration
Managing script target configurations
Evaluating execution properties
Providing access to loaded repositories
Root directory management
Execution-wide related features (e.g. appropriate caching)
Other executional services which have a longer lifetime than task execution, but do not necessarily outlive execution lifetime

The execution context is used to retrieve target configurations for build scripts. It does appropriate caching to ensure validity during the execution. See getTargetConfiguration(TaskContext, SakerFile) for more information.

Execution properties can be evaluated using the execution context, which will be cached during the lifetime of the execution.

The execution context holds references to the loaded build repositores for this execution. They are mapped to their String identifiers specified by user configuration. See getLoadedRepositories().

The execution context provides access to the root directories of the in-memory file hierarchy. They should be used tasks to handle file in- and output. The root directories are determined based on the user provided path configuration. See ExecutionDirectoryContext.getRootDirectories().

Clients should not implement this interface.

Methods

public long	getBuildTimeMillis() Gets the current date milliseconds for the build execution.
public ContentDescriptor	getContentDescriptor(ProviderHolderPathKey pathkey) Gets the content descriptor of the file that is represented by the given argument path key.
public SakerEnvironment	getEnvironment() Gets the environment for the current execution.
public <T> T	getExecutionPropertyCurrentValue(ExecutionProperty<T> executionproperty) Gets the current value of the parameter execution property.
public Map<String, ? extends BuildRepository>	getLoadedRepositories() Gets the loaded repositories for this execution.
public ScriptAccessProvider	getLoadedScriptAccessProvider(ScriptProviderLocation location) Gets the loaded script language provider for the specifeid script provider location.
public default SakerFileProvider	getLocalFileProvider() Gets the local file provider of the build execution.
public Path	getMirrorDirectory() Gets the mirror directory which was configured for this build execution.
public ExecutionPathConfiguration	getPathConfiguration() Gets the path configuration which was used to start this build execution.
public ExecutionRepositoryConfiguration	getRepositoryConfiguration() Gets the repository configuration which was used to start this build execution.
public ExecutionScriptConfiguration	getScriptConfiguration() Gets the script configuration which was used to start this build execution.
public TargetConfiguration	getTargetConfiguration(TaskContext taskcontext, SakerFile file) Gets the target configuration for a given file based on the execution configuration.
public Map<String, String>	getUserParameters() Gets the arbitrary user parameters used to start this build execution.
public boolean	isIDEConfigurationRequired() Gets if the task implementations are recommended to provide configurations for IDE usage.
public boolean	isRecordsBuildTrace() Gets if the current build execution records a build trace.
public EnvironmentSelectionResult	testEnvironmentSelection(TaskExecutionEnvironmentSelector environmentselector, Set<UUID> allowedenvironmentids) Tests the environment selection of a given selector the same way it is determined by the build system during execution.
public Path	toMirrorPath(SakerPath path) Gets the mirror path for the argument execution path.
public SakerPath	toUnmirrorPath(Path path) Converts a mirror path to execution path.

Inherited methods
From: ExecutionDirectoryContext getExecutionBuildDirectory, getExecutionWorkingDirectory, getRootDirectories, getRootDirectoryNames
From: ExecutionDirectoryPathContext getExecutionBuildDirectoryPath, getExecutionWorkingDirectoryPath

@RMICacheResult

public abstract long getBuildTimeMillis()

Gets the current date milliseconds for the build execution.

The representation is the same as System.currentTimeMillis().

The date milliseconds of the execution.

@RMISerialize

public abstract ContentDescriptor getContentDescriptor(ProviderHolderPathKey pathkey) throws NullPointerException

Gets the content descriptor of the file that is represented by the given argument path key.

The current content descriptor is retrieved that is tracked by the build system for the given file. The in-memory file hierarchy doesn't affect the content descriptor returned by this method.

This method can be used to retrieve content descriptors for files which are not part of the build execution. I.e. are not accessible via the execution path roots.

Usually, the returned descriptor will be constructed based on the database configuration. (Attribute, hash based descriptors, etc...) If a file synchronization already took place for the given file, then the synchronized content descriptor is returned, if the file hasn't been modified since.

pathkeyThe path key for the file.

The content descriptor for the file or null if the file doesn't exist.

NullPointerExceptionIf the argument is null.

@RMIForbidden

public abstract SakerEnvironment getEnvironment()

Gets the environment for the current execution.

For remote execution: The environment is always on the same machine as the currently running task, meaning that the build environment will be replicated for every PC that is used as a cluster.

The environment.

@RMISerialize

public abstract <T> T getExecutionPropertyCurrentValue(@RMISerializeExecutionProperty<T> executionproperty) throws NullPointerException, PropertyComputationFailedException

Gets the current value of the parameter execution property.

The properties are cached during the lifetime of the execution.

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

TaskContext.reportExecutionDependency(ExecutionProperty<T>, T)

@RMIForbidden

public abstract Map<String, ? extends BuildRepository> getLoadedRepositories()

Gets the loaded repositories for this execution.

The repositories are mapped to their identifiers specified by the user. If an identifier was not set by the user, an automatically generated one is used.

An unmodifiable map of the loaded repositories for this execution.

@RMIForbidden

public abstract ScriptAccessProvider getLoadedScriptAccessProvider(ScriptProviderLocation location)

Gets the loaded script language provider for the specifeid script provider location.

The script language providers are loaded based on the execution script configuration and the providers are accessible based on the script load location.

The location can be queried from the current script configuration (getScriptConfiguration()) and the location can be retrieved from ExecutionScriptConfiguration.getScriptOptionsConfig(SakerPath).getProviderLocation().

Make sure callers report an appropriate execution property dependency when handling script providers. It is recommended that they use ScriptParsingConfigurationExecutionProperty for retrieving the requested resources.

locationThe script provider location to get the loaded provider for.

The script language provider or null if no language provider was loaded for the given location.

@RMICacheResult

public default SakerFileProvider getLocalFileProvider()

Gets the local file provider of the build execution.

The method returns the file provider for the build execution machine. That is the one that coordinates the build and runs it.

This method can be useful when remote dispatchable tasks want to reference files on the local build machine.

The local file provider.

saker.build 0.8.12

@RMIForbidden

public abstract Path getMirrorDirectory()

Gets the mirror directory which was configured for this build execution.

The mirror directory or null if not available.

@RMICacheResult

public abstract ExecutionPathConfiguration getPathConfiguration()

Gets the path configuration which was used to start this build execution.

Tasks are not recommended to interact with the result of this function, but handle its in- and outputs using the in-memory file hierarchy. See ExecutionDirectoryContext and TaskDirectoryContext.

The path configuration.

ExecutionDirectoryContext.getRootDirectories()

TaskDirectoryContext.getTaskWorkingDirectory()

@RMICacheResult

public abstract ExecutionRepositoryConfiguration getRepositoryConfiguration()

Gets the repository configuration which was used to start this build execution.

The repository configuration.

@RMICacheResult

public abstract ExecutionScriptConfiguration getScriptConfiguration()

Gets the script configuration which was used to start this build execution.

The script configuration.

@RMISerialize

public abstract TargetConfiguration getTargetConfiguration(TaskContext taskcontext, SakerFile file) throws IOException, ScriptParsingFailedException, NullPointerException, MissingConfigurationException, InvalidPathFormatException

Gets the target configuration for a given file based on the execution configuration.

This method can be used to retrieve a build target configuration for a given build script file.

When the target configuration is constructed, the current script configuration will be taken into account.

The target configurations are cached during an execution, which means that retrieving the target configuration for files that bear the same path will result in the same configurations returned, even if the files have changed during the two queries. This caching ensures that invoking a target from a given script at a path will run the same build steps even if the build files were changed meanwhile. This is required due to the fact that task execution is highly concurrent and ordering of tasks should not have an effect of executed build targets.

This method will report an execution dependency at the file path for the used script options. If the script configuration for the execution changes, expect a rerun for the task with a DeltaType.EXECUTION_PROPERTY_CHANGED delta with the property class of ScriptParsingConfigurationExecutionProperty .
The method will not report an input dependency on the file.

taskcontextThe task context of the querying task.

fileThe file to get the target configuration for.

The parsed target configuration,

IOExceptionIn case of I/O error.

ScriptParsingFailedExceptionIf the parsing of the file failed.

NullPointerExceptionIf any of the parameters are null.

MissingConfigurationExceptionIf there is no corresponding script configuration for the file.

InvalidPathFormatExceptionIf the path of the file is relative.

ExecutionScriptConfiguration

@RMICacheResult

@RMIWrap(RMITreeMapWrapper.class)

public abstract Map<String, String> getUserParameters()

Gets the arbitrary user parameters used to start this build execution.

An unmodifiable map of user parameters.

@RMICacheResult

public abstract boolean isIDEConfigurationRequired()

Gets if the task implementations are recommended to provide configurations for IDE usage.

true if reporting IDE configurations is recommended.

IDEConfiguration

TaskContext.reportIDEConfiguration(IDEConfiguration)

IDEConfigurationRequiredExecutionProperty

@RMICacheResult

public abstract boolean isRecordsBuildTrace()

Gets if the current build execution records a build trace.

A build trace is a recording of various aspects of the build execution to be displayed later for the user.

true if a build trace is being recorded.

BuildTrace

saker.build 0.8.7

@RMISerialize

public abstract EnvironmentSelectionResult testEnvironmentSelection(@RMISerializeTaskExecutionEnvironmentSelector environmentselector, @RMIWrap(RMITreeSetSerializeElementWrapper.class)Set<UUID> allowedenvironmentids) throws NullPointerException, TaskEnvironmentSelectionFailedException

Tests the environment selection of a given selector the same way it is determined by the build system during execution.

This method can be used to test if a given task can be invoked with the given selector. In general, task implementations don't need to used this, however, there might be cases when it is appropriate and necessary to support incremental compilation.

One such scenario is when a task depends on the presence of an SDK installed on an executor machine. In this case, if the SDK gets removed or modified, the build system needs to trigger a reinvocation. In order to achieve this, the task implementation will need to install a dependency on an appropriate ExecutionProperty that determines if a given task can still run in the current build configuration. While this may not be necessary if the interested SDK is present on the coordinator machine, it can be crucial to support proper incremental compilation with build clusters in use.

environmentselectorThe task environment selector to test.

allowedenvironmentidsThe allowed environment identifiers for the selection. See InnerTaskExecutionParameters.getAllowedClusterEnvironmentIdentifiers(). null is accepted.

The result of environment selection as returned by the TaskExecutionEnvironmentSelector.

NullPointerExceptionIf the environment selector is null.

TaskEnvironmentSelectionFailedExceptionIf the environment selection fails.

@RMIForbidden

public abstract Path toMirrorPath(SakerPath path) throws IllegalArgumentException, NullPointerException, FileMirroringUnavailableException

Gets the mirror path for the argument execution path.

This method converts the parameter path to the same path that would be the result of the actual mirroring.

pathThe path to get the mirror path for.

The mirrored path.

IllegalArgumentExceptionIf the path is not absolute or is not a valid path for the current execution.

NullPointerExceptionIf path is null.

FileMirroringUnavailableExceptionIf file mirroring is not available for this path.

toUnmirrorPath(Path)

@RMIForbidden

public abstract SakerPath toUnmirrorPath(Path path) throws InvalidPathFormatException

Converts a mirror path to execution path.

This is the inverse conversion of toMirrorPath(SakerPath). The parameter file system path will be converted to the corresponding execution path.

pathThe path to convert to execution path.

The converted path or null if the argument path has no corresponding execution path. This is usually happens when the argument is not a subpath of getMirrorDirectory(), or file mirroring is not available.

InvalidPathFormatExceptionIf path is not absolute.