saker.build Documentation TaskDoc JavaDoc
public final class WildcardPath implements Externalizable, Comparable<WildcardPath>
File inclusion tester based on a specified path and specially handled wildcard pathnames.

The purpose of this class is similar to globbing, but the exact implementation details and accepted wildcards might be different from the usual common implementations.

The class takes a path during instantiation, and uses that to provide functionality to test inclusion, or discover files based on a listing implementation.

The following wildcards are supported in the current implementation:

  • *: which matches any number of characters (0 or more), but doesn't pass through directory boundary.
  • **: which can be used only as a single full path name, and matches zero or more directories with any name.
The following wildcards should be considered as reserved, as they might be added in future versions (without quotes): "?", "[", "]".

The single star wildcard can be combined with other characters, to match path names that partially contain the specified characters.

Wildcard paths that are relative, will only match relative paths, and absolute wildcard paths will only match absolute paths. A wildcard path is considered to be absolute according to the rules of SakerPath.

Examples:

  • dir/no/wildcard only matches dir/no/wildcard
  • abs:/no/wildcard only matches abs:/no/wildcard
  • /no/wildcard only matches /no/wildcard
  • dir/*.ext matches files under the directory dir which have the extension .ext
  • dir/*123* matches files under the directory dir which contain the number 123
  • dir/**/*.ext recursively matches files under the directory dir with the extension .ext
  • dir/**.ext is the same as dir/*.ext
  • dir/** recursively matches all files under the directory dir (children and their children too)
  • *d:/ will match root directories whose drive ends with d

This class works in a case sensitive manner. When collecting files, it will return directories and files which match the wildcard as well.

The usage of this class is not restricted to file paths, they are suitable for matching other kind of character sequences when appropriately constructed. (E.g. it can be used to match class names.)

A WildcardPath can be constructed that it doesn't contain any wildcards. In that case the path will only match the paths that equal to the one provided during instantiation.

The wildcard path doesn't handle the "." and ".." path names specially.

The class is comparable, and serializable.

Nested types
public interface
Interface for providing listing functionality for wildcard paths.
public static final class
Class holding information about the optimization performed in reduce().
Constructors
public
Methods
public int
Compares this object with the specified object for order.
public boolean
Indicates whether some other object is "equal to" this one.
public boolean
Checks if appending one or more names to the argument path can result in the wildcard including it.
public boolean
Checks if appending one or more names to the argument array of path names can result in the wildcard including it.
public static NavigableMap<SakerPath, SakerFile>
getFiles(Iterable<extends WildcardPath> paths, ExecutionDirectoryContext executiondirectorycontext, SakerDirectory workingdirectory)
Collects the files for multiple wildcard paths, a given execution directory context, and a working directory.
public static NavigableMap<SakerPath, SakerFile>
getFiles(Iterable<extends WildcardPath> paths, TaskContext taskcontext)
Collects the files for multiple wildcard paths, and a given task context.
public NavigableMap<SakerPath, ? extends BasicFileAttributes>
Collects the files for a given file provider.
public NavigableMap<SakerPath, ? extends BasicFileAttributes>
Collects the files for a given file provider and working directory.
public NavigableMap<SakerPath, SakerFile>
getFiles(ExecutionDirectoryContext executiondirectorycontext, SakerDirectory workingdir)
Collects the files for the specified directories.
public NavigableMap<SakerPath, ? extends BasicFileAttributes>
Collects the files for the specified execution path configuration.
public NavigableMap<SakerPath, SakerFile>
getFiles(TaskContext taskcontext)
Collects the files for the specified task context.
public static <T> NavigableMap<SakerPath, T>
getItems(Iterable<extends WildcardPath> paths, ItemLister<T> lister)
Collects the items for multiple wildcard paths and a given ItemLister.
public <T> NavigableMap<SakerPath, T>
getItems(ItemLister<T> lister)
Collects the items for a given ItemLister.
public SakerFile
getSingleFile(ExecutionDirectoryContext executiondirectorycontext, SakerDirectory workingdir)
Collects a single file matching this wildcard for the given execution directory context and working directory.
public SakerFile
Collects a single file matching this wildcard for the given task context.
public <T> Entry<SakerPath, T>
Collects a single item matching this wildcard for the given ItemLister.
public int
Returns a hash code value for the object.
public boolean
Checks if this wildcard includes/matches the specified path.
public boolean
includes(List<extends String> paths)
Checks if this wildcard includes/matches the path specified by a list of path names.
public boolean
Checks if this wildcard includes/matches the specified path.
public boolean
includes(String[] paths)
Checks if this wildcard includes/matches the path specified by an array of path names.
public boolean
Checks if this wildcard path only consists of path names that will match all files recursively.
public void
The object implements the readExternal method to restore its contents by calling the methods of DataInput for primitive types and readObject for objects, strings and arrays.
public ReducedWildcardPath
Tries to optimize this wildcard path by removing (reducing) the starting path names that match the path names in an exact manner.
public String
Returns a string representation of the object.
public static WildcardPath
Creates a new wildcard path based on the given path string.
public static WildcardPath
Creates a new wildcard path for the specified path.
public static WildcardPath
Creates a new wildcard path for the specified path.
public static WildcardPath
valueOf(String[] pathnames)
Creates a new wildcard path for the specified path names.
public void
The object implements the writeExternal method to save its contents by calling the methods of DataOutput for its primitive values or calling the writeObject method of ObjectOutput for objects, strings, and arrays.
public int compareTo(WildcardPath o)
Overridden from: Comparable
Compares this object with the specified object for order. Returns a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.

The implementor must ensure sgn(x.compareTo(y)) == -sgn(y.compareTo(x)) for all x and y. (This implies that x.compareTo(y) must throw an exception iff y.compareTo(x) throws an exception.)

The implementor must also ensure that the relation is transitive: (x.compareTo(y)>0 && y.compareTo(z)>0) implies x.compareTo(z)>0.

Finally, the implementor must ensure that x.compareTo(y)==0 implies that sgn(x.compareTo(z)) == sgn(y.compareTo(z)), for all z.

It is strongly recommended, but not strictly required that (x.compareTo(y)==0) == (x.equals(y)). Generally speaking, any class that implements the Comparable interface and violates this condition should clearly indicate this fact. The recommended language is "Note: this class has a natural ordering that is inconsistent with equals."

In the foregoing description, the notation sgn(expression) designates the mathematical signum function, which is defined to return one of -1, 0, or 1 according to whether the value of expression is negative, zero or positive.

othe object to be compared.
a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.
public boolean equals(Object obj)
Overridden from: Object
Indicates whether some other object is "equal to" this one.

The equals method implements an equivalence relation on non-null object references:

  • It is reflexive: for any non-null reference value x, x.equals(x) should return true.
  • It is symmetric: for any non-null reference values x and y, x.equals(y) should return true if and only if y.equals(x) returns true.
  • It is transitive: for any non-null reference values x, y, and z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) should return true.
  • It is consistent: for any non-null reference values x and y, multiple invocations of x.equals(y) consistently return true or consistently return false, provided no information used in equals comparisons on the objects is modified.
  • For any non-null reference value x, x.equals(null) should return false.

The equals method for class Object implements the most discriminating possible equivalence relation on objects; that is, for any non-null reference values x and y, this method returns true if and only if x and y refer to the same object (x == y has the value true).

Note that it is generally necessary to override the hashCode method whenever this method is overridden, so as to maintain the general contract for the hashCode method, which states that equal objects must have equal hash codes.

objthe reference object with which to compare.
true if this object is the same as the obj argument; false otherwise.
public boolean finishable(SakerPath path) throws NullPointerException
Checks if appending one or more names to the argument path can result in the wildcard including it.

The method returns true if any only if there exists an appending operation to the argument path that results in the wildcard matching the result.

pathThe path to examine.
true if the path can be finished so this wildcard matches it.
NullPointerExceptionIf the argument is null.
public boolean finishable(String[] paths) throws NullPointerException
Checks if appending one or more names to the argument array of path names can result in the wildcard including it.

The method returns true if any only if there exists an appending operation to the argument path that results in the wildcard matching the result.

pathsThe path names to examine.
true if the path can be finished so this wildcard matches it.
NullPointerExceptionIf the argument is null.
public static NavigableMap<SakerPath, SakerFile> getFiles(Iterable<extends WildcardPath> paths, ExecutionDirectoryContext executiondirectorycontext, SakerDirectory workingdirectory) throws NullPointerException
Collects the files for multiple wildcard paths, a given execution directory context, and a working directory.

If the execution directory context is null, no root directories are considered.

pathsThe wildcard paths to collect the files for.
executiondirectorycontextThe execution directory context.
workingdirectoryThe working directory to resolve relative paths against or null to not use a working directory.
The collected files mapped by their absolute paths.
NullPointerExceptionIf the wildcards argument is null.
public static NavigableMap<SakerPath, SakerFile> getFiles(Iterable<extends WildcardPath> paths, TaskContext taskcontext) throws NullPointerException
Collects the files for multiple wildcard paths, and a given task context.

The root directories and working directory for the task is used for base directories.

pathsThe wildcard paths to collect the files for.
taskcontextThe task context to use for base directories.
The collected files mapped by their absolute paths.
NullPointerExceptionIf any of the argument is null.
Collects the files for a given file provider.

As no working directory is specified, only absolute wildcards should use this function.

fpThe file provider to discover files.
The collected files mapped by the file attributes to their absolute paths.
NullPointerExceptionIf the file provider is null.
Collects the files for a given file provider and working directory.
fpThe file provider to discover files.
workingdirThe working directory to resolve relative paths against or null to not use a working directory.
The collected files mapped by the file attributes to their absolute paths.
NullPointerExceptionIf the file provider is null.
public NavigableMap<SakerPath, SakerFile> getFiles(ExecutionDirectoryContext executiondirectorycontext, SakerDirectory workingdir)
Collects the files for the specified directories.

The root directories specified by the execution directory will be used to discover absolute files.

executiondirectorycontextThe execution directory context.
workingdirThe working directory to resolve relative paths against or null to not use a working directory.
The collected files mapped by their absolute paths.
Collects the files for the specified execution path configuration.

The root file providers and working directory in the argument configuration will be used as a base for file collection.

pathconfigurationThe path configuration.
The collected files mapped by the file attributes to their absolute paths.
NullPointerExceptionIf the argument is null.
Collects the files for the specified task context.

The root directories and working directory for the task is used for base directories.

taskcontextThe task context.
The collected files mapped by their absolute paths.
NullPointerExceptionIf the argument is null.
public static <T> NavigableMap<SakerPath, T> getItems(Iterable<extends WildcardPath> paths, ItemLister<T> lister) throws NullPointerException
Collects the items for multiple wildcard paths and a given ItemLister.
pathsThe wildcard paths to collect the files for.
listerThe lister to use for enumerating items.
The collected items mapped by their absolute paths to the items collected.
NullPointerExceptionIf any of the argument is null.
Collects the items for a given ItemLister.
listerThe lister to use for enumerating items.
The collected items mapped by their absolute paths to the items collected.
NullPointerExceptionIf the argument is null.
public SakerFile getSingleFile(ExecutionDirectoryContext executiondirectorycontext, SakerDirectory workingdir)
Collects a single file matching this wildcard for the given execution directory context and working directory.

The root directories specified by the execution directory will be used to discover absolute files.

executiondirectorycontextThe execution directory context.
workingdirThe working directory to resolve relative paths against or null to not use a working directory.
The discovered file or null if no matching file found.
Collects a single file matching this wildcard for the given task context.

The root directories and working directory for the task is used for base directories.

taskcontextThe task context.
The discovered file or null if no matching file found.
NullPointerExceptionIf the argument is null.
public <T> Entry<SakerPath, T> getSingleItem(ItemLister<T> lister) throws NullPointerException
Collects a single item matching this wildcard for the given ItemLister.
listerThe lister to use for enumerating items.
The discovered item mapped to its absolute path or null if no matching item found.
NullPointerExceptionIf the argument is null.
public int hashCode()
Overridden from: Object
Returns a hash code value for the object. This method is supported for the benefit of hash tables such as those provided by HashMap.

The general contract of hashCode is:

  • Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
  • If two objects are equal according to the equals(Object) method, then calling the hashCode method on each of the two objects must produce the same integer result.
  • It is not required that if two objects are unequal according to the Object.equals(Object) method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hash tables.

As much as is reasonably practical, the hashCode method defined by class Object does return distinct integers for distinct objects. (This is typically implemented by converting the internal address of the object into an integer, but this implementation technique is not required by the Java™ programming language.)

a hash code value for this object.
public boolean includes(String path) throws NullPointerException
Checks if this wildcard includes/matches the specified path.

The argument will be split up in the same way valueOf(String) does.

The argument path may be relative or absolute.

pathThe path.
true if this wildcard includes the argument.
NullPointerExceptionIf the argument is null.
public boolean includes(List<extends String> paths) throws NullPointerException
Checks if this wildcard includes/matches the path specified by a list of path names.

The argument path may be relative or absolute.

pathsThe list of path names.
true if this wildcard includes the argument.
NullPointerExceptionIf the argument is null.
public boolean includes(SakerPath path) throws NullPointerException
Checks if this wildcard includes/matches the specified path.

The argument path may be relative or absolute.

pathThe path.
true if this wildcard includes the argument.
NullPointerExceptionIf the argument is null.
public boolean includes(String[] paths) throws NullPointerException
Checks if this wildcard includes/matches the path specified by an array of path names.

The argument path may be relative or absolute.

pathsThe array of path names.
true if this wildcard includes the argument.
NullPointerExceptionIf the argument is null.
public boolean isRecursiveAllFilesPath()
Checks if this wildcard path only consists of path names that will match all files recursively.
true if this path contains only the "**" path names.
Overridden from: Externalizable
The object implements the readExternal method to restore its contents by calling the methods of DataInput for primitive types and readObject for objects, strings and arrays. The readExternal method must read the values in the same sequence and with the same types as were written by writeExternal.
inthe stream to read data from in order to restore the object
IOExceptionif I/O errors occur
ClassNotFoundExceptionIf the class for an object being restored cannot be found.
Tries to optimize this wildcard path by removing (reducing) the starting path names that match the path names in an exact manner.

As a result of this call, the wildcard path will be separated into two parts:

  1. The first part contains the path names which doesn't contain any wildcards, therefore matching the input in an exact manner.
  2. The second part starts with the first wildcarded path name and lasts until the end of this path.
The resulting reduced wildcard can be used by resolving possible inputs against the reduced first part, and applying the remaining wildcard to that.

The resulting first or second parts might be null in which case this wildcard either fully matches paths exactly, or is wildcarded from the beginning.

Examples:

  • dir/*.ext will be reduced to dir and *ext
  • dir/file.ext will be reduced to dir/file.ext and null
  • *.ext will be reduced to null and *ext
The reduced wildcard path.
public String toString()
Overridden from: Object
Returns a string representation of the object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method.

The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of:

 getClass().getName() + '@' + Integer.toHexString(hashCode())
 
a string representation of the object.
Creates a new wildcard path based on the given path string.

The argument will be split up by '/' and '\\' characters. The path is considered to be absolute with the same rules as SakerPath.

pathThe path.
The constructed wildcard path.
NullPointerExceptionIf the argument is null
InvalidPathFormatExceptionIf the path has invalid format.
public static WildcardPath valueOf(Path path) throws NullPointerException
Creates a new wildcard path for the specified path.

The argument path will be normalized.

The created wildcard will have the same root (if absolute) and all path names as in the argument.

pathThe path.
The constructed wildcard path.
NullPointerExceptionIf the argument is null
Creates a new wildcard path for the specified path.

The created wildcard will have the same root (if absolute) and all path names as in the argument.

pathThe path.
The constructed wildcard path.
NullPointerExceptionIf the argument is null
public static WildcardPath valueOf(String[] pathnames) throws NullPointerException
Creates a new wildcard path for the specified path names.

The argument is not sanity checked in any way. If it includes slashes, or other semantically important characters, they are not removed or split up.

The array will be cloned, any modifications to it won't propagate to the created wildcard.

pathnamesAn array of path names.
The constructed wildcard path.
NullPointerExceptionIf the argument is null
public void writeExternal(ObjectOutput out) throws IOException
Overridden from: Externalizable
The object implements the writeExternal method to save its contents by calling the methods of DataOutput for its primitive values or calling the writeObject method of ObjectOutput for objects, strings, and arrays.
outthe stream to write the object to
IOExceptionIncludes any I/O exceptions that may occur