saker.build Documentation TaskDoc JavaDoc
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
Gets the current date milliseconds for the build execution.
public ContentDescriptor
Gets the content descriptor of the file that is represented by the given argument path key.
public SakerEnvironment
Gets the environment for the current execution.
public <T> T
Gets the current value of the parameter execution property.
public Map<String, ? extends BuildRepository>
Gets the loaded repositories for this execution.
public ScriptAccessProvider
Gets the loaded script language provider for the specifeid script provider location.
public Path
Gets the mirror directory which was configured for this build execution.
public ExecutionPathConfiguration
Gets the path configuration which was used to start this build execution.
public ExecutionRepositoryConfiguration
Gets the repository configuration which was used to start this build execution.
public ExecutionScriptConfiguration
Gets the script configuration which was used to start this build execution.
public TargetConfiguration
Gets the target configuration for a given file based on the execution configuration.
public Map<String, String>
Gets the arbitrary user parameters used to start this build execution.
public boolean
Gets if the task implementations are recommended to provide configurations for IDE usage.
public boolean
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
Gets the mirror path for the argument execution path.
public SakerPath
Converts a mirror path to execution path.
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.
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.
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.
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.
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.
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.
Gets the mirror directory which was configured for this build execution.
The mirror directory or null if not available.
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.
Gets the repository configuration which was used to start this build execution.
The repository configuration.
Gets the script configuration which was used to start this build execution.
The script configuration.
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.
Gets the arbitrary user parameters used to start this build execution.
An unmodifiable map of user parameters.
Gets if the task implementations are recommended to provide configurations for IDE usage.
true if reporting IDE configurations is recommended.
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.
0.8.7
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.
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.
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.