java.lang.Object
- eu.simuline.util.PathFinder

Direct Known Subclasses:

PathFinder.Primary, PathFinder.Secondary
```
public abstract class PathFinder
extends Object
```
Emulates the unix shell command find which is invoked as find [-H] [-L] [-P] [-Olevel] [-D help|tree|search|stat|rates|opt|exec] [path...] (expression)*. If path is left out (possibly more than one path?), then the default is ., i.e. the current directory. The path need not be a directory. If it is a proper file then typically wildcards are used. Then the name is matched. If no expression is given, the default is -print. So we may assume, that both, a path and a non-empty sequence of expressions, are given.
The idea behind the find command is, that, starting with the files matching the path, each expression serves as a filter, feeding the filter corresponding to the following expression. Each filter can have a side effect. Expressions may be either tests or actions. For tests, the focus is on the filter-functionality, whereas actions are trivial filters just passing the files they receive. Actions are applied because of their side effects like print.
The most basic kind of finder corresponds with the command find path iterating just over the files in the path. This kind of finder is returned by the static method path(Path). Starting with this basic finder, further finders can be added to the pipe using the member methods name(String) and print(PrintStream). Created: Wed Nov 21 17:29:41 2012

Version:

1.0

Author:

Ernst Reissner

Nested Class Summary

Nested Classes
Modifier and Type	Class	Description
`(package private) static class`	`PathFinder.AndFilter`	One of the logical operations of filters: Returns a filter which passes a path iff all original filters in `PathFinder.AndFilter.filters` do so.
`static interface`	`PathFinder.Callable`	To be implemented by java classes to apply a filter to a path and give feedback whether this filter succeeded.
`(package private) static class`	`PathFinder.ExecFilter`	Filter executing a shell command and passes the path received if the shell command succeeds according to its return code.
`(package private) static class`	`PathFinder.ExecJavaFilter`	Filter executing a java class implementing `PathFinder.Callable` which passes the path received if the method `PathFinder.Callable.call(Path)` succeeds according to its return code.
`(package private) static class`	`PathFinder.Filter`	Represents a path filter.
`(package private) static class`	`PathFinder.NameFilter`	Filters paths by name.
`(package private) static class`	`PathFinder.NegFilter`	One of the logical operations of filters: Returns a filter which passes a path iff the original filter `PathFinder.NegFilter.tbNegFilter` does not.
`(package private) static class`	`PathFinder.OrFilter`	One of the logical operations of filters: Returns a filter which passes a path iff at least one of the original filters in `PathFinder.OrFilter.filters` do so.
`(package private) static class`	`PathFinder.Primary`	The most basic kind of finder: Method `path(Path)` returns an instance of this.
`(package private) class`	`PathFinder.PrintFilter`	A filter passing all information and printing it on `PathFinder.PrintFilter.str`.
`(package private) static class`	`PathFinder.Secondary`	A finder wrapping a `PathFinder.Filter`.

Field Summary

Fields
Modifier and Type	Field	Description
`static PathFinder.Filter`	`CAN_EXEC`	Filter passing the path received iff it is executable.
`static PathFinder.Filter`	`CAN_READ`	Filter passing the path received iff it is readable.
`static PathFinder.Filter`	`CAN_WRITE`	Filter passing the path received iff it is writable.
`static String`	`EXEC_ARG`	For `PathFinder.ExecFilter`s representing a filter invoking a shell command, this string represents the argument of the command which is in the original find a `{}` and which is replaced by the path name received by the preceding portion of the pipe.
`static PathFinder.Filter`	`FALSE`	A filter passing no path.
`static PathFinder.Filter`	`IS_DIR`	Filter passing the path received iff it is a regular path.
`static PathFinder.Filter`	`IS_PATH`	Filter passing the path received iff it is a regular path.
`static PathFinder.Filter`	`TRUE`	A filter passing all paths.

Constructor Summary

Constructors
Modifier Constructor Description

private PathFinder()
This is declared private to prevent instantiation.

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method	Description
`PathFinder`	`add(PathFinder.Filter filter)`	Returns a finder by attachig the given filter.
`PathFinder`	`and(PathFinder.Filter[] filters)`	Convenience method: Returns a finder by attaching an and-filter.
`PathFinder`	`exec(String[] cmd)`	Convenience method: adds an execution filter to this finder.
`static PathFinder.Filter`	`execFilter(String[] cmd)`	Returns a filter invoking a shell command: just passes the paths received by this finder further if the command succeeds according to its return value.
`PathFinder`	`execJava(PathFinder.Callable callable)`	Convenience method: adds a java execution filter to this finder.
`static PathFinder.Filter`	`execJavaFilter(PathFinder.Callable callable)`	Returns a filter invoking method `PathFinder.Callable.call(Path)` of the given `callable`.
`abstract boolean`	`hasNext()`	Returns whether this PathFinder can emit another path.
`static void`	`main(String[] args)`
`PathFinder`	`name(String pattern)`	Convenience method: adds a name filter to this finder.
`static PathFinder.Filter`	`nameFilter(String pattern)`	Returns a filter passing a path iff its (short) names of which match the regular expression `pattern`.
`abstract Path`	`next()`	Returns the next path this finder can emit.
`PathFinder`	`not(PathFinder.Filter filter)`	Convenience method: Returns a finder by attaching the inverse of the given filter.
`PathFinder`	`or(PathFinder.Filter[] filters)`	Convenience method: Returns a finder by attaching an or-filter.
`static PathFinder`	`path(Path path)`	Returns a basic finder, emitting the given path if it exists and is accessible and, recursively, if it is a directory all paths therein.
`PathFinder`	`print(PrintStream str)`	Adds a trivial filter passing all paths received by this finder printing their full names to `str`.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - EXEC_ARG
```
public static final String EXEC_ARG
```
    For PathFinder.ExecFilters representing a filter invoking a shell command, this string represents the argument of the command which is in the original find a {} and which is replaced by the path name received by the preceding portion of the pipe. CAUTION: It must be used this instance and no other equivalent string {}.
    
    See Also:
    
    Constant Field Values
  - TRUE
```
public static final PathFinder.Filter TRUE
```
    A filter passing all paths. This corresponds the test -true in the original find command.
  - FALSE
```
public static final PathFinder.Filter FALSE
```
    A filter passing no path. This corresponds the test -false in the original find command.
  - CAN_EXEC
```
public static final PathFinder.Filter CAN_EXEC
```
    Filter passing the path received iff it is executable. This corresponds the test -executable in the original find command. Do not mix up with PathFinder.ExecFilter.
  - CAN_READ
```
public static final PathFinder.Filter CAN_READ
```
    Filter passing the path received iff it is readable. This corresponds the test -readable in the original find command.
  - CAN_WRITE
```
public static final PathFinder.Filter CAN_WRITE
```
    Filter passing the path received iff it is writable. This corresponds the test -writable in the original find command.
  - IS_PATH
```
public static final PathFinder.Filter IS_PATH
```
    Filter passing the path received iff it is a regular path. This corresponds the test -type f in the original find command.
  - IS_DIR
```
public static final PathFinder.Filter IS_DIR
```
    Filter passing the path received iff it is a regular path. This corresponds the test -type d in the original find command.
- Constructor Detail
  - PathFinder
```
private PathFinder()
```
    This is declared private to prevent instantiation.
- Method Detail
  - path
```
public static PathFinder path(Path path)
```
    Returns a basic finder, emitting the given path if it exists and is accessible and, recursively, if it is a directory all paths therein. The ordering is the same as in original find-command. The expression PathFinder.path(path) corresponds with find path, except that the find command implicitly adds a print filter as defined in print(PrintStream). Note also that, unlike th original find, no wildcards are supported.
    
    Returns:
    
    an instance of PathFinder.Primary
  - print
```
public PathFinder print(PrintStream str)
```
    Adds a trivial filter passing all paths received by this finder printing their full names to str.
  - add
```
public PathFinder add(PathFinder.Filter filter)
```
    Returns a finder by attachig the given filter. For adding the most common filters, there are convenience methods.
  - name
```
public PathFinder name(String pattern)
```
    Convenience method: adds a name filter to this finder.
    
    See Also:
    
    nameFilter(String)
  - exec
```
public PathFinder exec(String[] cmd)
```
    Convenience method: adds an execution filter to this finder.
    
    Returns:
    
    an instance of PathFinder.Secondary instantiated with a filter of type PathFinder.ExecFilter
    
    See Also:
    
    execFilter(String[])
  - execJava
```
public PathFinder execJava(PathFinder.Callable callable)
```
    Convenience method: adds a java execution filter to this finder.
    
    Returns:
    
    an instance of PathFinder.Secondary instantiated with a filter of type PathFinder.ExecJavaFilter
    
    See Also:
    
    execJavaFilter(Callable)
  - not
```
public PathFinder not(PathFinder.Filter filter)
```
    Convenience method: Returns a finder by attaching the inverse of the given filter. This corresponds the tests \! expr1 in the original find command.
    
    See Also:
    
    PathFinder.Filter.not()
  - and
```
public PathFinder and(PathFinder.Filter[] filters)
```
    Convenience method: Returns a finder by attaching an and-filter. This corresponds the tests \! expr1 in the original find command.
    
    See Also:
    
    PathFinder.Filter.and(Filter[])
  - or
```
public PathFinder or(PathFinder.Filter[] filters)
```
    Convenience method: Returns a finder by attaching an or-filter. This corresponds the tests \! expr1 in the original find command.
    
    See Also:
    
    PathFinder.Filter.or(Filter[])
  - nameFilter
```
public static PathFinder.Filter nameFilter(String pattern)
```
    Returns a filter passing a path iff its (short) names of which match the regular expression pattern.
    
    Returns:
    
    an instance of PathFinder.Secondary instantiated with a filter of type PathFinder.NameFilter
  - execFilter
```
public static PathFinder.Filter execFilter(String[] cmd)
```
    Returns a filter invoking a shell command: just passes the paths received by this finder further if the command succeeds according to its return value. Example in original find-terminology: find . -exec grep "pattern without quotes" {} \; -print. Here, the portion specifying execution is -exec grep "pattern without quotes" {} \;: It starts with -exec and ends with \;. Note that the command grep has arguments "pattern without quotes" and {}. The first argument must be quoted because it contains whitespace and would otherwise be interpreted as three arguments. The second argument {} is silently replaced by the path name received by the preceeding portion of the find-command.
    
    Parameters:
    
    cmd - a shell command with its arguments. The 0th entry is the command itself and the others are arguments. Be aware when escape sequences are needed. Quotes ensuring that an argument is interpreted as a unit must be omitted.
    In the original find command, {} represents arguments to be replaced by the path name received by the preceding portion of the pipe. These must be represented by the object instance EXEC_ARG which is also a string {} but it is wrong to put an equivalent string as e.g. new String("{}").
    For example to obtain a grep use new String{} {"grep", "pattern without quotes", EXEC_ARG}
    
    Returns:
    
    a filter of type PathFinder.ExecFilter
    
    See Also:
    
    execJavaFilter(Callable)
  - execJavaFilter
```
public static PathFinder.Filter execJavaFilter(PathFinder.Callable callable)
```
    Returns a filter invoking method PathFinder.Callable.call(Path) of the given callable.
    
    Parameters:
    
    callable - A callable defining a filter. If parameters are required, these must be given when instantiating the callable or later using setter methods.
    
    Returns:
    
    a filter of type PathFinder.ExecFilter
    
    See Also:
    
    execFilter(String[])
  - hasNext
```
public abstract boolean hasNext()
```
    Returns whether this PathFinder can emit another path.
    
    See Also:
    
    next()
  - next
```
public abstract Path next()
```
    Returns the next path this finder can emit. This does not throw an exception iff hasNext() returns true.
  - main
```
public static void main(String[] args)
```

Class PathFinder

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

EXEC_ARG

TRUE

FALSE

CAN_EXEC

CAN_READ

CAN_WRITE

IS_PATH

IS_DIR

Constructor Detail

PathFinder

Method Detail

path

print

add

name

exec

execJava

not

and

or

nameFilter

execFilter

execJavaFilter

hasNext

next

main