This interface defines methods for the following reasons:
- Convenience, some methods require less parameters so callers don't need to bother dealing with the fully parameterized counterparts.
- Bulk methods which result in better performance, as they only need to be called once instead of calling a single method multiple times.
- Remote execution support methods, to avoid multiple unnecessary RMI calls and do a specific operation quicker. This can also include optional caching.
- Additional utilities for communicating with the build system.
Convenience methods (unless noted otherwise) work the same way as their same named counterparts in TaskContext.
Bulk methods provide better performance for working with larger data sets. They are usually the equivalent of calling the corresponding singular parameterized function multiple times for every element in an argument collection. These methods should be preferred, as the build system can optimize handling of these. They are also strongly recommended when designing tasks for remote execution, as these require significantly less RMI calls, therefore less delay due to network communication. See: reporting dependencies, starting tasks, invalidating files.
Remote execution support methods are present to increase performance of remote execution capable tasks, and to
provide functionality which would require extra work for task implementations to handle. These methods can employ
cluster-local caching for file contents, and reduce the number of RMI calls required to do something. See: file
resolution, file manipulation, file content retrieval, file creation, and other methods.
These methods can be called even if a task is not designed for remote execution, they can be handled the same way.
They are only present for performance and utility reasons.
The reason of the existence of this utility class is that although these methods could be declared in the TaskContext interface, it was decided to export these as these would pollute the TaskContext interface.
The naming of the task starting methods are based on their return value. Methods that end with Future
will return a future to the started task(s), methods that end with Result
returns the result of the task
execution, and methods that doesn't have a special ending will return void
. These methods differ from
startTask as that returns a
future, but methods in this interface is specially named. Tasks should consider choosing the void
returning methods when they are not intereseted in the result in any way, as it can reduce the load on the RMI
runtime when remote execution is used.
Clients should not implement this interface. Additional methods can be added to this interface without prior notice.
public static final class |
public static final int | Synchronization operation flag to signal that the posix file permissions should be copied from the source file to
the target. |
public static final int | Synchronization operation flag to signal that the synchronization may delete intermediate files when creating the
parent directories. |
public static final int | Synchronization operation flag representing no flags. |
public static final int | Synchronization operation flag to specify that non-empty directories shouldn't be deleted as part of the
operation. |
public default SakerFile | addFile( Adds a file to the specified directory. |
public default SakerFile | addFileIfAbsent( Add a file to the specified directory only if there is no file present yet with the same name. |
public default SakerFile | addFileOverwriteIfNotDirectory( Add a file to the specified directory only if there is no directory present with the same name. |
public void | addSynchronizeInvalidatedProviderPathFileToDirectory( Add and synchronizes a SakerFile to the specified directory with the given name that has its contents
backed by the given path key. |
public NavigableMap< | collectFiles( Collects the files for the given file collection strategy. |
public NavigableMap< | collectFilesReportAdditionDependency( Bulk method for calling collectFilesReportAdditionDependency( |
public default NavigableMap< | collectFilesReportAdditionDependency( Collects the files for the given addition dependency, and reports it. |
public NavigableMap< | collectFilesReportInputFileAndAdditionDependency( Bulk method for calling
collectFilesReportInputFileAndAdditionDependency( |
public default NavigableMap< | collectFilesReportInputFileAndAdditionDependency( Collects the files for the given file addition dependency, and reports it and the files as dependencies. |
public SakerFile | createProviderPathFile( Creates a SakerFile instance which has its contents backed by the specified file system file at the given
path. |
public SakerFile | createProviderPathFile( Creates a SakerFile instance which has its contents backed by the specified file system file at the given
path, and associates the argument content descriptor with the current contents. |
public default SakerFile | Creates a SakerFile instance which has its contents backed by the specified file system file at the given
path. |
public SakerFile | createProviderPathFileWithPosixFilePermissions( Creates a SakerFile instance which has its contents backed by the specified file system file at the given
path, and associates the argument content descriptor and posix file permissions with the current contents. |
public ByteArrayRegion | Gets the raw contents of the file as a byte array. |
public default NavigableMap< | Gets the content descriptors of the children of the specified directory. |
public String | getContent( Gets the contents of the file as a String. |
public < | getReportEnvironmentDependency( Gets the current value of the specified environment property and reports it as a dependency. |
public < | getReportExecutionDependency( Gets the current value of the specified execution property and reports it as a dependency. |
public TaskContext | Gets the task context which this utilities belong to. |
public void | invalidate( Bulk method for TaskContext.invalidate( |
public void | Invalidates the specified file and also associates the current posix file permissions of the file in the build
system. |
public Path | mirrorDirectoryAtPath( Executes the mirroring for a directory at the given execution path. |
public Path | mirrorFileAtPath( Executes the mirroring for a file at the given execution path. |
public MirroredFileContents | Executes the mirroring for a file at the given execution path and gets the file content descriptor. |
public ByteSource | openByteSource( Opens a byte source to the contents of the file. |
public InputStream | openInputStream( Opens an input stream to the contents of the file. |
public default void | Reports an unhandled exception that occurred during the execution of the task for informational purposes. |
public default void | reportInputFileDependency( Bulk method for reportInputFileDependency( |
public void | reportInputFileDependency( |
public void | reportInputFileDependency( Reports an input file dependency for the path of the file and its contents. |
public default void | reportOutputFileDependency( Bulk method for reportOutputFileDependency( |
public void | reportOutputFileDependency( |
public void | reportOutputFileDependency( Reports an output file dependency for the path of the file and its contents. |
public SakerFile | Resolves a file or directory using the given absolute path. |
public SakerFile | resolveAtPath( Same as resolveAtPath( |
public SakerFile | resolveAtPath( Resolves a file or directory at the given path. |
public default SakerFile | resolveAtRelativePath( Resolves a file or directory using the given relative path against a base directory. |
public default SakerFile | resolveAtRelativePathNames( Resolves a file or directory with the given path names against a base directory. |
public SakerDirectory | Resolves a directory using the given absolute path. |
public SakerDirectory | Resolves a directory using the given absolute path, creating it if necessary, overwriting already existing files. |
public SakerDirectory | Resolves a directory using the given absolute path, creating it if possible. |
public SakerDirectory | resolveDirectoryAtPath( Same as resolveDirectoryAtPath( |
public SakerDirectory | Resolves a directory at a given path. |
public SakerDirectory | resolveDirectoryAtPathCreate( Same as resolveDirectoryAtPathCreate( |
public SakerDirectory | Resolves a directory at a given path, creating it if necessary, overwriting already existing files. |
public SakerDirectory | resolveDirectoryAtPathCreateIfAbsent( Same as resolveDirectoryAtPathCreateIfAbsent( |
public SakerDirectory | Resolves a directory at a given path, creating it if possible. |
public default SakerDirectory | resolveDirectoryAtRelativePath( Resolves a directory using the given relative path against a base directory. |
public default SakerDirectory | resolveDirectoryAtRelativePathCreate( Resolves a directory using the given relative path against a base directory, creating it if necessary,
overwriting already existing files. |
public default SakerDirectory | resolveDirectoryAtRelativePathCreateIfAbsent( Resolves a directory using the given relative path against a base directory, creating it if possible. |
public default SakerDirectory | resolveDirectoryAtRelativePathNames( Resolves a directory with the given path names against a base directory. |
public default SakerDirectory | resolveDirectoryAtRelativePathNamesCreate( Resolves a directory with the given path names against a base directory, creating it if necessary, overwriting
already existing files. |
public default SakerDirectory | resolveDirectoryAtRelativePathNamesCreateIfAbsent( Resolves a directory with the given path names against a base directory, creating it if possible. |
public SakerFile | Resolves a file but not a directory using the given absolute path. |
public SakerFile | resolveFileAtPath( Same as resolveFileAtPath( |
public SakerFile | resolveFileAtPath( Resolves a file but not a directory at the given path. |
public default SakerFile | resolveFileAtRelativePath( Resolves a file but not a directory using the given relative path against a base directory. |
public default SakerFile | resolveFileAtRelativePathNames( Resolves a file but not a directory with the given path names against a base directory. |
public default void | runTask( Same as runTask( |
public default void | runTask( Same as runTaskFuture( null
execution parameters, but returns void . |
public default void | runTask( Same as runTaskFuture( void . |
public default < | runTaskFuture( Same as runTaskFuture( |
public default < | runTaskFuture( Convenience function to call runTaskFuture( |
public < | runTaskFuture( Starts a task and waits for its execution to complete. |
public default < | runTaskResult( Same as runTaskResult( |
public default < | runTaskResult( Convenience function to call runTaskResult( |
public default < | runTaskResult( Starts a task and waits for its execution to complete. |
public default void | startTask( Convenience function to call TaskContext.startTask( |
public default void | startTask( Convenience function to call TaskContext.startTask( |
public default < | startTaskFuture( Convenience function to call TaskContext.startTask( |
public default < | startTaskFuture( Convenience function to call TaskContext.startTask( |
public default void | startTasks( Batch function for starting tasks specified by the launch arguments. |
public default void | startTasks( Batch function for starting multiple tasks. |
public default void | startTasks( Batch function for starting multiple tasks with the specified execution parameters. |
public default List< | startTasksFuture( Batch function for starting tasks with the specified launch arguments and retrieving the futures for them. |
public ContentDescriptor | synchronize( Executes synchronization of files from the given source path to the specified target path. |
public default NavigableMap< | toPathContentMap( Converts the given files to a map with their retrieved paths as keys and content
descriptors as values. |
public default NavigableMap< | toPathFileMap( Converts the given files to a map with their retrieved paths as keys. |
public void | writeTo( Writes the contents of the file to the specified output stream. |
public void | Writes the contents of the file to the specified byte sink. |
This method works the same way as SakerDirectory.add(
This method can be called from both remote and non-remote executed tasks.
null
.
This method works the same way as SakerDirectory.addIfAbsent(
This method can be called from both remote and non-remote executed tasks.
null
if there is already a file with the same
name. If non-null
, it is the same as the parameter if called from non-remote executed
tasks.null
.
This method works the same way as SakerDirectory.addOverwriteIfNotDirectory(
This method can be called from both remote and non-remote executed tasks.
null
if there is a directory present with the
same name. If non-null
, it is the same as the parameter if called from non-remote
executed tasks.null
.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.
null
.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(
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(
For correct incremental operation tasks should not forget to report the dependencies as well. Consider calling
collectFilesReportInputFileAndAdditionDependency(
null
.This method collects the files for all the addition dependencies, and aggregates them into a single result map.
null
.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(
null
.This method collects the files for all the addition dependencies, and aggregates them into a single result map.
null
.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(
null
.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 createProviderPathFile(
null
.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.
null
.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)
null
.
The method works the same way as
createProviderPathFile(
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.
null
.null
.Calling this method might implicitly synchronize the file to its real location, or to some other cache location when remote execution is used.
null
.The resulting map is mapped by the file names of the children.
null
.Calling this method might implicitly synchronize the file to its real location, or to some other cache location when remote execution is used.
null
.null
.null
.null
.
The method works like TaskContext.invalidate(
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(
null
.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.
null
,
DirectoryVisitPredicate.everything() will be used.null
.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.
null
.
The method works the same way as mirrorFileAtPath(
null
.Calling this method might implicitly synchronize the file to its real location, or to some other cache location when remote execution is used.
null
.Calling this method might implicitly synchronize the file to its real location, or to some other cache location when remote execution is used.
null
.
This method works the same way as TaskContext.reportIgnoredException(
null
.
See TaskContext.reportInputFileDependency(
null
.null
.
See TaskContext.reportOutputFileDependency(
null
.null
if not found.null
.null
if not found.null
, or path is relative and base directory is null
.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.
null
if not found.null
.null
if not found.null
.The path names are interpreted as if they were relative compared to the base directory.
null
if not found.null
.null
if a directory was not found at the path.null
.null
.This method doesn't overwrite the already existing file at the path if it's not a directory.
null
if it cannot be created.null
.null
if a directory was not found at the path.null
, or path is relative and base directory is null
.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.
null
if a directory was not found at the path.null
.null
, or path is relative and base directory is null
.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.
null
.null
if it cannot be created.null
, or path is relative and base directory is null
.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.
null
if it cannot be created.null
.null
if a directory was not found at the path.null
.null
.This method doesn't overwrite the already existing file at the path if it's not a directory.
null
if it cannot be created.null
.The path names are interpreted as if they were relative compared to the base directory.
null
if a directory was not found at the path.null
.The path names are interpreted as if they were relative compared to the base directory.
null
.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.
null
if it cannot be created.null
.null
if not found or it's a directory.null
.null
if not found or it's a directory.null
, or path is relative and base directory is null
.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.
null
if not found or it's a directory.null
.null
if not found.null
.The path names are interpreted as if they were relative compared to the base directory.
null
if not found or it's a directory.null
.null
.null
execution parameters, but returns void
.null
.void
.null
to use the defaults.null
.null
.null
.
This method is similar to runTaskResult(
null
to use the defaults.null
.null
.null
.
A task dependency will be added for the started task with the same rules as in
TaskContext.getTaskResult(
null
to use the defaults.null
.This method returns no result.
null
.This method returns no result.
null
.null
.null
.This function starts every task with the parameters specified by each launch arguments.
This function works the same way as if startTask(
This function returns void
, to retrieve the futures for the started tasks as well, use
startTasksFuture(
null
.The started tasks will use the default execution parameters.
This function works the same way as startTasks(null
execution parameters.
null
.
The passed execution parameters will be used for each started task. If null
, the default parameters
will be used.
null
.
This function works the same way as if startTaskFuture(
The returned list of task futures will have the same order as the argument iterable.
null
.This method synchronizes the contents of the source path file to the target path.
If the source file is a file, its contents will be updated to the target path. If a file already exists at the target path, it will be overwritten. Parent directories will be created at the target path if necessary. Specifying the flag SYNCHRONIZE_FLAG_NO_OVERWRITE_DIRECTORY will cause the synchronization to throw an exception if a non-empty directory already exists at the target. Empty directories at the target path will be deleted and overwritten with the byte contents of the source file.
If the source file is a directory, then a directory will be created at the target path. Children of the source directory are not synchronized. If a file already exists at the target path, it will be deleted and a directory is created instead. If a directory already exists at the target path, no operations are done. Parent directories are created appropriately.
SYNCHRONIZE_FLAG_*
constants in the class.null
.The implementation doesn't examine the nature of the retrieved paths. If there are conflicting paths, then the resulting map may be smaller in size than the passed input. E.g. If multiple files have no parent, but same file name, only one will be in the result map with its name.
When calling this during remote execution, it is recommended that the files reside on the coordinator machine.
null
.The implementation doesn't examine the nature of the retrieved paths. If there are conflicting paths, then the resulting map may be smaller in size than the passed input. E.g. If multiple files have no parent, but same file name, only one will be in the result map with its name.
When calling this during remote execution, it is recommended that the files reside on the coordinator machine.
null
.Calling this method might implicitly synchronize the file to its real location, or to some other cache location when remote execution is used.
null
.Calling this method might implicitly synchronize the file to its real location, or to some other cache location when remote execution is used.
null
.