saker.build Documentation TaskDoc JavaDoc Packages
public interface TaskExecutionUtilities
Interface for an utility class that provides extension functions for TaskContext.

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.

Nested types
public static final class
Holds information about a path and associated contents.
Fields
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.
Methods
public default SakerFile
Adds a file to the specified directory.
public default SakerFile
Add a file to the specified directory only if there is no file present yet with the same name.
public default SakerFile
Add a file to the specified directory only if there is no directory present with the same name.
public void
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<SakerPath, SakerFile>
Collects the files for the given file collection strategy.
public NavigableMap<SakerPath, SakerFile>
public default NavigableMap<SakerPath, SakerFile>
Collects the files for the given addition dependency, and reports it.
public NavigableMap<SakerPath, SakerFile>
public default NavigableMap<SakerPath, SakerFile>
Collects the files for the given file addition dependency, and reports it and the files as dependencies.
public SakerFile
Creates a SakerFile instance which has its contents backed by the specified file system file at the given path.
public SakerFile
createProviderPathFile(String name, ProviderHolderPathKey pathkey, ContentDescriptor currentpathcontentdescriptor)
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
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<String, ContentDescriptor>
Gets the content descriptors of the children of the specified directory.
public String
Gets the contents of the file as a String.
public <T> T
Gets the current value of the specified environment property and reports it as a dependency.
public <T> T
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(Iterable<extends PathKey> pathkeys)
public void
Invalidates the specified file and also associates the current posix file permissions of the file in the build system.
public Path
Executes the mirroring for a directory at the given execution path.
public Path
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
Opens a byte source to the contents of the file.
public InputStream
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
public void
public void
Reports an input file dependency for the path of the file and its contents.
public default void
public void
public void
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
Same as resolveAtPath(SakerPath), but uses the specified base directory to resolve relative paths.
public SakerFile
Resolves a file or directory at the given path.
public default SakerFile
Resolves a file or directory using the given relative path against a base directory.
public default SakerFile
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
Same as resolveDirectoryAtPath(SakerPath), but uses the specified base directory to resolve relative paths.
public SakerDirectory
Resolves a directory at a given path.
public SakerDirectory
Same as resolveDirectoryAtPathCreate(SakerPath), but uses the specified base directory to resolve relative paths.
public SakerDirectory
Resolves a directory at a given path, creating it if necessary, overwriting already existing files.
public SakerDirectory
Same as resolveDirectoryAtPathCreateIfAbsent(SakerPath), but uses the specified base directory to resolve relative paths.
public SakerDirectory
Resolves a directory at a given path, creating it if possible.
public default SakerDirectory
Resolves a directory using the given relative path against a base directory.
public default SakerDirectory
Resolves a directory using the given relative path against a base directory, creating it if necessary, overwriting already existing files.
public default SakerDirectory
Resolves a directory using the given relative path against a base directory, creating it if possible.
public default SakerDirectory
Resolves a directory with the given path names against a base directory.
public default SakerDirectory
Resolves a directory with the given path names against a base directory, creating it if necessary, overwriting already existing files.
public default SakerDirectory
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
Same as resolveFileAtPath(SakerPath), but uses the specified base directory to resolve relative paths.
public SakerFile
Resolves a file but not a directory at the given path.
public default SakerFile
Resolves a file but not a directory using the given relative path against a base directory.
public default SakerFile
Resolves a file but not a directory with the given path names against a base directory.
public default void
Same as runTask(TaskIdentifier, TaskFactory<?>, TaskExecutionParameters) with the arguments derived from the specified launch arguments.
public default void
runTask(TaskIdentifier taskid, TaskFactory<?> taskfactory)
Same as runTaskFuture(TaskIdentifier, TaskFactory<R>, TaskExecutionParameters) with null execution parameters, but returns void.
public default void
runTask(TaskIdentifier taskid, TaskFactory<?> taskfactory, TaskExecutionParameters parameters)
public default <R> TaskFuture<R>
Same as runTaskFuture(TaskIdentifier, TaskFactory<R>, TaskExecutionParameters) with the arguments derived from the specified launch arguments.
public default <R> TaskFuture<R>
runTaskFuture(TaskIdentifier taskid, TaskFactory<R> taskfactory)
Convenience function to call runTaskFuture(TaskIdentifier, TaskFactory<R>, TaskExecutionParameters) with the default task execution parameters.
public <R> TaskFuture<R>
Starts a task and waits for its execution to complete.
public default <R> R
Same as runTaskResult(TaskIdentifier, TaskFactory<R>, TaskExecutionParameters) with the arguments derived from the specified launch arguments.
public default <R> R
runTaskResult(TaskIdentifier taskid, TaskFactory<R> taskfactory)
Convenience function to call runTaskResult(TaskIdentifier, TaskFactory<R>, TaskExecutionParameters) with the default task execution parameters.
public default <R> R
Starts a task and waits for its execution to complete.
public default void
public default void
startTask(TaskIdentifier taskid, TaskFactory<?> taskfactory)
Convenience function to call TaskContext.startTask(TaskIdentifier, TaskFactory<R>, TaskExecutionParameters) with the default task execution parameters.
public default <R> TaskFuture<R>
public default <R> TaskFuture<R>
Convenience function to call TaskContext.startTask(TaskIdentifier, TaskFactory<R>, TaskExecutionParameters) with the default task execution parameters.
public default void
Batch function for starting tasks specified by the launch arguments.
public default void
startTasks(Map<extends TaskIdentifier, ? extends TaskFactory<?>> tasks)
Batch function for starting multiple tasks.
public default void
startTasks(Map<extends TaskIdentifier, ? extends TaskFactory<?>> tasks, TaskExecutionParameters parameters)
Batch function for starting multiple tasks with the specified execution parameters.
public default List<extends TaskFuture<?>>
Batch function for starting tasks with the specified launch arguments and retrieving the futures for them.
public ContentDescriptor
Executes synchronization of files from the given source path to the specified target path.
public default NavigableMap<SakerPath, ContentDescriptor>
Converts the given files to a map with their retrieved paths as keys and content descriptors as values.
public default NavigableMap<SakerPath, SakerFile>
toPathFileMap(Iterable<extends SakerFile> files)
Converts the given files to a map with their retrieved paths as keys.
public void
Writes the contents of the file to the specified output stream.
public void
Writes the contents of the file to the specified byte sink.
Synchronization operation flag to signal that the posix file permissions should be copied from the source file to the target.
saker.build 0.8.13
public static final int SYNCHRONIZE_FLAG_DELETE_INTERMEDIATE_FILES = 2
Synchronization operation flag to signal that the synchronization may delete intermediate files when creating the parent directories.
public static final int SYNCHRONIZE_FLAG_NONE = 0
Synchronization operation flag representing no flags.
public static final int SYNCHRONIZE_FLAG_NO_OVERWRITE_DIRECTORY = 1
Synchronization operation flag to specify that non-empty directories shouldn't be deleted as part of the operation.
Adds a file to the specified directory.

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.

directoryThe directory to add the file to.
fileThe file to add.
The file which was added to the directory. It is the same as the parameter if called from non-remote executed tasks.
NullPointerExceptionIf any of the parameters are null.
Add a file to the specified directory only if there is no file present yet with the same name.

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.

directoryThe directory to add the file to.
fileThe file to add.
The file which was added to the directory or 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.
NullPointerExceptionIf any of the parameters are null.
Add a file to the specified directory only if there is no directory present with the same name.

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.

directoryThe directory to add the file to.
fileThe file to add.
The file which was added to the directory or 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.
NullPointerExceptionIf any of the parameters are null.
Add and synchronizes a SakerFile to the specified directory with the given name that has its contents backed by the given path key.

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.

directoryThe directory to add the file to.
pathkeyThe path key at which the given result file resides.
filenameThe name of the created SakerFile that is added to the directory.
IOExceptionIn case of I/O error.
NullPointerExceptionIf any of the arguments are null.
Collects the files for the given file collection strategy.

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 collectFilesReportInputFileAndAdditionDependency(Object, FileCollectionStrategy) instead of this function.

collectionstrategyThe file collection strategy.
The collected files.
NullPointerExceptionIf the argument is null.
Bulk method for calling collectFilesReportAdditionDependency(Object, FileCollectionStrategy).

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

tagThe tag for the dependencies.
fileadditiondependenciesThe file addition dependencies.
The collected files.
NullPointerExceptionIf the file addition dependencies or any of the elements are null.
Collects the files for the given addition dependency, and reports it.

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.

tagThe tag for the dependencies.
fileadditiondependencyThe file addition dependency.
The collected files.
NullPointerExceptionIf the file addition dependency is null.
Bulk method for calling collectFilesReportInputFileAndAdditionDependency(Object, FileCollectionStrategy).

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

tagThe tag for the dependencies.
fileadditiondependenciesThe file addition dependencies.
The collected files.
NullPointerExceptionIf the file addition dependencies or any of the elements are null.
Collects the files for the given file addition dependency, and reports it and the files as dependencies.

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.

tagThe tag for the dependencies.
fileadditiondependencyThe file addition dependency.
The collected files.
NullPointerExceptionIf the file addition dependency is null.
Creates a SakerFile instance which has its contents backed by the specified file system file at the given path.

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(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.)

nameThe name to create the file with.
pathkeyThe path to the contents which is used by the created file.
The file or directory instance.
NullPointerExceptionIf any of the arguments are null.
IOExceptionIf accessing the file at the given path results in an I/O error.
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.

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.

nameThe name to create the file with.
pathkeyThe path to the contents which is used by the created file.
currentpathcontentdescriptorThe content descriptor to associate with the current file system contents.
The created file.
IOExceptionIf the operation fails due to I/O error.
NullPointerExceptionIf any of the arguments are null.
InvalidFileTypeExceptionIf the file is a directory.
Creates a SakerFile instance which has its contents backed by the specified file system file at the given path.

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)
 
pathkeyThe path key.
The file or directory instance.
NullPointerExceptionIf the argument is null.
IOExceptionIf accessing the file at the given path results in an I/O error.
saker.build 0.8.13
public abstract SakerFile createProviderPathFileWithPosixFilePermissions(String name, ProviderHolderPathKey pathkey, @RMISerializeContentDescriptor currentpathcontentdescriptor, @RMIWrap(saker.build.util.rmi.EnumSetRMIWrapper.class)Set<PosixFilePermission> permissions) throws IOException, NullPointerException, InvalidFileTypeException
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.

The method works the same way as 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.

nameThe name to create the file with.
pathkeyThe path to the contents which is used by the created file.
currentpathcontentdescriptorThe content descriptor to associate with the current file system contents.
permissionsThe posix file permissions to associate with the given file. May be null.
The created file.
IOExceptionIf the operation fails due to I/O error.
NullPointerExceptionIf any of the arguments except the posix file permissions are null.
InvalidFileTypeExceptionIf the file is a directory.
saker.build 0.8.13
Gets the raw contents of the file as a byte array.

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

fileThe file.
The raw contents of the file.
IOExceptionIn case of I/O error.
NullPointerExceptionIf the file is null.
Gets the content descriptors of the children of the specified directory.

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

dirThe directory.
A new map of file names mapped to their content descriptors.
NullPointerExceptionIf the directory is null.
Gets the contents of the file as a String.

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

fileThe file.
The string contents of the file.
IOExceptionIn case of I/O error.
NullPointerExceptionIf the file is null.
Gets the current value of the specified environment property and reports it as a dependency.
TThe type of the returned property.
propertyThe environment property.
The current value of the environment 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 current value of the specified execution property and reports it as a dependency.
TThe type of the returned property.
propertyThe execution property.
The current value of the execution 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 task context which this utilities belong to.
The task context.
public abstract void invalidate(@RMIWrap(RMIArrayListWrapper.class)Iterable<extends PathKey> pathkeys) throws NullPointerException
pathkeysThe path keys to invalidate.
NullPointerExceptionIf the argument, or any of its element is null.
Invalidates the specified file and also associates the current posix file permissions of the file in the build system.

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

pathkeyThe path key to invalidate.
NullPointerExceptionIf the path key is null.
IOExceptionIn case of I/O error.
saker.build 0.8.13
Executes the mirroring for a directory at the given execution path.

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.

pathThe path of the directory to mirror. Relative paths are resolved against the task working directory.
synchpredicateThe predicate to use for mirroring. If this is null, DirectoryVisitPredicate.everything() will be used.
The path to the mirrored directory.
IOExceptionIn case of I/O error.
InvalidFileTypeExceptionIf the file at the path is not a directory.
FileNotFoundExceptionIf no file found at the given path.
NullPointerExceptionIf the path is null.
Executes the mirroring for a file at the given execution path.

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.

pathThe path of the file to mirror. Relative paths are resolved against the task working directory.
The path to the mirrored file.
IOExceptionIn case of I/O error.
InvalidFileTypeExceptionIf the file at the path is a directory.
FileNotFoundExceptionIf no file found at the given path.
NullPointerExceptionIf the path is null.
Executes the mirroring for a file at the given execution path and gets the file content descriptor.

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

pathThe path of the file to mirror. Relative paths are resolved against the task working directory.
The path and contents of the mirrored file.
IOExceptionIn case of I/O error.
InvalidFileTypeExceptionIf the file at the path is a directory.
FileNotFoundExceptionIf no file found at the given path.
NullPointerExceptionIf the path is null.
Opens a byte source to the contents of the file.

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

fileThe file.
The opened byte source.
IOExceptionIn case of I/O error.
NullPointerExceptionIf the file is null.
Opens an input stream to the contents of the file.

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

fileThe file.
The opened input stream.
IOExceptionIn case of I/O error.
NullPointerExceptionIf the file is null.
Reports an unhandled exception that occurred during the execution of the task for informational purposes.

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

eThe exception.
tagThe tag for the dependency.
filesThe files to report the dependencies for.
InvalidPathFormatExceptionIf the path of a file is not absolute.
NullPointerExceptionIf the files or any of its elements are null.
Bulk method for TaskContext.reportInputFileDependency(Object, SakerPath, ContentDescriptor).

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

tagThe tag for the dependency.
pathcontentsThe paths to contents map for each dependency.
NullPointerExceptionIf the path contents are null.
IllegalArgumentExceptionIf the map is not sorted by natural order.
Reports an input file dependency for the path of the file and its contents.

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

tagThe tag for the dependency.
fileThe file to report the dependency for.
InvalidPathFormatExceptionIf the path of the file is not absolute.
NullPointerExceptionIf the file is null.
tagThe tag for the dependency.
filesThe files to report the dependencies for.
InvalidPathFormatExceptionIf the path of a file is not absolute.
NullPointerExceptionIf the files or any of its elements are null.
Bulk method for TaskContext.reportOutputFileDependency(Object, SakerPath, ContentDescriptor).

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

tagThe tag for the dependency.
pathcontentsThe paths to contents map for each dependency.
NullPointerExceptionIf the path contents are null.
IllegalArgumentExceptionIf the map is not sorted by natural order.
Reports an output file dependency for the path of the file and its contents.

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

tagThe tag for the dependency.
fileThe file to report the dependency for.
InvalidPathFormatExceptionIf the path of the file is not absolute.
NullPointerExceptionIf the file is null.
Resolves a file or directory using the given absolute path.
pathThe absolute path.
The resolved file or null if not found.
NullPointerExceptionIf the path is null.
InvalidPathFormatExceptionIf the path is not absolute.
Same as resolveAtPath(SakerPath), but uses the specified base directory to resolve relative paths.
basedirThe base directory.
pathThe path to resolve.
The found file at the given path or null if not found.
NullPointerExceptionIf path is null, or path is relative and base directory is null.
Resolves a file or directory at the given path.

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.

pathThe path to resolve.
The found file at the given path or null if not found.
NullPointerExceptionIf the path is null.
Resolves a file or directory using the given relative path against a base directory.
basedirThe base directory.
pathThe relative path.
The resolved file or null if not found.
NullPointerExceptionIf any of the arguments are null.
InvalidPathFormatExceptionIf the path is not relative.
Resolves a file or directory with the given path names against a base directory.

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

basedirThe base directory.
namesThe relative path names.
The resolved file or null if not found.
NullPointerExceptionIf any of the arguments or path names are null.
InvalidPathFormatExceptionIf any of the path name has invalid format.
Resolves a directory using the given absolute path.
pathThe absolute path.
The resolved directory or null if a directory was not found at the path.
NullPointerExceptionIf the path is null.
InvalidPathFormatExceptionIf the path is not absolute.
Resolves a directory using the given absolute path, creating it if necessary, overwriting already existing files.
pathThe absolute path.
The directory at the given path.
NullPointerExceptionIf the path is null.
InvalidPathFormatExceptionIf the path is not absolute.
Resolves a directory using the given absolute path, creating it if possible.

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

pathThe absolute path.
The directory at the given path or null if it cannot be created.
NullPointerExceptionIf the path is null.
InvalidPathFormatExceptionIf the path is not absolute.
Same as resolveDirectoryAtPath(SakerPath), but uses the specified base directory to resolve relative paths.
basedirThe base directory.
pathThe path to resolve.
The found directory at the given path or null if a directory was not found at the path.
NullPointerExceptionIf path is null, or path is relative and base directory is null.
Resolves a directory at a given path.

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.

pathThe path to resolve.
The found directory at the given path or null if a directory was not found at the path.
NullPointerExceptionIf the path is null.
Same as resolveDirectoryAtPathCreate(SakerPath), but uses the specified base directory to resolve relative paths.
basedirThe base directory.
pathThe path to resolve.
The directory at the given path.
NullPointerExceptionIf path is null, or path is relative and base directory is null.
Resolves a directory at a given path, creating it if necessary, overwriting already existing files.

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.

pathThe path to resolve.
The directory at the given path.
NullPointerExceptionIf the path is null.
Same as resolveDirectoryAtPathCreateIfAbsent(SakerPath), but uses the specified base directory to resolve relative paths.
basedirThe base directory.
pathThe path to resolve.
The directory at the given path or null if it cannot be created.
NullPointerExceptionIf path is null, or path is relative and base directory is null.
Resolves a directory at a given path, creating it if possible.

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.

pathThe path to resolve.
The directory at the given path or null if it cannot be created.
NullPointerExceptionIf the path is null.
Resolves a directory using the given relative path against a base directory.
basedirThe base directory.
pathThe relative path.
The resolved directory or null if a directory was not found at the path.
NullPointerExceptionIf any of the arguments are null.
InvalidPathFormatExceptionIf the path is not relative.
Resolves a directory using the given relative path against a base directory, creating it if necessary, overwriting already existing files.
basedirThe base directory.
pathThe relative path.
The directory at the given path.
NullPointerExceptionIf any of the arguments are null.
InvalidPathFormatExceptionIf the path is not relative.
Resolves a directory using the given relative path against a base directory, creating it if possible.

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

basedirThe base directory.
pathThe relative path.
The directory at the given path or null if it cannot be created.
NullPointerExceptionIf any of the arguments are null.
InvalidPathFormatExceptionIf the path is not relative.
Resolves a directory with the given path names against a base directory.

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

basedirThe base directory.
namesThe relative path names.
The resolved directory or null if a directory was not found at the path.
NullPointerExceptionIf any of the arguments or path names are null.
InvalidPathFormatExceptionIf any of the path name has invalid format.
Resolves a directory with the given path names against a base directory, creating it if necessary, overwriting already existing files.

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

basedirThe base directory.
namesThe relative path names.
The directory at the given path.
NullPointerExceptionIf any of the arguments or path names are null.
InvalidPathFormatExceptionIf any of the path name has invalid format.
Resolves a directory with the given path names against a base directory, creating it if possible.

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.

basedirThe base directory.
namesThe relative path names.
The directory at the given path or null if it cannot be created.
NullPointerExceptionIf any of the arguments or path names are null.
InvalidPathFormatExceptionIf any of the path name has invalid format.
Resolves a file but not a directory using the given absolute path.
pathThe absolute path.
The resolved file or null if not found or it's a directory.
NullPointerExceptionIf the path is null.
InvalidPathFormatExceptionIf the path is not absolute.
Same as resolveFileAtPath(SakerPath), but uses the specified base directory to resolve relative paths.
basedirThe base directory.
pathThe path to resolve.
The found file at the given path or null if not found or it's a directory.
NullPointerExceptionIf path is null, or path is relative and base directory is null.
Resolves a file but not a directory at the given path.

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.

pathThe path to resolve.
The found file at the given path or null if not found or it's a directory.
NullPointerExceptionIf the path is null.
Resolves a file but not a directory using the given relative path against a base directory.
basedirThe base directory.
pathThe relative path.
The resolved file or null if not found.
NullPointerExceptionIf any of the arguments are null.
InvalidPathFormatExceptionIf the path is not relative.
Resolves a file but not a directory with the given path names against a base directory.

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

basedirThe base directory.
namesThe relative path names.
The resolved file or null if not found or it's a directory.
NullPointerExceptionIf any of the arguments or path names are null.
InvalidPathFormatExceptionIf any of the path name has invalid format.
Same as runTask(TaskIdentifier, TaskFactory<?>, TaskExecutionParameters) with the arguments derived from the specified launch arguments.
taskThe launch arguments of the task.
TaskIdentifierConflictExceptionIf a task with the same identifier is already started and the task factories does not equal.
NullPointerExceptionIf task identifier or task factory is null.
IllegalTaskOperationExceptionIf the task identifier is the same as the caller.
Same as runTaskFuture(TaskIdentifier, TaskFactory<R>, TaskExecutionParameters) with null execution parameters, but returns void.
taskidThe task identifier for the task to run.
taskfactoryThe task factory of the task.
TaskIdentifierConflictExceptionIf a task with the same identifier is already started and the task factories does not equal.
NullPointerExceptionIf task identifier or task factory is null.
IllegalTaskOperationExceptionIf the task identifier is the same as the caller.
taskidThe task identifier for the task to run.
taskfactoryThe task factory of the task.
parametersThe task execution parameters, or null to use the defaults.
TaskIdentifierConflictExceptionIf a task with the same identifier is already started and the task factories does not equal.
NullPointerExceptionIf task identifier or task factory is null.
IllegalTaskOperationExceptionIf the task identifier is the same as the caller.
Same as runTaskFuture(TaskIdentifier, TaskFactory<R>, TaskExecutionParameters) with the arguments derived from the specified launch arguments.
RThe result type of the task.
taskThe launch arguments of the task.
A future handle for the run task.
TaskIdentifierConflictExceptionIf a task with the same identifier is already started and the task factories does not equal.
NullPointerExceptionIf task identifier or task factory is null.
IllegalTaskOperationExceptionIf the task identifier is the same as the caller.
Convenience function to call runTaskFuture(TaskIdentifier, TaskFactory<R>, TaskExecutionParameters) with the default task execution parameters.
RThe result type of the task.
taskidThe task identifier for the task to run.
taskfactoryThe task factory of the task.
A future handle for the run task.
TaskIdentifierConflictExceptionIf a task with the same identifier is already started and the task factories does not equal.
NullPointerExceptionIf any of the arguments are null.
IllegalTaskOperationExceptionIf the task identifier is the same as the caller.
Starts a task and waits for its execution to complete.

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

RThe result type of the task.
taskidThe task identifier for the task to run.
taskfactoryThe task factory of the task.
parametersThe task execution parameters, or null to use the defaults.
A future handle for the run task.
TaskIdentifierConflictExceptionIf a task with the same identifier is already started and the task factories does not equal.
NullPointerExceptionIf task identifier or task factory is null.
IllegalTaskOperationExceptionIf the task identifier is the same as the caller.
Same as runTaskResult(TaskIdentifier, TaskFactory<R>, TaskExecutionParameters) with the arguments derived from the specified launch arguments.
RThe result type of the task.
taskThe launch arguments of the task.
The result of the task execution.
TaskIdentifierConflictExceptionIf a task with the same identifier is already started and the task factories does not equal.
NullPointerExceptionIf task identifier or task factory is null.
IllegalTaskOperationExceptionIf the task identifier is the same as the caller.
TaskExecutionFailedExceptionIf the task execution resulted in an exception.
Convenience function to call runTaskResult(TaskIdentifier, TaskFactory<R>, TaskExecutionParameters) with the default task execution parameters.
taskidThe task identifier for the task to run.
taskfactoryThe task factory of the task.
The result of the task execution.
NullPointerExceptionIf any of the arguments are null.
TaskExecutionFailedExceptionIf the task execution resulted in an exception.
IllegalTaskOperationExceptionIf the task identifier is the same as the caller.
Starts a task and waits for its execution to complete.

A task dependency will be added for the started task with the same rules as in TaskContext.getTaskResult(TaskIdentifier).

taskidThe task identifier for the task to run.
taskfactoryThe task factory of the task.
parametersThe task execution parameters, or null to use the defaults.
The result of the task execution.
TaskIdentifierConflictExceptionIf a task with the same identifier is already started and the task factories does not equal.
NullPointerExceptionIf task identifier or task factory is null.
TaskExecutionFailedExceptionIf the task execution resulted in an exception.
IllegalTaskOperationExceptionIf the task identifier is the same as the caller.
Convenience function to call TaskContext.startTask(TaskIdentifier, TaskFactory<R>, TaskExecutionParameters).

This method returns no result.

taskThe launch arguments of the task.
TaskIdentifierConflictExceptionIf a task with the same identifier is already started and the task factories does not equal.
NullPointerExceptionIf any of the arguments are null.
IllegalTaskOperationExceptionIf the task identifier is the same as the caller.
Convenience function to call TaskContext.startTask(TaskIdentifier, TaskFactory<R>, TaskExecutionParameters) with the default task execution parameters.

This method returns no result.

taskidThe task identifier for the task to run.
taskfactoryThe task factory of the task.
TaskIdentifierConflictExceptionIf a task with the same identifier is already started and the task factories does not equal.
NullPointerExceptionIf any of the arguments are null.
IllegalTaskOperationExceptionIf the task identifier is the same as the caller.
RThe result type of the task
taskThe launch arguments of the task.
A future handle for the started task.
TaskIdentifierConflictExceptionIf a task with the same identifier is already started and the task factories does not equal.
NullPointerExceptionIf any of the arguments are null.
IllegalTaskOperationExceptionIf the task identifier is the same as the caller.
Convenience function to call TaskContext.startTask(TaskIdentifier, TaskFactory<R>, TaskExecutionParameters) with the default task execution parameters.
RThe result type of the task
taskidThe task identifier for the task to run.
taskfactoryThe task factory of the task.
A future handle for the started task.
TaskIdentifierConflictExceptionIf a task with the same identifier is already started and the task factories does not equal.
NullPointerExceptionIf any of the arguments are null.
IllegalTaskOperationExceptionIf the task identifier is the same as the caller.
Batch function for starting tasks specified by the launch arguments.

This function starts every task with the parameters specified by each launch arguments.

This function works the same way as if startTask(TaskLaunchArguments<?>) was called for each element in the argument.

This function returns void, to retrieve the futures for the started tasks as well, use startTasksFuture(Iterable<extends TaskLaunchArguments<?>>).

tasksThe tasks to start.
TaskIdentifierConflictExceptionIf a task with the same identifier is already started and the task factories does not equal.
NullPointerExceptionIf any of the arguments or elements are null.
IllegalTaskOperationExceptionIf a task identifier is the same as the caller.
Batch function for starting multiple tasks.

The started tasks will use the default execution parameters.

This function works the same way as startTasks(Map<extends TaskIdentifier, ? extends TaskFactory<?>>, TaskExecutionParameters) with null execution parameters.

tasksThe collection of tasks to start.
TaskIdentifierConflictExceptionIf a task with the same identifier is already started and the task factories does not equal.
NullPointerExceptionIf any of the arguments or elements are null.
IllegalTaskOperationExceptionIf a task identifier is the same as the caller.
Batch function for starting multiple tasks with the specified execution parameters.

The passed execution parameters will be used for each started task. If null, the default parameters will be used.

tasksThe collection of tasks to start.
parametersThe execution parameter to start the tasks with.
TaskIdentifierConflictExceptionIf a task with the same identifier is already started and the task factories does not equal.
NullPointerExceptionIf any of the arguments or elements are null.
IllegalTaskOperationExceptionIf a task identifier is the same as the caller.
Batch function for starting tasks with the specified launch arguments and retrieving the futures for them.

This function works the same way as if startTaskFuture(TaskLaunchArguments<R>) was called for each element in the argument.

The returned list of task futures will have the same order as the argument iterable.

tasksThe tasks to start
The futures for the started tasks in the same order as the argument iterable.
TaskIdentifierConflictExceptionIf a task with the same identifier is already started and the task factories does not equal.
NullPointerExceptionIf any of the arguments or elements are null.
IllegalTaskOperationExceptionIf a task identifier is the same as the caller.
Executes synchronization of files from the given source path to the specified target path.

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.

sourceThe source path key.
targetThe synchronization target path key.
syncflagThe synchronization flags. 0, or any of the SYNCHRONIZE_FLAG_* constants in the class.
The content descriptor that is associated with the synchronized contents.
IOExceptionIn case of I/O error.
NullPointerExceptionIf any of the arguments are null.
Converts the given files to a map with their retrieved paths as keys and content descriptors as values.

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.

filesThe files to map to their paths and contents.
A new map of paths mapped to the corresponding content descriptors.
NullPointerExceptionIf the files or any of its elements are null.
Converts the given files to a map with their retrieved paths as keys.

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.

filesThe files to map to their paths.
A new map of paths mapped to the corresponding files.
NullPointerExceptionIf the files or any of its elements are null.
Writes the contents of the file to the specified output stream.

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

fileThe file.
osThe output stream to write the contents of the file to.
IOExceptionIn case of I/O error.
NullPointerExceptionIf any of the arguments are null.
public abstract void writeTo(SakerFile file, ByteSink os) throws IOException, NullPointerException
Writes the contents of the file to the specified byte sink.

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

fileThe file.
osThe byte sink to write the contents of the file to.
IOExceptionIn case of I/O error.
NullPointerExceptionIf any of the arguments are null.