Finder (TestHelpers 1.0-SNAPSHOT API)

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

Direct Known Subclasses:

Finder.Primary, Finder.Secondary
```
public abstract class Finder
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(File). 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 and Description
`(package private) static class`	`Finder.AndFilter` One of the logical operations of filters: Returns a filter which passes a file iff all original filters in `Finder.AndFilter.filters` do so.
`static interface`	`Finder.Callable` To be implemented by java classes to apply a filter to a file and give feedback whether this filter succeeded.
`(package private) static class`	`Finder.ExecFilter` Filter executing a shell command and passes the file received if the shell command succeeds according to its return code.
`(package private) static class`	`Finder.ExecJavaFilter` Filter executing a java class implementing `Finder.Callable` which passes the file received if the method `Finder.Callable.call(File)` succeeds according to its return code.
`(package private) static class`	`Finder.Filter` Represents a file filter.
`(package private) static class`	`Finder.NameFilter` Filters files by name.
`(package private) static class`	`Finder.NegFilter` One of the logical operations of filters: Returns a filter which passes a file iff the original filter `Finder.NegFilter.negFilter` does not.
`(package private) static class`	`Finder.OrFilter` One of the logical operations of filters: Returns a filter which passes a file iff at least one of the original filters in `Finder.OrFilter.filters` do so.
`(package private) static class`	`Finder.Primary` The most basic kind of finder: Method `path(File)` returns an instance of this.
`(package private) class`	`Finder.PrintFilter` A filter passing all information and printing it on `Finder.PrintFilter.str`.
`(package private) static class`	`Finder.Secondary` A finder wrapping a `Finder.Filter`.

Field Summary

Fields
Modifier and Type	Field and Description
`static Finder.Filter`	`CAN_EXEC` Filter passing the file received iff it is executable.
`static Finder.Filter`	`CAN_READ` Filter passing the file received iff it is readable.
`static Finder.Filter`	`CAN_WRITE` Filter passing the file received iff it is writable.
`static String`	`EXEC_ARG` For `Finder.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 file name received by the preceding portion of the pipe.
`static Finder.Filter`	`FALSE` A filter passing no file.
`static Finder.Filter`	`IS_DIR` Filter passing the file received iff it is a regular file.
`static Finder.Filter`	`IS_FILE` Filter passing the file received iff it is a regular file.
`static Finder.Filter`	`TRUE` A filter passing all files.

Constructor Summary

Constructors
Modifier Constructor and Description

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

Constructors
Modifier	Constructor and Description
`private`	`Finder()` This is declared `private` to prevent instantiation.

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`Finder`	`add(Finder.Filter filter)` Returns a finder by attachig the given filter.
`Finder`	`and(Finder.Filter[] filters)` Convenience method: Returns a finder by attaching an and-filter.
`Finder`	`exec(String[] cmd)` Convenience method: adds an execution filter to this finder.
`static Finder.Filter`	`execFilter(String[] cmd)` Returns a filter invoking a shell command: just passes the files received by this finder further if the command succeeds according to its return value.
`Finder`	`execJava(Finder.Callable callable)` Convenience method: adds a java execution filter to this finder.
`static Finder.Filter`	`execJavaFilter(Finder.Callable callable)` Returns a filter invoking method `Finder.Callable.call(File)` of the given `callable`.
`abstract boolean`	`hasNext()` Returns whether this Finder can emit another file.
`static void`	`main(String[] args)`
`Finder`	`name(String pattern)` Convenience method: adds a name filter to this finder.
`static Finder.Filter`	`nameFilter(String pattern)` Returns a filter passing a file iff its (short) names of which match the regular expression `pattern`.
`abstract File`	`next()` Returns the next file this finder can emit.
`Finder`	`not(Finder.Filter filter)` Convenience method: Returns a finder by attaching the inverse of the given filter.
`Finder`	`or(Finder.Filter[] filters)` Convenience method: Returns a finder by attaching an or-filter.
`static Finder`	`path(File file)` Returns a basic finder, emitting the given file if it exists and is accessible and, recursively, if it is a directory all files therein.
`Finder`	`print(PrintStream str)` Adds a trivial filter passing all files 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 Finder.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 file 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 Finder.Filter TRUE
```
    A filter passing all files. This corresponds the test -true in the original find command.
  - FALSE
```
public static final Finder.Filter FALSE
```
    A filter passing no file. This corresponds the test -false in the original find command.
  - CAN_EXEC
```
public static final Finder.Filter CAN_EXEC
```
    Filter passing the file received iff it is executable. This corresponds the test -executable in the original find command. Do not mix up with Finder.ExecFilter.
  - CAN_READ
```
public static final Finder.Filter CAN_READ
```
    Filter passing the file received iff it is readable. This corresponds the test -readable in the original find command.
  - CAN_WRITE
```
public static final Finder.Filter CAN_WRITE
```
    Filter passing the file received iff it is writable. This corresponds the test -writable in the original find command.
  - IS_FILE
```
public static final Finder.Filter IS_FILE
```
    Filter passing the file received iff it is a regular file. This corresponds the test -type f in the original find command.
  - IS_DIR
```
public static final Finder.Filter IS_DIR
```
    Filter passing the file received iff it is a regular file. This corresponds the test -type d in the original find command.
- Constructor Detail
  - Finder
```
private Finder()
```
    This is declared private to prevent instantiation.
- Method Detail
  - path
```
public static Finder path(File file)
```
    Returns a basic finder, emitting the given file if it exists and is accessible and, recursively, if it is a directory all files therein. The ordering is the same as in original find-command. The expression Finder.path(file) corresponds with find file, 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 Finder.Primary
  - print
```
public Finder print(PrintStream str)
```
    Adds a trivial filter passing all files received by this finder printing their full names to str.
  - add
```
public Finder add(Finder.Filter filter)
```
    Returns a finder by attachig the given filter. For adding the most common filters, there are convenience methods.
  - name
```
public Finder name(String pattern)
```
    Convenience method: adds a name filter to this finder.
    
    See Also:
    
    nameFilter(String)
  - exec
```
public Finder exec(String[] cmd)
```
    Convenience method: adds an execution filter to this finder.
    
    Returns:
    
    an instance of Finder.Secondary instantiated with a filter of type Finder.ExecFilter
    
    See Also:
    
    execFilter(String[])
  - execJava
```
public Finder execJava(Finder.Callable callable)
```
    Convenience method: adds a java execution filter to this finder.
    
    Returns:
    
    an instance of Finder.Secondary instantiated with a filter of type Finder.ExecJavaFilter
    
    See Also:
    
    execJavaFilter(Callable)
  - not
```
public Finder not(Finder.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:
    
    Finder.Filter.not()
  - and
```
public Finder and(Finder.Filter[] filters)
```
    Convenience method: Returns a finder by attaching an and-filter. This corresponds the tests \! expr1 in the original find command.
    
    See Also:
    
    and(Filter[])
  - or
```
public Finder or(Finder.Filter[] filters)
```
    Convenience method: Returns a finder by attaching an or-filter. This corresponds the tests \! expr1 in the original find command.
    
    See Also:
    
    or(Filter[])
  - nameFilter
```
public static Finder.Filter nameFilter(String pattern)
```
    Returns a filter passing a file iff its (short) names of which match the regular expression pattern.
    
    Returns:
    
    an instance of Finder.Secondary instantiated with a filter of type Finder.NameFilter
  - execFilter
```
public static Finder.Filter execFilter(String[] cmd)
```
    Returns a filter invoking a shell command: just passes the files 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 file 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 file 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 Finder.ExecFilter
    
    See Also:
    
    execJavaFilter(Callable)
  - execJavaFilter
```
public static Finder.Filter execJavaFilter(Finder.Callable callable)
```
    Returns a filter invoking method Finder.Callable.call(File) 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 Finder.ExecFilter
    
    See Also:
    
    execFilter(String[])
  - hasNext
```
public abstract boolean hasNext()
```
    Returns whether this Finder can emit another file.
    
    See Also:
    
    next()
  - next
```
public abstract File next()
```
    Returns the next file this finder can emit. This does not throw an exception iff hasNext() returns true.
  - main
```
public static void main(String[] args)
```

Class Finder

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_FILE

IS_DIR

Constructor Detail

Finder

Method Detail

path

print

add

name

exec

execJava

not

and

or

nameFilter

execFilter

execJavaFilter

hasNext

next

main