Calling this function will set a pending cause exception for the task result. Tasks which retrieve the result of this task will receive this exception.

The execution of this task will continue, and the task may still return an object from the Task.run(TaskContext) method. This task result will not be visible to other tasks, but this task can still retrieve it using TaskContext.getPreviousTaskOutput(Class<T>) when it is run next time.

For inner tasks, calling this function will return this exception via the InnerTaskResultHolder.getExceptionIfAny(), and the inner task may also return an object as a result, which is available via InnerTaskResultHolder.getResult().

Aborting excecution using this functions is preferable to throwing an exception directly when the task is able to handle previously thrown exceptions in the next run.

If the task uses this function to abort, then any results produced by the current run will be visible in the next one. The base for delta calculation will be the current run instead of the last previously successfully finished run.

It is useful to use this function when the task actually finishes its calculations successfully, but it is required to abort due to a semantic build error.

This method may be called multiple times. The first exception that is used to call this method will be the cause of the task execution exception, and any further exceptions will be added as suppressed exceptions.

Acquiring the lock will prevent any access to the standard I/O streams of the execution by other tasks. This means that the locker will have exclusive access to the input and output of the execution. Any output that is produced by concurrent tasks will be written out when this task releases the lock.

The lock is task execution based and not thread based. This means that the lock can be acquired on one thread and can be released on an other thread. Trying to acquire the lock multiple times will result in an exception.

It is recommended to acquire this lock when the task wants to display information that is necessary to be grouped together. Without locking, the lines printed to the output streams might be interlaced with the output of concurrent tasks.

It is required to acquire the lock to access the standard input. If the task wants to read input from the standard input stream and the lock is not acquired, then an exception will be thrown. This is to prevent misalignment of typed data from the user by concurrent output writing, and due to the fact that the standard input is one single shared stream of input for all concurrent tasks.

This method works the same way as SakerDirectory.add(SakerFile), but returns a reference to the argument file. It is mostly useful when designing tasks for remote execution, as the files need to be transferred to the coordinator machine, therefore the actually added file to the directory might be different than the file passed as parameter. See SakerDirectory.add(SakerFile) documentation for more info.

This method can be called from both remote and non-remote executed tasks.

This method works the same way as SakerDirectory.addIfAbsent(SakerFile), but returns the reference to the argument file. It is mostly useful when designing tasks for remote execution, as the files need to be transferred to the coordinator machine, therefore the actually added file to the directory might be different than the file passed as parameter. See SakerDirectory.addIfAbsent(SakerFile) documentation for more info.

This method can be called from both remote and non-remote executed tasks.

This method works the same way as SakerDirectory.addOverwriteIfNotDirectory(SakerFile), but returns the reference to the argument file. It is mostly useful when designing tasks for remote execution, as the files need to be transferred to the coordinator machine, therefore the actually added file to the directory might be different than the file passed as parameter. See SakerDirectory.addOverwriteIfNotDirectory(SakerFile) documentation for more info.

This method can be called from both remote and non-remote executed tasks.

This method can be used to perform multiple operations in a single call. The method will invalidate the contents at the given path key and create a provider path file for the given path key. The created SakerFile is the added to the argument directory, and then syncronized.

Calling this method can be useful to batch the above operations in a single call. It is usually useful when you invoke an external process that produces a result file and want to add it to the build system file hierarchy.

This method doesn't report the argument as dependency.

Important: Calling this method will trigger the computation of file deltas as it uses TaskContext.getPreviousFileAdditionDependency(FileCollectionStrategy) to avoid redundant computations.

This method is the same as:

 collectionstrategy.collectFiles(taskcontext);
 

When designing tasks for remote execution, it is recommended to call this method instead invoking FileCollectionStrategy.collectFiles(ExecutionDirectoryContext, TaskDirectoryContext) directly.

For correct incremental operation tasks should not forget to report the dependencies as well. Consider calling TaskExecutionUtilities.collectFilesReportInputFileAndAdditionDependency(Object, FileCollectionStrategy) instead of this function.

This method collects the files for all the addition dependencies, and aggregates them into a single result map.

This method doesn't report input file dependency to the collected files.

Important: Calling this method will trigger the computation of file deltas as it uses TaskContext.getPreviousFileAdditionDependency(FileCollectionStrategy) to avoid redundant computations.

This method collects the files for all the addition dependencies, and aggregates them into a single result map.

This method collects the files for the specified addition dependency, reports the addition dependency, and reports the input dependencies for the collected files with their respective content descriptors.

Important: Calling this method will trigger the computation of file deltas as it uses TaskContext.getPreviousFileAdditionDependency(FileCollectionStrategy) to avoid redundant computations.

The execution context will ensure that a given data for a file and a computer is only computed once during an execution.

The computed datas will be cached during the execution. The cache uses the content descriptor, path of the file, and the computer as a key to the cached datas. Files which are not attached to any parents will not have their computed datas cached.

Multiple concurrent computation can run for a given file, but only one computation will run at the same time for file data computers that equal.

This method can be used to include files from a given file system in the build. The resulting file needs to be added to a SakerDirectory to be included in the in-memory hierarchy.

If the file at the given path is a directory, a SakerDirectory instance will be returned that contains all the files which are present in the given directory. (The directory may be lazily populated.)

Note that we recommend using TaskExecutionUtilities.createProviderPathFile(String, ProviderHolderPathKey, ContentDescriptor) when when creating SakerFiles for externally modified files. You should specify your own content descriptor for the modified file as in case where the file modification times are used to detect file changes, some changes may be unnoticed on file systems that have larger granularity. (E.g. if the file modification times are stored as seconds.)

The file represented with the given path must be a file, not a directory.

The argument content descriptor will be associated with the current contents of the file system at the given path. This means that unless some other agent modifies the contents at the given path, calling SakerFile.getContentDescriptor() will return the passed argument for the returned file.

This method can be used to include files from a given file system in the build. The resulting file needs to be added to a SakerDirectory to be included in the in-memory hierarchy.

The name of the file is the same as the name of the argument path.

This method is the same as:

 createProviderPathFile(pathkey.getPath().getFileName(), pathkey)
 

The method works the same way as TaskExecutionUtilities.createProviderPathFile(String, ProviderHolderPathKey, ContentDescriptor), but also associated the specified posix file permissions with the file.

The result file will return the argument posix file permissions from its SakerFile.getPosixFilePermissions() method.

It is not required for the underlying filesystem to support posix file permissions.

Note that the argument content descriptor should reflect the specified posix file permissions as well. It is recommended to use PosixFilePermissionsDelegateContentDescriptor.

Calling this method might implicitly synchronize the file to its real location, or to some other cache location when remote execution is used.

The resulting map is mapped by the file names of the children.

Calling this method might implicitly synchronize the file to its real location, or to some other cache location when remote execution is used.

The returned container will include all file deltas regardless of DeltaType.

Important: Calling this method will trigger the computation of file deltas. Any input dependency tasks should be waited for before calling this method. By waiting for tasks after file delta computation, you risk the file deltas being incorrectly reported which can result in incorrect incremental builds. See TaskContext documentation for more info.

The resulting container will only include deltas which type matches the given parameter.

If the parameter is not a file change related DeltaType then an empty container will be returned.

Important: Calling this method will trigger the computation of file deltas. Any input dependency tasks should be waited for before calling this method. By waiting for tasks after file delta computation, you risk the file deltas being incorrectly reported which can result in incorrect incremental builds. See TaskContext documentation for more info.

The resulting map will have the same entries as if the dependency was used to collect the files themselves. The resulting map was used to compute the deltas for the task.

Calling this method instead of collecting the files manually can result in performance increase as it can avoid duplicate computations.

If the file addition dependency was not reported in the previous run, null will be returned.

Important: Calling this method will trigger the computation of file deltas. Any input dependency tasks should be waited for before calling this method. By waiting for tasks after file delta computation, you risk the file deltas being incorrectly reported which can result in incorrect incremental builds. See TaskContext documentation for more info.

The resulting map will have one entry for every input file reported previously. The resulting map contains the files which were used to compute deltas for the task.

It is recommended to get the files using this method if there are no deltas for the given tag, as it can avoid unnecessary computations by the task.

Important: Calling this method will trigger the computation of file deltas. Any input dependency tasks should be waited for before calling this method. By waiting for tasks after file delta computation, you risk the file deltas being incorrectly reported which can result in incorrect incremental builds. See TaskContext documentation for more info.

The resulting map will have one entry for every output file reported previously. The resulting map contains the files which were used to compute deltas for the task.

Important: Calling this method will trigger the computation of file deltas. Any input dependency tasks should be waited for before calling this method. By waiting for tasks after file delta computation, you risk the file deltas being incorrectly reported which can result in incorrect incremental builds. See TaskContext documentation for more info.

The progress monitor can be used to check if the execution has been cancelled externally.

The returned reader can be used to prompt the user to enter data in a secret way. This usually means that the characters the user enters will not be directly displayed on the computer screen, but will be hidden. (E.g. the console doesn't echo back the characters, or using a password text box.)

Reading functions on the returned result may lock the standard IO lock before reading the secret input, but may not based on the implementation.

Callers must handle the case if the secret reader is not available. This usually means that the build execution was configured in a way that direct input reading is not possible. (E.g. during a CI (continuous integration) build.)

The standard error is private to the currently executed task. It is buffered, but unlike the standard out, will not be flushed during the execution of the task, only after it has finished. It will be flushed as a block of bytes and will not be interlaced with concurrently executing tasks.

The display identifier is not prepended to the lines of this output. The contents written to standard err will not be replayed when the task is not rerun due to no deltas.

The returned sink is not thread-safe, the caller must ensure proper synchronization, otherwise bytes written to the sink may be lost, or scrambled.

The standard input is shared by all concurrently running tasks in the same build environment. The current task must lock on the standard I/O lock via TaskContext.acquireStandardIOLock() before calling any reading functions on the returned stream. Not locking will result in a TaskStandardIOLockIllegalStateException when calling reading functions.

The standard input and output can be both used when the lock is acquired to provide an interactive interface to the user.

The standard output is private to the currently executed task. It is buffered, and is flushed when the execution sees it as a best opportunity. The buffering occurs on a per-line basis, no partially finished lines will be printed, unless the execution-wide standard I/O lock is acquired.

The bytes written to this stream is examined and every line is prepended with the currently set display identifier. (See TaskContext.setStandardOutDisplayIdentifier(String))

The bytes written to this stream is not replayed to the user if the task is not rerun due to no deltas. To print information which are replayed use TaskContext.println(String).

When buffered lines are flushed from this stream they might be interlaced with output lines of concurrently executing tasks. They might be interlaced, but they will not be mangled.

The build directory is based on the execution-wide base build directory and the task execution parameters specified for the task.

It is strongly recommended that unless explicitly specified by the user, all tasks produce outputs under the directory returned by this method.

To avoid checking null result of this method consider using SakerPathFiles.requireBuildDirectory(TaskDirectoryContext) which throws an appropriate exception if it is not available.

The returned path is the absolute execution path to the build directory of the task. This is affected by the task execution parameters. The result may be null, if there's no build directory configured for the task or build execution.

The path is the same as TaskDirectoryContext.getTaskBuildDirectory().getSakerPath() would return.

The task is not required to be started, or exist in the build runtime as of the calling of this function. Futures can be obtained to not yet started tasks as well.

Same as:

 getTaskFuture(taskid).getAsDependencyFuture();
 

The task is not required to be started, or exist in the build runtime as of the calling of this function. Futures can be obtained to not yet started tasks as well.

This method waits for the specified task if needed, and works the same way as TaskFuture.get().

If this method throws a TaskExecutionFailedException, it is considered to be a valid return scenario. A dependency on the the associated task will be installed as if a return value was returned.

Callers should handle the possiblity of tasks returning StructuredTaskResult instances.

The retrieval of the handle is implementation dependent. The TaskResultDependencyHandle.get() method may return structured task results.

The utility instance provides bulk operations, utility functions, and extensions for working with task context.

Usage of this is especially recommended when designing remote executable tasks.

The task utilities exist for the purpose of keeping the TaskContext interface clean and functions which could bloat the interface are implemented in the utilities instance.

The working directory is based on the execution-wide base working directory and the task execution parameters specified for the task.

Any relative paths used by this task should be resolved against this directory.

Note: In some cases this method may return null. This might be for example when the build system is detecting the deltas for a given task, and the working directory path did not resolve to an actual path. Callers in FileCollectionStrategy.collectFiles(ExecutionDirectoryContext, TaskDirectoryContext) should handle the possibility of this method returning null. If this method is called during task execution (I.e. inside Task.run(TaskContext), then this method will never return null.)

The returned path is the absolute execution path to the working directory of the task. This is affected by the task execution parameters.

The path is the same as TaskDirectoryContext.getTaskWorkingDirectory().getSakerPath() would return.

It can be used to resolve relative user arguments against it without actually querying the SakerDirectory instance.

This method needs to be called when tasks decides to externally modify files which are referenced by the build system.
External modifications include:

• Modifying a file using an external process. (E.g. spawning an external compiler process)
• Using direct Java I/O APIs to modify files. E.g. File, Path and related classes.
• Directly modifying files using file providers.
• Other file modifications that aren't done through the SakerFile API.

If task implementations forget to call this method, the synchronization of the files might not work as expected. Synchronizations might be skipped, while the file contents won't be the same as expected.

Generally if task implementations do not overwrite files multiple times, and keep intermediate files separate, they don't need to expect failures. Tasks should aim to mainly use the SakerFile API or if they really need to, only work with the local file system.

If task implementations only use SakerFile.synchronize() and related functions, they don't need to call this.

Calling this method will not modify the SakerFile in-memory hierarchy in any way.

Internal implementation note: This function invalidates the specified handle for the content database. As the content database can cache file disk contents, this method needs to be called so the cached data is invalidated. If this method is not called, then the content database might not re-check the disk contents before synchronization. In that case the synchronization will be skipped, even though it should happen.

When remote execution (via clusters) are used, this method will invalidate the local cache content database and the main content database as well. In some cases it can happen that the content database on the actual file system where the file resides will not be invalidated. This can happen when a task on cluster A modifies a file on cluster B. It is a very insignificant edge-case and it it strongly discouraged to configure an execution where such a scenario can happen.

This method works the same way as TaskContext.invalidate(PathKey), but reads the content descriptor at the given path after the invalidation.

The method works like TaskContext.invalidate(PathKey), but also instructs the build system to track the posix file permissions of the specified file. This will cause the file returned from TaskExecutionUtilities.createProviderPathFile(String, ProviderHolderPathKey) to have its SakerFile.getPosixFilePermissions() filled.

This method works only if the argument file resides on a filesystem that supports posix file permissions. Otherwise this method works the same way as TaskContext.invalidate(PathKey) without taking posix file permissions into account.

Same as calling:

 mirror(file, DirectoryVisitPredicate.everything());
 

If the file is a directory, then the parameter predicate will be used to select the files to mirror.

See TaskContext documentation for more information about mirroring.

The method will resolve the specified path to a directory and execute the mirroring.

If the file doesn't exist, or not a directory, an exception is thrown.

The method will resolve the specified path to a file and execute the mirroring.

If the file doesn't exist, or is a directory, an exception is thrown.

The method works the same way as TaskExecutionUtilities.mirrorFileAtPath(SakerPath), but returns the content descriptor of the mirrored file.

Calling this method might implicitly synchronize the file to its real location, or to some other cache location when remote execution is used.

Calling this method might implicitly synchronize the file to its real location, or to some other cache location when remote execution is used.

This method is called for each file tag that is passed to any of the file dependency management methods.

The default implementation directly returns the argument.

This method is called for each file tag that is passed to any of the file dependency management methods.

The default implementation directly returns the argument.

This method is called for each task output tag that is passed to any of the task output management methods.

The default implementation directly returns the argument.

The lines printed using this function will be replayed if the task is not executed again due to no incremental changes.

The line is automatically prepended by the display identifier if set.

To display uniformly formatted data, we recommend using SakerLog logging functions.

The argument line will be automatically appended with a line ending character(s).

When the lock is released all partially finished lines of TaskContext.getStandardOut() will be ended.

This method works the same way as TaskContext.println(String), however, it doesn't actually print the line to the output. It only stores the line to be printed if the task is not executed again due to no incremental changes.

This method records the dependency value for the given property for the execution runtime. When the task is executed next time in an incremental manner, the current value for the property will be compared to the expected value. If it changed, an appropriate delta will be triggered and the task will be rerun.

This method records the dependency value for the given property for the execution runtime. When the task is executed next time in an incremental manner, the current value for the property will be compared to the expected value. If it changed, an appropriate delta will be triggered and the task will be rerun.

IDE configurations can be considered as meta-data from the tasks which can be used to properly configure an editor for IDE related features.

Tasks are not required to always report IDE configurations, it can be toggled by the user using execution parameters. If a task decides to adhere these configuration changes, make sure to report an execution dependency, so the task is rerun when the parameter changes. (See IDEConfigurationRequiredExecutionProperty)

This method works the same way as TaskContext.reportIgnoredException(ExceptionView), but takes care of converting the exception to an appropriate ExceptionView.

Unhandled exceptions do not modify the operation of the task or the build execution. The build system may present these to the user to debug or analyze possible inconsistent build output.

Ignoring an exception should not modify the output of a task in any way.

One good example for an ignored exception is one thrown during verbose logging to the standard output. When the task tries to write some verbose information about the execution output, but it fails with an exception, then the task might choose to ignore the thrown exception, as it doesn't modify the result of the task in any way, but only the displayed information to the user.

The build system may handle the ignored exceptions in an implementation dependent way.

If the parameter is null, a NullPointerException will be ignored.

The build executor will collect the files for the dependency next time the task is incrementally run. If it detects any added files, then an appropriate delta will be triggered, and the task will be rerun.

Important: The task needs to report any used files as input dependencies via TaskContext.reportInputFileDependency(Object, SakerPath, ContentDescriptor), else a delta will be triggered for the unreported files as well next time the task is run.

Example:
The task reports a file addition dependency, and reports the file A as input.
The user adds file B as a new file. Next time the task is incrementally run, the build executor collects the files, and will report file B as an addition with the appropriate delta and rerun the task.
If the task didn't report file A, then the build executor would report file A as an addition, even though it is not newly added. It is important to report the files the task uses as input dependency.

A file addition dependency can be reported multiple times, with different tags as well.

Each path-content descriptor pair will be reported as an input dependency.

See TaskContext.reportInputFileDependency(Object, SakerPath, ContentDescriptor).

The build executor will check if the contents of the file at the given path have changed next time the task is incrementally run. If it detects changes, then an appropriate delta will be triggered, and the task will be rerun.

When an input dependency is reported multiple times with the same path and tag, then the actually recorded contents is chosen in an implementation dependent manner, and no exception is thrown.

See TaskContext.getTaskUtilities() for reporting bulk file dependencies, or working with file instances directly.

Each path-content descriptor pair will be reported as an output dependency.

See TaskContext.reportOutputFileDependency(Object, SakerPath, ContentDescriptor).

The build executor will check if the contents of the file at the given path have changed next time the task is incrementally run. If it detects changes, then an appropriate delta will be triggered, and the task wil be rerun.

When an output dependency is reported multiple times with the same path and tag, then the actually recorded contents is chosen in an implementation dependent manner, and no exception is thrown

It is recommended that all output files are under the build directory, unless explicitly specified by the user.

The reported output files are not automatically synchronized by the build runtime. (See SakerFile.synchronize())

See TaskContext.getTaskUtilities() for reporting bulk file dependencies, or working with file instances directly.

Setting an output change detector for the self task can result in skipping rerunning the tasks which depend on this task. The set detector should report the output unchanged if the object returned from Task.run(TaskContext) can be considered as unchanged from an external perspective.

The task can report themselves as unchanged, if output files of the task changed, but the information held in the output object remained the same. Usually EqualityTaskOutputChangeDetector is used with this method instantiated with the returned output object.

A very simple example for this:
A task calculates the sum of two input integers. In the first run it calculates 1 + 3. The input integers change for the next build, and the task will now calculate 2 + 2.
As the outputs of the task is the same, setting a self change detector can result in not rerunning any other tasks which depend on this.

If the path is relative, it will be resolved against the current task working directory.

If it is absolute, the execution root directories will be used as a base of resolution.

The path names are interpreted as if they were relative compared to the base directory.

This method doesn't overwrite the already existing file at the path if it's not a directory.

If the path is relative, it will be resolved against the current task working directory.

If it is absolute, the execution root directories will be used as a base of resolution.

If the path is relative, it will be resolved against the current task working directory.

If it is absolute, the execution root directories will be used as a base of resolution.

This method doesn't overwrite the already existing file at the path if it's not a directory.

If the path is relative, it will be resolved against the current task working directory.

If it is absolute, the execution root directories will be used as a base of resolution.

This method doesn't overwrite the already existing file at the path if it's not a directory.

The path names are interpreted as if they were relative compared to the base directory.

The path names are interpreted as if they were relative compared to the base directory.

This method doesn't overwrite the already existing file at the path if it's not a directory.

The path names are interpreted as if they were relative compared to the base directory.

If the path is relative, it will be resolved against the current task working directory.

If it is absolute, the execution root directories will be used as a base of resolution.

The path names are interpreted as if they were relative compared to the base directory.

This method is similar to TaskExecutionUtilities.runTaskResult(TaskIdentifier, TaskFactory<R>, TaskExecutionParameters), but doesn't add a dependency for the task, and returns a TaskFuture instance to the caller.