saker.build Documentation TaskDoc JavaDoc Packages
public class SakerPathFiles
Utility class holding methods for manipulating, querying and working with files.

The methods which provide utility functions for paths and sorted sets/maps containing them are implemented efficiently, meaning they will rarely require more time complexity than O(lookup) where lookup is the time it takes to look up an element in a sorted set/map. Unless noted otherwise, these functions expect the parameter sets/maps to be sorted by the natural order.

Methods
public static ByteArrayRegion
Gets the raw byte contents of the file, implicitly synchronizing the file using the specified content database.
public static NavigableMap<String, ContentDescriptor>
Gets the content descriptors of the children of the specified directory.
public static String
Gets the string contents of the file, implicitly synchronizing the file using the specified content database.
public static NavigableMap<SakerPath, SakerFile>
Gets the children of the specified directory by resolving the names against the current path of the directory.
public static NavigableMap<SakerPath, SakerFile>
Gets the children of the specified directory by resolving the names against the specified path.
public static NavigableMap<SakerPath, SakerFile>
Gets the children in the specified directory tree.
public static NavigableMap<SakerPath, SakerFile>
Gets the children in the specified directory tree using the given predicate.
public static NavigableMap<SakerPath, SakerFile>
Gets the all of the children in the specified directory tree, resolving the relative paths against the argument.
public static ProviderHolderPathKey
Gets the path key for a local path.
public static ProviderHolderPathKey
Gets the path key for a file provider and corresponding path.
public static SakerPath
Gets the path or any of its parent which is contained in a set for a specified path.
public static <V> Entry<SakerPath, V>
Gets the entry for the path path or any of its parent which is contained in a map for a specified path.
public static <V> NavigableMap<SakerPath, V>
Gets a submap of the argument which only contains entries that are mapped to a absolute path.
public static <V> NavigableMap<SakerPath, V>
getPathSubMapDirectoryChildren(NavigableMap<SakerPath, V> paths, SakerPath dirpath, boolean includedirectory)
Gets a submap of the argument which only contains entries with keys that start with the argument directory path.
public static <V> ConcurrentNavigableMap<SakerPath, V>
getPathSubMapDirectoryChildren(ConcurrentNavigableMap<SakerPath, V> paths, SakerPath dirpath, boolean includedirectory)
Gets a submap of the argument which only contains entries with keys that start with the argument directory path.
public static <V> NavigableMap<SakerPath, V>
Gets a submap of the argument which only contains entries that are mapped to a relative path.
public static NavigableSet<SakerPath>
Gets a subset of the argument paths which only contain absolute paths.
public static NavigableSet<SakerPath>
getPathSubSetDirectoryChildren(NavigableSet<SakerPath> paths, SakerPath dirpath, boolean includedirectory)
Gets a subset of the argument which only contains paths that only contain paths that start with the argument directory path.
public static NavigableSet<SakerPath>
Gets a subset of the argument paths which only contain relative paths.
public static SortedSet<SakerPath>
Gets a subset of the argument paths which only contain relative paths.
public static RootFileProviderKey
Gets the root file provider key of a file provider by unwrapping it according the wrapping rules of file providers.
public static boolean
hasAbsolutePath(SortedMap<extends SakerPath, ?> paths)
Checks if the argument map contains any absolute path key.
public static boolean
Checks if the argument set contains any absolute path element.
public static boolean
Checks if the specified path set doesn't contain paths which have different roots.
public static boolean
Checks if the argument sorted path set has any non-forward relative path.
public static boolean
Checks if the argument pahts set contains the specified path, or any parent path of it.
public static boolean
Checks if the argument set contains the specified test path, or any subpath of it.
public static boolean
hasRelativePath(SortedMap<extends SakerPath, ?> paths)
Checks if the argument map contains any relative path keys.
public static boolean
Checks if the argument set contains any relative path element.
public static boolean
Checks if the argument set contains at least one path that is a subpath of the specified test path.
public static boolean
Checks if all key paths in the argument map starts with the specified base path.
public static boolean
Checks if all paths in the argument set starts with the specified base path.
public static boolean
Checks if the argument sorted path set consists only of forward relative paths.
public static boolean
Checks if a specified file path is a direct children of a directory path.
public static boolean
isSamePaths(SakerFileProvider fileprovider, SakerPath path, Path localpath)
Checks if the specified path with the given file provider has the same location as the argument local path.
public static boolean
isSamePaths(SakerFileProvider fileprovider, SakerPath path, PathKey pathkey)
Checks if a location specified by a file provider and absolute path is same as the given path key.
public static boolean
isSamePaths(SakerFileProvider firstprovider, SakerPath firstpath, SakerFileProvider secondprovider, SakerPath secondpath)
Checks if the specified file provider-path pair point to the same location.
public static boolean
Checks if the argument file provider keys are the same.
public static boolean
Checks if the file provider key represents the file provider as the file provider argument.
public static boolean
Checks if the argument file providers operate on the same files.
public static boolean
isSubPath(PathKey basepath, PathKey path)
Checks if the argument path key operate on the same file providers, and the second path is a subpath of the first (base) path.
public static boolean
isSubPath(SakerFileProvider baseprovider, SakerPath basepath, SakerFileProvider provider, SakerPath path)
Tests if second file provider-path pair is a subpath of the first base pair.
public static int
Comparator function for comparing the argument files by their name.
public static InputStream
Opens an input stream to the contents of the file, implicitly synchronizing the file using the specified content database.
public static final void
Pretty prints a file hierarchy to the specified stream.
public static <V> NavigableMap<SakerPath, V>
Converts a map by taking the subpath of the keys for a given path base.
public static NavigableSet<SakerPath>
Converts a path set by taking the subpath of the paths for a given path base.
public static Path
Validation method for ensuring that the specified path is absolute.
public static SakerPath
Validation method for ensuring that the specified file is available through an absolute path.
public static SakerPath
Validation method for ensuring that the specified path is absolute.
public static SakerDirectory
Validation method for ensuring that the execution has a build directory configured for it.
public static SakerDirectory
Validation method for ensuring that the task has a build directory configured for it.
public static SakerPath
Validation method for ensuring that the task has a build directory path configured for it.
public static String
Validation method for ensuring that the specified path has a valid file name.
public static SakerPath
Validation method for ensuring that a specified path has a non-null parent.
public static Path
Validation method for ensuring that the specified path is relative.
public static SakerPath
Validation method for ensuring that the specified file is available through a relative path.
public static SakerPath
Validation method for ensuring that the specified path is relative.
public static SakerFileProvider
Validation method for ensuring that the specified file provider is a root file provider.
public static RootFileProviderKey
Validation method for ensuring that the specified file provider is a root file provider.
public static String
Validation method for a file name according to the rules of FileHandle.getName().
public static SakerFile
resolve(SakerDirectory dir, String childname)
Resolves a file or directory name against the specified directory.
public static SakerFile
Resolves a file or directory using the given absolute path.
public static SakerFile
resolveAtPath(ExecutionDirectoryContext executiondirectorycontext, SakerDirectory basedir, SakerPath path)
Same as resolveAtPath(TaskContext, SakerPath), but uses the specified base directory to resolve relative paths.
public static SakerFile
Resolves a file or directory at the given path.
public static SakerFile
Resolves a file or directory using the given relative path against a base directory.
public static SakerFile
Resolves a file or directory with the given path names against a base directory.
public static SakerDirectory
Resolves a directory name on the specified directory.
public static SakerDirectory
Resolves a directory using the given absolute path.
public static SakerDirectory
Resolves a directory using the given absolute path, creating it if necessary, overwriting already existing files.
public static SakerDirectory
Resolves a directory using the given absolute path, creating it if possible.
public static SakerDirectory
Same as resolveDirectoryAtPath(TaskContext, SakerPath), but uses the specified base directory to resolve relative paths.
public static SakerDirectory
Resolves a directory at a given path.
public static SakerDirectory
Same as resolveDirectoryAtPathCreate(TaskContext, SakerPath), but uses the specified base directory to resolve relative paths.
public static SakerDirectory
Resolves a directory at a given path, creating it if necessary, overwriting already existing files.
public static SakerDirectory
Same as resolveDirectoryAtPathCreateIfAbsent(TaskContext, SakerPath), but uses the specified base directory to resolve relative paths.
public static SakerDirectory
Resolves a directory at a given path, creating it if possible.
public static SakerDirectory
Resolves a directory using the given relative path against a base directory.
public static SakerDirectory
Resolves a directory using the given relative path against a base directory, creating it if necessary, overwriting already existing files.
public static SakerDirectory
Resolves a directory using the given relative path against a base directory, creating it if possible.
public static SakerDirectory
Resolves a directory with the given path names against a base directory.
public static SakerDirectory
Resolves a directory with the given path names against a base directory, creating it if necessary, overwriting already existing files.
public static SakerDirectory
Resolves a directory with the given path names against a base directory, creating it if possible.
public static SakerDirectory
Resolves a directory name on the specified directory, creating if necessary.
public static SakerDirectory
Resolves a directory name on the specified directory, creating if possible.
public static SakerFile
Resolves a file but not a directory name on the specified directory.
public static SakerFile
Resolves a file but not a directory using the given absolute path.
public static SakerFile
resolveFileAtPath(ExecutionDirectoryContext executiondirectorycontext, SakerDirectory basedir, SakerPath path)
Same as resolveFileAtPath(TaskContext, SakerPath), but uses the specified base directory to resolve relative paths.
public static SakerFile
Resolves a file but not a directory at the given path.
public static SakerFile
Resolves a file but not a directory using the given relative path against a base directory.
public static SakerFile
Resolves a file but not a directory with the given path names against a base directory.
public static void
Executes the synchronization of a directory to its denoted path using the given content database and synchronization predicate.
public static void
Executes the synchronization of a directory to its denoted path using the given content database.
public static void
Executes the synchronization of a directory to the given path using the given content database and synchronization predicate.
public static void
Executes the synchronization of a file (but not a directory) to its denoted path using the given content database.
public static void
Executes the synchronization of a file (but not a directory) to the specified path using the given content database.
public static SakerPath
Converts the argument to an absolute path by optionally resolving it against the working directory of the task context.
public static <K> NavigableMap<K, ContentDescriptor>
Transforms the parameter map by taking the content descriptor of the values.
public static NavigableMap<SakerPath, ContentDescriptor>
Converts the given files to a map with their retrieved paths as keys and content descriptors as values.
public static NavigableMap<SakerPath, SakerFile>
toPathFileMap(Iterable<extends SakerFile> files)
Converts the given files to a map with their retrieved paths as keys.
public static String
Converts the argument path to a relative string if possible.
public static void
Writes the contents of the file to the parameter stream, implicitly synchronizing the file using the specified content database.
Gets the raw byte contents of the file, implicitly synchronizing the file using the specified content database.

It is recommended that users call TaskExecutionUtilities.getBytes(SakerFile) instead.

fileThe file to write the contents of.
dbThe content database for implicit synchronization. May be null to skip implicit synchronization.
The byte contents of the file.
IOExceptionIn case of I/O error.
NullPointerExceptionIf file is null.
Gets the content descriptors of the children of the specified directory.

Works the same way as TaskExecutionUtilities.getChildrenFileContents(SakerDirectory), and it is recommended for tasks to call that instead.

dirThe directory.
A new map of file names mapped to their content descriptors.
NullPointerExceptionIf the directory is null.
Gets the string contents of the file, implicitly synchronizing the file using the specified content database.

It is recommended that users call TaskExecutionUtilities.getContent(SakerFile) instead.

Unless the file reports getting the bytes efficient, this method gets the raw bytes of the file and decodes them as UTF-8.

fileThe file to write the contents of.
dbThe content database for implicit synchronization. May be null to skip implicit synchronization.
The character contents of the file.
IOExceptionIn case of I/O error.
NullPointerExceptionIf file is null.
Gets the children of the specified directory by resolving the names against the current path of the directory.

Only the direct children of the directory is included.

This method works in the same way as if SakerDirectory.getChildren() was called, and every entry key is resolved against the directory path.

Same as:

 getDirectoryChildrenByPath(dir, dir.getSakerPath())
 
dirThe directory.
The direct children of the directory mapped to their names resolved against the directory path.
NullPointerExceptionIf the directory is null.
Gets the children of the specified directory by resolving the names against the specified path.

Only the direct children of the directory is included.

This method works in the same way as if SakerDirectory.getChildren() was called, and every entry key is resolved against the base path.

dirThe directory.
basepathThe path to resolve the directory child names against.
The direct children of the directory mapped to their names resolved against the base path.
NullPointerExceptionIf any of the arguments are null.
Gets the children in the specified directory tree.

The result map will have the files mapped to a relative path compared to the argument directory. Any file that is a direct child of the directory will have a relative path with a single path name as their key.

This is a convenience function for calling:

 dir.getFilesRecursiveByPath(SakerPath.EMPTY, DirectoryVisitPredicate.everything())
 
dirThe directory to collect the children of.
The collected children. The returned map is mutable.
NullPointerExceptionIf the directory is null.
Gets the children in the specified directory tree using the given predicate.

This is a convenience function for calling:

 dir.getFilesRecursiveByPath(SakerPath.EMPTY, predicate)
 
dirThe directory to collect the children of.
predicateThe predicate to define the files to visit. If this is null, DirectoryVisitPredicate.everything() will be used.
The collected children. The returned map is mutable.
NullPointerExceptionIf the directory is null.
Gets the all of the children in the specified directory tree, resolving the relative paths against the argument.

This is a convenience function for calling:

 dir.getFilesRecursiveByPath(basepath, DirectoryVisitPredicate.everything())
 
dirThe directory to collect the children of.
basepathThe base path to resolve the relative paths agains.
The collected children. The returned map is mutable.
NullPointerExceptionIf any of the arguments are null.
Gets the path key for a local path.

Same as:

 LocalFileProvider.getInstance().getPathKey(path)
 
pathThe path to get the path key for.
The created path key.
NullPointerExceptionIf the argument is null.
InvalidPathFormatExceptionIf the path is not absolute, or not associated with the default file system.
Gets the path key for a file provider and corresponding path.
fileproviderThe file provider.
pathThe path.
The created path key.
NullPointerExceptionIf any argument is null.
Gets the path or any of its parent which is contained in a set for a specified path.

The argument must be naturally ordered.

pathsThe paths.
pathThe path to search for.
The found path which is either the same as the argument path, or any parent of it, or null if not found.
public static <V> Entry<SakerPath, V> getPathOrParentEntry(NavigableMap<SakerPath, V> paths, SakerPath path)
Gets the entry for the path path or any of its parent which is contained in a map for a specified path.

The argument must be naturally ordered.

VThe value type of the map.
pathsThe paths.
pathThe path to search for.
The found entry for the path which is either the same as the argument path, or any parent of it, or null if not found.
Gets a submap of the argument which only contains entries that are mapped to a absolute path.

The argument must be naturally ordered.

VThe value type of the map.
pathsThe path map.
A submap of the argument which only contains entries that are mapped to a absolute path.
NullPointerExceptionIf the argument is null.
public static <V> NavigableMap<SakerPath, V> getPathSubMapDirectoryChildren(NavigableMap<SakerPath, V> paths, SakerPath dirpath, boolean includedirectory) throws NullPointerException
Gets a submap of the argument which only contains entries with keys that start with the argument directory path.

The argument must be naturally ordered.

VThe value type of the map.
pathsThe paths.
dirpathThe directory base path.
includedirectoryboolean indicating whether to include the directory base path in the result subset or not.
The submap which only contains entries with keys that start with the specified directory base path.
NullPointerExceptionIf any of the arguments are null.
public static <V> ConcurrentNavigableMap<SakerPath, V> getPathSubMapDirectoryChildren(ConcurrentNavigableMap<SakerPath, V> paths, SakerPath dirpath, boolean includedirectory) throws NullPointerException
Gets a submap of the argument which only contains entries with keys that start with the argument directory path.

The argument must be naturally ordered.

This method is same as getPathSubMapDirectoryChildren(NavigableMap<SakerPath, V>, SakerPath, boolean), but is specialized for concurrent navigable maps.

VThe value type of the map.
pathsThe paths.
dirpathThe directory base path.
includedirectoryboolean indicating whether to include the directory base path in the result subset or not.
The submap which only contains entries with keys that start with the specified directory base path.
NullPointerExceptionIf any of the arguments are null.
Gets a submap of the argument which only contains entries that are mapped to a relative path.

The argument must be naturally ordered.

VThe value type of the map.
pathsThe path map.
A submap of the argument which only contains entries that are mapped to a relative path.
NullPointerExceptionIf the argument is null.
Gets a subset of the argument paths which only contain absolute paths.

The argument must be naturally ordered.

pathsThe paths.
A subset of the argument which only contains the absolute paths of the argument.
NullPointerExceptionIf the argument is null.
public static NavigableSet<SakerPath> getPathSubSetDirectoryChildren(NavigableSet<SakerPath> paths, SakerPath dirpath, boolean includedirectory) throws NullPointerException
Gets a subset of the argument which only contains paths that only contain paths that start with the argument directory path.

The argument must be naturally ordered.

pathsThe paths.
dirpathThe directory base path.
includedirectoryboolean indicating whether to include the directory base path in the result subset or not.
The subset which only contains paths that start with the specified directory base path.
NullPointerExceptionIf any of the arguments are null.
Gets a subset of the argument paths which only contain relative paths.

The argument must be naturally ordered.

pathsThe paths.
A subset of the argument which only contains the relative paths of the argument.
NullPointerExceptionIf the argument is null.
Gets a subset of the argument paths which only contain relative paths.

The argument must be naturally ordered.

pathsThe paths.
A subset of the argument which only contains the relative paths of the argument.
NullPointerExceptionIf the argument is null.
Gets the root file provider key of a file provider by unwrapping it according the wrapping rules of file providers.
providerThe file provider.
The root file provider key of the last file provider.
NullPointerExceptionIf the file provider is null.
public static boolean hasAbsolutePath(SortedMap<extends SakerPath, ?> paths)
Checks if the argument map contains any absolute path key.

The argument must be naturally ordered.

If the argument is empty, false is returned.

pathsThe paths.
true if the argument contains at least one absolute path.
public static boolean hasAbsolutePath(SortedSet<extends SakerPath> paths)
Checks if the argument set contains any absolute path element.

The argument must be naturally ordered.

If the argument is empty, false is returned.

pathsThe paths.
true if the argument contains at least one absolute path.
public static boolean hasDifferentRootedPaths(SortedSet<extends SakerPath> paths)
Checks if the specified path set doesn't contain paths which have different roots.

The argument must be naturally ordered.

If the argument is empty, then false is returned as it satisfies the condition.

pathsThe paths.
true if all of the paths in the set have the same root.
public static boolean hasNonForwardRelative(SortedSet<SakerPath> paths)
Checks if the argument sorted path set has any non-forward relative path.

If there is an absolute path in the set, the result will be true.

Empty argument will result in false.

In any other cases if there is a path in it that starts with "..", true is returned.

pathsThe paths to examine.
true if there is at least one not forward relative path in the set.
public static boolean hasPathOrParent(NavigableSet<SakerPath> paths, SakerPath path)
Checks if the argument pahts set contains the specified path, or any parent path of it.

The argument must be naturally ordered.

pathsThe paths.
pathThe path to search for.
true if the set contains the path or any of its parent.
public static boolean hasPathOrSubPath(NavigableSet<SakerPath> paths, SakerPath testpath)
Checks if the argument set contains the specified test path, or any subpath of it.

The argument must be naturally ordered.

pathsThe paths.
testpathThe test path to check inclusion and subpaths for.
true if the set contains the path or there is at least one subpath in it.
public static boolean hasRelativePath(SortedMap<extends SakerPath, ?> paths)
Checks if the argument map contains any relative path keys.

The argument must be naturally ordered.

If the argument is empty, false is returned.

pathsThe paths.
true if the argument contains at least one relative path.
public static boolean hasRelativePath(SortedSet<extends SakerPath> paths)
Checks if the argument set contains any relative path element.

The argument must be naturally ordered.

If the argument is empty, false is returned.

pathsThe paths.
true if the argument contains at least one relative path.
public static boolean hasSubPath(NavigableSet<SakerPath> paths, SakerPath testpath)
Checks if the argument set contains at least one path that is a subpath of the specified test path.

The argument must be naturally ordered.

pathsThe paths.
testpathThe test path to check subpaths for.
true if there is at least one subpath in the set.
public static boolean isAllSubPath(SortedMap<SakerPath, ?> paths, SakerPath base)
Checks if all key paths in the argument map starts with the specified base path.

The argument must be naturally ordered.

If the path map is empty, true is returned.

pathsThe paths.
baseThe base path to check the paths agains.
true if all paths in the map start with the base path argument.
public static boolean isAllSubPath(SortedSet<SakerPath> paths, SakerPath base)
Checks if all paths in the argument set starts with the specified base path.

The argument must be naturally ordered.

If the path set is empty, true is returned.

pathsThe paths.
baseThe base path to check the paths agains.
true if all paths in the set start with the base path argument.
public static boolean isOnlyForwardRelatives(SortedSet<SakerPath> paths)
Checks if the argument sorted path set consists only of forward relative paths.

If the argument is empty, the result is true.

If the argument contains an absolute path, the result is false.

If the argument contains a path that is not forward relative, the result is false.

pathsThe paths to examine.
true if all of the paths in the argument set are forward relative.
public static boolean isPathInDirectory(SakerPath directory, SakerPath file)
Checks if a specified file path is a direct children of a directory path.

This method returns true if and only if the file path starts with the directory path, and the path name count of the file is one greater than the directory path name count.

directoryThe directory path.
fileThe file path.
true, if the path for the file is a direct child path of the directory.
public static boolean isSamePaths(SakerFileProvider fileprovider, SakerPath path, Path localpath) throws NullPointerException, InvalidPathFormatException
Checks if the specified path with the given file provider has the same location as the argument local path.

The file system of the argument Path object is not taken into account. It is always interpreted as a path on the local file system.

fileproviderThe file provider for the path.
pathThe path.
localpathThe local path to compare against.
true if they represent the same file location.
NullPointerExceptionIf any of the arguments are null.
InvalidPathFormatExceptionIf the paths are not absolute.
public static boolean isSamePaths(SakerFileProvider fileprovider, SakerPath path, PathKey pathkey) throws NullPointerException, InvalidPathFormatException
Checks if a location specified by a file provider and absolute path is same as the given path key.
fileproviderThe file provider for the path.
pathThe path.
pathkeyThe location to compare the path against.
true if they represent the same file location.
NullPointerExceptionIf any of the arguments are null.
InvalidPathFormatExceptionIf the path is not absolute.
public static boolean isSamePaths(SakerFileProvider firstprovider, SakerPath firstpath, SakerFileProvider secondprovider, SakerPath secondpath) throws NullPointerException, InvalidPathFormatException
Checks if the specified file provider-path pair point to the same location.
firstproviderThe file provider for the first path.
firstpathThe first path.
secondproviderThe file provider for the second path.
secondpathThe second path.
true if they represent the same file location.
NullPointerExceptionIf any of the arguments are null.
InvalidPathFormatExceptionIf the path arguments are not absolute.
public static boolean isSameProvider(FileProviderKey key1, FileProviderKey key2) throws NullPointerException
Checks if the argument file provider keys are the same.

The keys are checked for equality.

key1The first key.
key2The second key.
true if the keys equal.
NullPointerExceptionIf any of the arguments are null.
public static boolean isSameProvider(FileProviderKey key, SakerFileProvider fileprovider) throws NullPointerException
Checks if the file provider key represents the file provider as the file provider argument.

The key is checked for equality against the key of the argument file provider.

keyThe file provider key.
fileproviderThe file provider.
true if the key equals to the key of the file provider.
NullPointerExceptionIf any of the arguments are null.
public static boolean isSameProvider(SakerFileProvider provider1, SakerFileProvider provider2) throws NullPointerException
Checks if the argument file providers operate on the same files.

Their file provider keys are checked for equality.

provider1The first file provider.
provider2The second file provider.
true if their file provider keys equal.
NullPointerExceptionIf any of the arguments are null.
public static boolean isSubPath(PathKey basepath, PathKey path) throws NullPointerException
Checks if the argument path key operate on the same file providers, and the second path is a subpath of the first (base) path.
basepathThe base path.
pathThe path to check if it is a subpath ot the base path.
true if the paths are associated with the same file providers, and the second path is a subpath of the first.
NullPointerExceptionIf any of the arguments are null.
public static boolean isSubPath(SakerFileProvider baseprovider, SakerPath basepath, SakerFileProvider provider, SakerPath path) throws NullPointerException, InvalidPathFormatException
Tests if second file provider-path pair is a subpath of the first base pair.
baseproviderThe base path file provider.
basepathThe base path.
providerThe test path file provider.
pathThe test path.
true if the second path is a subpath of the first.
NullPointerExceptionIf any of the arguments are null.
InvalidPathFormatExceptionIf the paths are not absolute.
public static int nameComparator(SakerFile left, SakerFile right)
Comparator function for comparing the argument files by their name.
leftThe first file.
rightThe second file.
The comparion result of their names.
Opens an input stream to the contents of the file, implicitly synchronizing the file using the specified content database.

It is recommended that users call TaskExecutionUtilities.openInputStream(SakerFile) instead.

fileThe file to write the contents of.
dbThe content database for implicit synchronization. May be null to skip implicit synchronization.
An opened stream for the file contents.
IOExceptionIn case of I/O error.
NullPointerExceptionIf file is null.
public static final void prettyPrintRecursive(PrintStream ps, SakerFile file)
Pretty prints a file hierarchy to the specified stream.

If the file is a directory, the children and their children recursively will be printed, and indented in the output.

The file name, its identity hash, and the classname is printed to the output.

psThe stream.
fileThe file.
Converts a map by taking the subpath of the keys for a given path base.

The argument must be naturally ordered.

VThe value type of the map.
pathsThe paths map to convert.
baseThe path base for taking the subpaths of the keys.
The converted map, where every key is relative to the base path.
IllegalArgumentExceptionIf not all key in the map is a subpath of the path base.
Converts a path set by taking the subpath of the paths for a given path base.

The argument must be naturally ordered.

pathsThe paths set to convert.
baseThe path base for taking the subpaths of the elements.
The converted set, where every element is relative to the base path.
IllegalArgumentExceptionIf not all element in the set is a subpath of the path base.
Validation method for ensuring that the specified path is absolute.
pathThe path.
The path argument.
InvalidPathFormatExceptionIf the path is not absolute.
NullPointerExceptionIf the argument is null.
Validation method for ensuring that the specified file is available through an absolute path.

A file has an absolute path if and only if it has every parent until one of the root directories for the execution, or is a root directory itself.

fileThe file.
The absolute path of the file.
InvalidPathFormatExceptionIf the path for the file is not absolute.
NullPointerExceptionIf the argument is null.
Validation method for ensuring that the specified path is absolute.
pathThe path.
The path argument.
InvalidPathFormatExceptionIf the path is not absolute.
NullPointerExceptionIf the argument is null.
Validation method for ensuring that the execution has a build directory configured for it.
executiondircontextThe execution directory context.
The build directory.
MissingConfigurationExceptionIf the build directory is not available for the execution.
NullPointerExceptionIf the argument is null.
Validation method for ensuring that the task has a build directory configured for it.
taskdircontextThe task directory context.
The build directory.
MissingConfigurationExceptionIf the build directory is not available for the task.
NullPointerExceptionIf the argument is null.
Validation method for ensuring that the task has a build directory path configured for it.
taskdircontextThe task directory path context.
The build directory path.
MissingConfigurationExceptionIf the build directory is not available for the task.
NullPointerExceptionIf the argument is null.
Validation method for ensuring that the specified path has a valid file name.
pathThe path.
The file name of the path.
InvalidPathFormatExceptionIf the path has no valid file name.
NullPointerExceptionIf the argument is null.
Validation method for ensuring that a specified path has a non-null parent.
pathThe path.
The parent of the path.
InvalidPathFormatExceptionIf the path has not parent.
NullPointerExceptionIf path is null.
Validation method for ensuring that the specified path is relative.
pathThe path.
The path argument.
InvalidPathFormatExceptionIf the path is not relative.
NullPointerExceptionIf the argument is null.
Validation method for ensuring that the specified file is available through a relative path.

A file has a relative path if and only if it has no parent, or none of its parents are a root directory of the execution.

fileThe file.
The absolute path of the file.
InvalidPathFormatExceptionIf the path for the file is not relative.
NullPointerExceptionIf the argument is null.
Validation method for ensuring that the specified path is relative.
pathThe path.
The path argument.
InvalidPathFormatExceptionIf the path is not relative.
NullPointerExceptionIf the argument is null.
Validation method for ensuring that the specified file provider is a root file provider.
fileproviderThe file provider.
The file provider argument.
NullPointerExceptionIf the argument is null.
IllegalArgumentExceptionIf the file provider is not a root file provider.
Validation method for ensuring that the specified file provider is a root file provider.
fileproviderThe file provider.
The file provider key of the argument.
NullPointerExceptionIf the argument is null.
IllegalArgumentExceptionIf the file provider is not a root file provider.
Validation method for a file name according to the rules of FileHandle.getName().

The name may not be null, empty, "." or "..", must not contain slash characters ('/', '\\'), and must not contain the colon (':') and semicolon (';') characters.

nameThe file name.
The argument file name.
InvalidPathFormatExceptionIf the file name is not valid.
NullPointerExceptionIf the file name is null.
Resolves a file or directory name against the specified directory.

Tha names "." and ".." are specially handled meaning the directory itself, and its parent respectively.

In any other case a child file of the directory is returned.

dirThe directory.
childnameThe name of the requested child.
The resolved file or null if not found.
NullPointerExceptionIf any of the arguments are null.
InvalidPathFormatExceptionIf the child name has an invalid format.
Resolves a file or directory using the given absolute path.

It is recommended that users call TaskExecutionUtilities.resolveAtAbsolutePath(SakerPath) instead.

executiondirectorycontextThe execution directory context.
pathThe absolute path.
The resolved file or null if not found.
NullPointerExceptionIf the path is null.
InvalidPathFormatExceptionIf the path is not absolute.
public static SakerFile resolveAtPath(ExecutionDirectoryContext executiondirectorycontext, SakerDirectory basedir, SakerPath path) throws NullPointerException
Same as resolveAtPath(TaskContext, SakerPath), but uses the specified base directory to resolve relative paths.

It is recommended that users call TaskExecutionUtilities.resolveAtPath(SakerDirectory, SakerPath) instead.

executiondirectorycontextThe execution directory context.
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, or path is absolute and execution directory context is null.
public static SakerFile resolveAtPath(TaskContext taskcontext, SakerPath path) throws NullPointerException
Resolves a file or directory at the given path.

It is recommended that users call TaskExecutionUtilities.resolveAtPath(SakerPath) instead.

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.

taskcontextThe task context.
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.

It is recommended that users call TaskExecutionUtilities.resolveAtRelativePath(SakerDirectory, SakerPath) instead.

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.

It is recommended that users call TaskExecutionUtilities.resolveAtRelativePathNames(SakerDirectory, Iterable<extends String>) instead.

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 name on the specified directory.

Tha names "." and ".." are specially handled meaning the directory itself, and its parent respectively.

If the specified child of the directory is not a directory instance, then null is returned.

In any other case a child directory of the directory is returned.

dirThe directory.
childnameThe name of the requested child.
The resolved directory or null if a directory was not found for the name.
NullPointerExceptionIf any of the arguments are null.
InvalidPathFormatExceptionIf the child name has an invalid format.
Resolves a directory using the given absolute path.

It is recommended that users call TaskExecutionUtilities.resolveDirectoryAtAbsolutePath(SakerPath) instead.

executiondirectorycontextThe execution directory context.
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.

It is recommended that users call TaskExecutionUtilities.resolveDirectoryAtAbsolutePathCreate(SakerPath) instead.

executiondirectorycontextThe execution directory context.
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.

It is recommended that users call TaskExecutionUtilities.resolveDirectoryAtAbsolutePathCreateIfAbsent(SakerPath) instead.

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

executiondirectorycontextThe execution directory context.
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(TaskContext, SakerPath), but uses the specified base directory to resolve relative paths.

It is recommended that users call TaskExecutionUtilities.resolveDirectoryAtPath(SakerDirectory, SakerPath) instead.

executiondirectorycontextThe execution directory context.
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, or path is absolute and execution directory context is null.
Resolves a directory at a given path.

It is recommended that users call TaskExecutionUtilities.resolveDirectoryAtPath(SakerPath) instead.

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.

taskcontextThe task context.
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(TaskContext, SakerPath), but uses the specified base directory to resolve relative paths.

It is recommended that users call TaskExecutionUtilities.resolveDirectoryAtPathCreate(SakerDirectory, SakerPath) instead.

executiondirectorycontextThe execution directory context.
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, or path is absolute and execution directory context is null.
Resolves a directory at a given path, creating it if necessary, overwriting already existing files.

It is recommended that users call TaskExecutionUtilities.resolveDirectoryAtPathCreate(SakerPath) instead.

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.

taskcontextThe task context.
pathThe path to resolve.
The directory at the given path.
NullPointerExceptionIf the path is null.
Same as resolveDirectoryAtPathCreateIfAbsent(TaskContext, SakerPath), but uses the specified base directory to resolve relative paths.

It is recommended that users call TaskExecutionUtilities.resolveDirectoryAtPathCreateIfAbsent(SakerDirectory, SakerPath) instead.

executiondirectorycontextThe execution directory context.
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, or path is absolute and execution directory context is null.
Resolves a directory at a given path, creating it if possible.

It is recommended that users call TaskExecutionUtilities.resolveDirectoryAtPathCreateIfAbsent(SakerPath) instead.

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.

taskcontextThe task context.
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.

It is recommended that users call TaskExecutionUtilities.resolveDirectoryAtRelativePath(SakerDirectory, SakerPath) instead.

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.

It is recommended that users call TaskExecutionUtilities.resolveDirectoryAtRelativePathCreate(SakerDirectory, SakerPath) instead.

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.

It is recommended that users call TaskExecutionUtilities.resolveDirectoryAtRelativePathCreateIfAbsent(SakerDirectory, SakerPath) instead.

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.

It is recommended that users call TaskExecutionUtilities.resolveDirectoryAtRelativePathNames(SakerDirectory, Iterable<extends String>) instead.

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.

It is recommended that users call TaskExecutionUtilities.resolveDirectoryAtRelativePathNamesCreate(SakerDirectory, Iterable<extends String>) instead.

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.

It is recommended that users call TaskExecutionUtilities.resolveDirectoryAtRelativePathNamesCreateIfAbsent(SakerDirectory, Iterable<extends String>) instead.

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 directory name on the specified directory, creating if necessary.

Tha names "." and ".." are specially handled meaning the directory itself, and its parent respectively.

If the file name is ".." and the directory has no parent, null is returned.

In any other case a child directory of the passed directory is returned or created.

dirThe directory.
childnameThe name of the requested child.
The resolved/created directory or null if the file name is ".." and the directory has no parent.
NullPointerExceptionIf any of the arguments are null.
InvalidPathFormatExceptionIf the child name has an invalid format.
Resolves a directory name on the specified directory, creating if possible.

Tha names "." and ".." are specially handled meaning the directory itself, and its parent respectively.

If the specified child of the directory is present and not a directory instance, then null is returned.

If the file name is ".." and the directory has no parent, null is returned.

In any other case a child directory of the passed directory is returned or created.

dirThe directory.
childnameThe name of the requested child.
The resolved/created directory or null if the file name is ".." and the directory has no parent, or failed to create the directory.
NullPointerExceptionIf any of the arguments are null.
InvalidPathFormatExceptionIf the child name has an invalid format.
Resolves a file but not a directory name on the specified directory.

Tha names "." and ".." are specially handled meaning the directory itself, and its parent respectively. In these cases null is returned.

If the specified child of the directory is a directory instance, then null is returned.

In any other case a child file of the directory is returned.

dirThe directory.
childnameThe name of the requested child file.
The resolved file or null if a file was not found for the name or the found file is a directory.
NullPointerExceptionIf any of the arguments are null.
InvalidPathFormatExceptionIf the child name has an invalid format.
Resolves a file but not a directory using the given absolute path.

It is recommended that users call TaskExecutionUtilities.resolveFileAtAbsolutePath(SakerPath) instead.

executiondirectorycontextThe execution directory context.
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.
public static SakerFile resolveFileAtPath(ExecutionDirectoryContext executiondirectorycontext, SakerDirectory basedir, SakerPath path) throws NullPointerException
Same as resolveFileAtPath(TaskContext, SakerPath), but uses the specified base directory to resolve relative paths.

It is recommended that users call TaskExecutionUtilities.resolveFileAtPath(SakerDirectory, SakerPath) instead.

executiondirectorycontextThe execution directory context.
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, or path is absolute and execution directory context is null.
public static SakerFile resolveFileAtPath(TaskContext taskcontext, SakerPath path) throws NullPointerException
Resolves a file but not a directory at the given path.

It is recommended that users call TaskExecutionUtilities.resolveFileAtPath(SakerPath) instead.

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.

taskcontextThe task context.
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.

It is recommended that users call TaskExecutionUtilities.resolveFileAtRelativePath(SakerDirectory, SakerPath) instead.

basedirThe base directory.
pathThe relative path.
The resolved file or null if not found or it's a directory.
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.

It is recommended that users call TaskExecutionUtilities.resolveFileAtRelativePathNames(SakerDirectory, Iterable<extends String>) instead.

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.
Executes the synchronization of a directory to its denoted path using the given content database and synchronization predicate.

The actual path is determined using ContentDatabase.getPathConfiguration().

Clients should not call this method directly, but SakerDirectory.synchronize(DirectoryVisitPredicate) instead.

dirThe directory to synchronize.
synchpredicateThe synchronization predicate to determine which files should be synchronized. Passing null is the same as DirectoryVisitPredicate.everything().
dbThe content database to manage synchronization.
IOExceptionIn case of I/O error, or if the path of the file is relative.
NullPointerExceptionIf any of the arguments except predicate are null.
Executes the synchronization of a directory to its denoted path using the given content database.

The actual path is determined using ContentDatabase.getPathConfiguration().

Clients should not call this method directly, but SakerDirectory.synchronize() instead.

dirThe directory to synchronize.
dbThe content database to manage synchronization.
IOExceptionIn case of I/O error, or if the path of the file is relative.
NullPointerExceptionIf any of the arguments are null.
Executes the synchronization of a directory to the given path using the given content database and synchronization predicate.

Clients should not call this method directly, but SakerDirectory.synchronize(ProviderHolderPathKey, DirectoryVisitPredicate) instead.

dirThe directory to synchronize.
pathkeyThe path to synchronize the directory to.
synchpredicateThe synchronization predicate to determine which files should be synchronized. Passing null is the same as DirectoryVisitPredicate.everything().
dbThe content database to manage synchronization.
IOExceptionIn case of I/O error.
NullPointerExceptionIf any of the arguments except predicate are null.
Executes the synchronization of a file (but not a directory) to its denoted path using the given content database.

The actual path is determined using ContentDatabase.getPathConfiguration().

Clients should not call this method directly, but SakerFile.synchronize() instead.

fileThe file to synchronize.
dbThe content database to manage synchronization.
IOExceptionIn case of I/O error, or if the path of the file is relative.
IllegalArgumentExceptionIf the file is an instance of SakerDirectory.
NullPointerExceptionIf any of the arguments are null.
Executes the synchronization of a file (but not a directory) to the specified path using the given content database.

Clients should not call this method directly, but SakerFile.synchronize(ProviderHolderPathKey) instead.

fileThe file to synchronize.
pathkeyThe path to synchronize the file to.
dbThe content database to manage synchronization.
IOExceptionIn case of I/O error.
IllegalArgumentExceptionIf the file is an instance of SakerDirectory.
NullPointerExceptionIf any of the arguments are null.
public static SakerPath toAbsolutePath(TaskContext taskcontext, SakerPath path) throws NullPointerException
Converts the argument to an absolute path by optionally resolving it against the working directory of the task context.

If the argument path is already absolute, it is returned directly.

taskcontextThe task context.
pathThe path to absolutize.
The path converted to an absolute path.
NullPointerExceptionIf any of the arguments are null.
Transforms the parameter map by taking the content descriptor of the values.

The ordering of the returned map is the same as the argument.

This function has no conterpart in TaskExecutionUtilities. To retrieve content descriptors of files see TaskExecutionUtilities.toPathContentMap(Iterable<extends SakerFile>).

mapThe map to transform.
A new map mapped to the appropriate keys to the corresponding content descriptors of the files.
NullPointerExceptionIf the map or any of the files are null.
Converts the given files to a map with their retrieved paths as keys and content descriptors as values.

Works the same way as TaskExecutionUtilities.toPathContentMap(Iterable<extends SakerFile>), and it is recommended for tasks to call that instead.

filesThe files to retrieve the 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.

Works the same way as TaskExecutionUtilities.toPathFileMap(Iterable<extends SakerFile>), and it is recommended for tasks to call that instead.

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.
Converts the argument path to a relative string if possible.

If the argument is already relative, it will be converted to string directly.

If it is absolute, the method will try to convert it to a relative one by checking if it is under the execution working directory. The resulting path string will be forward relative.

If this method is called from a build execution thread, the configured execution working directory will be used to convert the path to a relative string.

If the path is not a subpath of the execution working directory, it will be stringized as an absolute path.

If this method is not called from a build execution, it is equivalent to path.toString().

This method is useful when displaying paths to the user, as relative paths are often more meaningful.

pathThe path to convert to relative string.
The string representation of the path. May be absolute, if the relativization failed.
NullPointerExceptionIf the argument is null.
Writes the contents of the file to the parameter stream, implicitly synchronizing the file using the specified content database.

It is recommended that users call TaskExecutionUtilities.writeTo(SakerFile, OutputStream) instead.

fileThe file to write the contents of.
osThe stream to write the contents to.
dbThe content database for implicit synchronization. May be null to skip implicit synchronization.
IOExceptionIn case of I/O error.
NullPointerExceptionIf file or the stream is null.