FileCriteria ( Frame4J -- the Java framework de.frame4j... )

java.lang.Object
- de.frame4j.io.FileCriteria

All Implemented Interfaces:

FileFilter, FilenameFilter, Serializable, Cloneable, DirectoryStream.Filter<File>
```
@MinDoc(copyright="Copyright  1997 - 2005, 2009, 2016  A. Weinert",
        author="Albrecht Weinert",
        version="V.38",
        lastModified="16.04.2021",
        usage="use when files and directories are to be selected",
        purpose="file and directory criteria")
public class FileCriteria
extends Object
implements Cloneable, Serializable, FilenameFilter, FileFilter, DirectoryStream.Filter<File>
```
Criteria for choosing files.

Objects of this class are a set of encompassing file criteria. These relate to
- the name (exact match or a wildcard expression)
- names to exclude for the path (single or list)
- the type (as part of the name or as list of types)
- the species (file, directory or both)
- the time of the last modification (as range)
- the length (exact or as range)
All object fields defining those criteria are properties with the conventional (JavaBeans schema) setters and getters. Multiple properties can be set at once by a PropMap object.

With those criteria set object of this class are quite complex FilenameFilter. The description of the criteria in the documentation below related directly to their effect on the java.io.FilenameFilter; see also accept().

© Copyright 1997 - 2003, 2005 Albrecht Weinert
See Also:

Serialized Form

Field Summary

Fields
Modifier and Type	Field and Description
`protected boolean`	`allowDir` Acceptance of directories.
`protected boolean`	`allowFile` Acceptance of (real) files.
`protected boolean`	`ignoreCase` Ignore case in names.
`protected long`	`maxLen` The length criterion (maximal size).
`protected long`	`maxTime` The time criterion, maximal time ("until").
`protected long`	`minLen` The length criterion (minimal size).
`protected long`	`minTime` The time criterion, minimal time ("since").
`protected String`	`wildName` The name criterion (with wild cards).

Constructor Summary

Constructors
Constructor and Description

FileCriteria()
The sole constructor.

Constructors
Constructor and Description
`FileCriteria()` The sole constructor.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`accept(File file)` Check, if a file (or directory) fulfils the criteria.
`boolean`	`accept(File dirf, String name)` Check, if a named file (or directory) fulfils the criteria.
`void`	`addExcludeNames(CharSequence excludeNames)` Add exclude criteria for names (to the list).
`void`	`addTypes(CharSequence types)` Add to the file type criteria.
`FileCriteria`	`clone()` A copy of this object.
`boolean`	`equals(Object other)` Compare to other FileCriteria object.
`FastStringSet`	`getExcludeNames()` Exclude criteria for names (a list without wild cards).
`FileFilter`	`getFileFilter()` Get a javax.swing.filechooser.FileFilter.
`long`	`getMaxLen()` The length criterion (maximal size).
`long`	`getMaxTime()` The time criterion, maximal time ("until").
`long`	`getMinLen()` The length criterion (minimal size).
`long`	`getMinTime()` The time criterion, minimal time ("since").
`FastStringSet`	`getTypes()` The file type criterion.
`String`	`getWildName()` The name criterion (with wild cards).
`int`	`hashCode()` Hashcode for FileCriteria.
`boolean`	`isAllowDir()` Acceptance of directories.
`boolean`	`isAllowFile()` Acceptance of (real) files.
`boolean`	`isIgnoreCase()` Ignoring case in names.
`boolean`	`isLenSet()` The length criteria (minimal and maximal size) are given.
`boolean`	`isMaxTimeSet()` The time criterion (max) is set.
`boolean`	`isMinTimeSet()` The time criterion (minTime) is set.
`boolean`	`isTimeSet()` One time criterion is set.
`String`	`parse(String path)` Parse / separate a file specification into path and wildcard name.
`String`	`parse(String path, CharSequence defTypes)` Parse / separate a file specification into path and wildcard name.
`void`	`set(String prefix, PropMap prop)` Set the criteria according to a PropMap.
`void`	`setAllowDir(boolean allowDir)` Acceptance of directories.
`void`	`setAllowFile(boolean allowFile)` Acceptance of (real) files.
`void`	`setExcludeNames(CharSequence excludeNames)` Set exclude criteria for names (list without wild cards).
`void`	`setIgnoreCase(boolean ignoreCase)` Ignore case in names.
`void`	`setMaxLen(long maxLen)` Set the length criterion (maximal size).
`void`	`setMaxTime(CharSequence maxTime)` Set the time criterion, maximal time ("until") by String.
`void`	`setMaxTime(long maxTime)` The time criterion, maximal time ("until").
`void`	`setMinLen(long minLen)` The length criterion (minimal size).
`void`	`setMinTime(CharSequence minTime)` Set the time criterion, minimal time ("since") by String.
`void`	`setMinTime(long minTime)` The time criterion, minimal time ("since").
`void`	`setTypes(CharSequence types)` Set the file type criterion.
`void`	`setWildName(String wildName)` Set the name criterion (with wild cards).
`String`	`toString()` State as String.

Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait

- Field Detail
  - wildName
```
protected String wildName
```
    The name criterion (with wild cards).
    
    See Also:
    
    getWildName()
  - ignoreCase
```
protected boolean ignoreCase
```
    Ignore case in names.
    
    See Also:
    
    isIgnoreCase()
  - allowFile
```
protected boolean allowFile
```
    Acceptance of (real) files.
    
    See Also:
    
    isAllowFile()
  - allowDir
```
protected boolean allowDir
```
    Acceptance of directories.
    
    See Also:
    
    isAllowDir()
  - minTime
```
protected long minTime
```
    The time criterion, minimal time ("since").
    
    See Also:
    
    getMinTime()
  - maxTime
```
protected long maxTime
```
    The time criterion, maximal time ("until").
    
    See Also:
    
    getMaxTime()
  - minLen
```
protected long minLen
```
    The length criterion (minimal size).
    
    See Also:
    
    getMinLen()
  - maxLen
```
protected long maxLen
```
    The length criterion (maximal size).
    
    See Also:
    
    getMinLen()
- Constructor Detail
  - FileCriteria
```
public FileCriteria()
```
    The sole constructor.
    
    A FileCriteria object is made all of its properties having their specific default values. As a java.io.FilenameFilter the object in this state will accept every file and every directory.
    
    See Also:
    
    accept()
- Method Detail
  - getWildName
```
public final String getWildName()
```
    The name criterion (with wild cards).
    
    If the character sequence wildName is not null, it is the (one) criterion on the file's or directory's name. Default is null.
    
    If ignoreCase is true (default), the matching of names to wildName will be not case sensitive.
    
    Returns:
    
    the wild (card) name if set
    
    See Also:
    
    TextHelper.WildEqual(), ignoreCase
  - setWildName
```
public void setWildName(String wildName)
```
    Set the name criterion (with wild cards).
    
    Surrounding white spaces will be stripped. An empty character sequence will be taken as null (no wild name criterion).
    
    Plus signs + will be transformed to asterisks *.
    *.* will be taken as null (no wild name criterion, as accept all).
    
    If wildName contains list separators (normally ; respectively : at Linux) this method will set types instead of wildName.
    
    Parameters:
    
    wildName - the name criterion (with wild cards)
    
    See Also:
    
    TextHelper.WildEqual(), wildName, getWildName()
  - isIgnoreCase
```
public final boolean isIgnoreCase()
```
    Ignoring case in names.
    
    This property says, whether in wildName and excludeNames case should matter.
    
    default: ! ComVar.NOT_WINDOWS
    
    Returns:
    
    true if case is ignored in names
    
    See Also:
    
    wildName
  - setIgnoreCase
```
public void setIgnoreCase(boolean ignoreCase)
```
    Ignore case in names.
    
    Parameters:
    
    ignoreCase - true if case shall be ignored in names
    
    See Also:
    
    isIgnoreCase()
  - getExcludeNames
```
public final FastStringSet getExcludeNames()
```
    Exclude criteria for names (a list without wild cards).
    
    If the FastStringSet excludeNames is not empty, it is an exclude criterion for the file or directory names. If one of the names to exclude is found to be a part of the regarded path, that will be rejected.
    
    excludeNames can be set as a list of names separated by list separator (; or : depending on the operating system), example:
    "D:\Programme; WinNT;"
    
    default: null
    
    Returns:
    
    the exclude exclude criteria for names (a list without wild cards)
    
    See Also:
    
    addExcludeNames(CharSequence), igorecase, wildName
  - setExcludeNames
```
public void setExcludeNames(CharSequence excludeNames)
```
    Set exclude criteria for names (list without wild cards).
    
    The list of exclude criteria for names will be cleared. Afterwards its like addExcludeNames(CharSequence).
    
    Example: ".svn; .cvs; build; .settings"
    
    Parameters:
    
    excludeNames - exclude criteria for names (a ; separated list without wild cards)
    
    See Also:
    
    getExcludeNames(), addExcludeNames(CharSequence)
  - addExcludeNames
```
public void addExcludeNames(CharSequence excludeNames)
```
    Add exclude criteria for names (to the list).
    
    Surrounding white spaces will be stripped. An empty sequence will be taken as null. Plus signs + will be transformed to asterisk * even if wildcards won't be regarded in excludeNames.
    A list / path separator ComVar.PS will be used to separate #getExcludeNames() excludeNames to token.
    Every token / entry will be surrounded by ComVar.FS if not yet so and then added to the list of exclude criteria for names.
    
    If no entry / token is to be added to the exclude criteria they will be left unmodified.
    
    Parameters:
    
    excludeNames - exclude criteria for names to be added
  - getTypes
```
public final FastStringSet getTypes()
```
    The file type criterion.
    
    If the set types is not empty it is the criterion on the file type or extension. default is empty.
    
    The entries in the set will have the form ".aha", ".ht*", ".java" and the like.
    . They will be in lower case.
    
    Returns:
    
    the file type criterion
    
    See Also:
    
    setTypes(CharSequence)
  - setTypes
```
public void setTypes(CharSequence types)
```
    Set the file type criterion.
    
    The list of file types will be cleared. Then its like addTypes(CharSequence).
    
    Parameters:
    
    types - the file type criterion
    
    See Also:
    
    getTypes()
  - addTypes
```
public void addTypes(CharSequence types)
```
    Add to the file type criteria.
    
    Surrounding white spaces will be stripped. An empty sequence will be taken as null.
    
    Multiple types to be accepted may be given as a semicolon separated list. Case does not matter for the file types (a Window only concept foreign to Linux).
    
    Entries may freely have forms like "typ", "*.typ" or "+.typ"; plus characters + will be transformed to asterisks *. (A leading *. will bear no information anyway.)
    
    Parameters:
    
    types - additional file type criteria
    
    See Also:
    
    getTypes(), FastStringSet.addTypes(CharSequence), FastStringSet.setTypes(CharSequence)
  - isAllowFile
```
public final boolean isAllowFile()
```
    Acceptance of (real) files.
    
    Files respectively directories are accepted only if allowFile respectively allowDir is true (the default).
    
    Returns:
    
    true if (real) files are to be accepted
  - setAllowFile
```
public void setAllowFile(boolean allowFile)
```
    Acceptance of (real) files.
    
    Parameters:
    
    allowFile - states if (real) files are to be accepted
    
    See Also:
    
    isAllowDir(), isAllowFile()
  - isAllowDir
```
public final boolean isAllowDir()
```
    Acceptance of directories.
    
    Files respectively directories are accepted only if allowFile respectively allowDir is true (the default).
    
    Returns:
    
    true if directories are to be accepted
    
    See Also:
    
    isAllowFile()
  - setAllowDir
```
public void setAllowDir(boolean allowDir)
```
    Acceptance of directories.
    
    Parameters:
    
    allowDir - states if directories are to be accepted
    
    See Also:
    
    isAllowDir(), isAllowFile()
  - getMinTime
```
public final long getMinTime()
```
    The time criterion, minimal time ("since").
    
    Files are accepted only it the time of their last modification is >= minTime .
    
    The criterion is only used if it is >= 0 (= begin of year 1970) an if it is <= maxTime .
    
    Implementation (history) hint: This class and its predecessor assumes since many years that it will never have to handle files written the last time before 1970. In all its usages that assumption was never challenged, but may nevertheless be questionable.
    
    default: -1 (criterion not in use)
    
    Returns:
    
    the minimal (from) time
    
    See Also:
    
    getMaxTime(), isTimeSet()
  - setMinTime
```
public void setMinTime(long minTime)
```
    The time criterion, minimal time ("since").
    
    Parameters:
    
    minTime - the minimal (from) time
    
    See Also:
    
    getMaxTime(), getMinTime()
  - setMinTime
```
public void setMinTime(CharSequence minTime)
```
    Set the time criterion, minimal time ("since") by String.
    
    If minTime is empty or not parsable as time minTime will be set to -1 .
    
    For accepted time formats see TimeHelper.parse().
    
    A missing time of day will be interpreted as 00:00:00.000 .
    
    Parameters:
    
    minTime - the minimal (from) time
  - getMaxTime
```
public final long getMaxTime()
```
    The time criterion, maximal time ("until").
    
    Files are accepted only it the time of their last modification is <= maxTime .
    
    The criterion is only used if it is >= 0 (= begin of year 1970) an if it is >= minTime.
    
    default: -1 (criterion not in use)
    
    Returns:
    
    the maximum (until) time
    
    See Also:
    
    getMinTime(), isTimeSet()
  - setMaxTime
```
public void setMaxTime(long maxTime)
```
    The time criterion, maximal time ("until").
    
    Parameters:
    
    maxTime - the maximum (until) time
    
    See Also:
    
    maxTime, minTime
  - setMaxTime
```
public void setMaxTime(CharSequence maxTime)
```
    Set the time criterion, maximal time ("until") by String.
    
    If minTime is empty or not parsable as time minTime will be set to -1 .
    
    For accepted time formats see TimeHelper.parse().
    
    A missing time of day will be interpreted as 23:59:59.999 .
    
    The last point says, if using the same date without time of day for both times, it is the whole day.
    
    Parameters:
    
    maxTime - the maximum (until) time
    
    See Also:
    
    setMinTime()
  - isTimeSet
```
public final boolean isTimeSet()
```
    One time criterion is set.
    
    This method returns true, if at least one of the time criteria minTime or maxTime is effectual. See there.
    
    Returns:
    
    true if time criteria are effectual
  - isMinTimeSet
```
public final boolean isMinTimeSet()
```
    The time criterion (minTime) is set.
    
    This method returns true, if at least one of the time criteria minTime is effectual.
    
    Returns:
    
    true if the minimum time criterion is effectual
  - isMaxTimeSet
```
public final boolean isMaxTimeSet()
```
    The time criterion (max) is set.
    
    This method returns true, if at least one of the time criteria maxTime is effectual.
    
    Returns:
    
    true if the maximum (until) time criterion is effectual
  - getMinLen
```
public final long getMinLen()
```
    The length criterion (minimal size).
    
    Files will only be accepted if for their length len
    minLen <= len <= maxLen
    
    minLen's default is 0 and maxLens's default is -1.
    The above length criterion will not be effectual, if
    maxLen < minLen (default) or minLen < 0
    
    Returns:
    
    the minimum length (in bytes) criterion
    
    See Also:
    
    maxLen
  - setMinLen
```
public void setMinLen(long minLen)
```
    The length criterion (minimal size).
    
    Parameters:
    
    minLen - the minimum length (in bytes) criterion
    
    See Also:
    
    getMaxLen(), getMinLen()
  - getMaxLen
```
public long getMaxLen()
```
    The length criterion (maximal size).
    
    Default : -1 (no effect)
    
    Returns:
    
    the maximum length (in bytes) criterion
    
    See Also:
    
    getMinLen()
  - setMaxLen
```
public void setMaxLen(long maxLen)
```
    Set the length criterion (maximal size).
    
    Parameters:
    
    maxLen - the maximum length (in bytes) criterion
    
    See Also:
    
    getMinLen()
  - isLenSet
```
public boolean isLenSet()
```
    The length criteria (minimal and maximal size) are given.
    
    This method returns true if the length criteria are effectual.
    
    Returns:
    
    true if the length criteria are effectual
    
    See Also:
    
    getMinLen()
  - set
```
public void set(String prefix,
                PropMap prop)
```
    Set the criteria according to a PropMap.
    
    This objects criteria will be set according to those properties if they are contained in the supplied PropMap object prop:
    - minLen
    - maxLen
    - minTime respectively since
    - maxTime respectively til
    - allowDir
    - allowFile
    - types
    - ignoreCase
    - wildName
    - excludeNames
    If a property is not given in prop (or prop is null) nothing happens in each case.
    
    If prefix is not empty it will be prepended to the searched property's name transforming their first character to upper case. Example:
    If the prefix "files" the property minLen would be looked up as filesMinLen.
    Parameters:
    
    prefix - an optional prefix for the keys to search for
    
    prop - the properties map to take the criteria from
  - accept
```
public boolean accept(File dirf,
                      String name)
```
    Check, if a named file (or directory) fulfils the criteria.
    
    This method implements the interface java.io.FilenameFilter.
    
    Specified by:
    
    accept in interface FilenameFilter
    
    Parameters:
    
    dirf - the directory in which the file resides (may be null)
    
    name - the (pure) name of the file (null or empty returns false)
    
    Returns:
    
    true if dir/name is acceptable by this FileCriteria
  - accept
```
public boolean accept(File file)
```
    Check, if a file (or directory) fulfils the criteria.
    
    This method implements the function defined by FileFilter.accept().
    
    Specified by:
    
    accept in interface FileFilter
    
    Specified by:
    
    accept in interface DirectoryStream.Filter<File>
    
    Parameters:
    
    file - the file or directory
    
    Returns:
    
    true if the file is acceptable by this FileCriteria
  - getFileFilter
```
public final FileFilter getFileFilter()
```
    Get a javax.swing.filechooser.FileFilter.
    
    This method returns a FileFilter governed by this FileCriteria object.
    Hint this extra method (pitifully) is necessary as javax.swing.filechooser.FileFilter is neither an interface nor does declare any interfaces not even the partly identical java.io.FileFilter.
    
    Returns:
    
    a FileFilter for Swing
  - clone
```
public FileCriteria clone()
```
    A copy of this object.
    
    A copy of this object will be made and returned.
    Hint: The copy is deep, as excludeNames and types are cloned in the process.
    
    Overrides:
    
    clone in class Object
  - equals
```
public final boolean equals(Object other)
```
    Compare to other FileCriteria object.
    
    The comparison is not made field by field, but regarding this objects effect as file filter (FilenameFilter).
    true is returned if the other object is of the same class and would act in the same way.
    
    Overrides:
    
    equals in class Object
  - hashCode
```
public final int hashCode()
```
    Hashcode for FileCriteria.
    
    The value is computed using most fields that have an effect on file filtering (FilenameFilter).
    
    Overrides:
    
    hashCode in class Object
    
    See Also:
    
    equals(java.lang.Object)
  - toString
```
public String toString()
```
    State as String.
    
    Overrides:
    
    toString in class Object
    
    Returns:
    
    a multi-line text describing this object's file criteria
  - parse
```
public String parse(String path)
```
    Parse / separate a file specification into path and wildcard name.
    
    The call is equivalent to parse(path, null).
    
    Parameters:
    
    path - the file denomination to start with (+ becomes *)
    
    Returns:
    
    the parent / directory path part of path
  - parse
```
public String parse(String path,
                    CharSequence defTypes)
```
    Parse / separate a file specification into path and wildcard name.
    
    This method transforms most comfortably an intuitive String notation into a (parent) path and file name or type criteria for this FileCriteria object. Parameters path like
    - \institute\plan\uhu.html
    - \institute\plan\+.html
    - \institute\plan\*.html
    - \institute\plan\html;
    - \institute\plan\.html;.xml
    - \institute\plan\.html;.xml;css
    will be treated correctly.
    
    As a first step wildName will be set null and types will be set to defTypes.
    
    The parameter path will be processed bay TextHelper.makeFNL().
    The result will be split at the last file separator (ComVar.FS \ or /) or at an colon : if ComVar.PS is not a colon.
    This split, if feasible, may have provided a (parent) path and a name part. If no name part was found wildName and types will keep their values from step one above.
    
    If there is a name part found, that will become either wildName or types of this FileCriteria object, taking "." or "*.*" as null.
    It will become types instead of wildName if it contains at least one list separator character ComVar.PS.
    
    The (parent) path part will be returned by this method. If none was found (in above split) .\ respectively ./ (the actual directory's placeholder) is returned.
    
    Hint: After this method only / at most one of wildName or types will be not null.
    
    Hint 2: It might be thought that the effect of ...\*.html and ...\html; (see above), i.e. a wildcard name ending in .html and a type list with just one type html, is the same. This is true in most cases, but not always. A filename "uhu.html" is, obviously, accepted by both settings (hence the belief in equivalence). But "uhu.29.08.2009.html" will only be accepted by the type list entry.
    Parameters:
    
    path - the file denomination to start with (+ becomes *)
    
    defTypes - the default for type criteria
    
    Returns:
    
    the parent / directory path part of path
    
    See Also:
    
    wildName, types

Class FileCriteria

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

wildName

ignoreCase

allowFile

allowDir

minTime

maxTime

minLen

maxLen

Constructor Detail

FileCriteria

Method Detail

getWildName

setWildName

isIgnoreCase

setIgnoreCase

getExcludeNames

setExcludeNames

addExcludeNames

getTypes

setTypes

addTypes

isAllowFile

setAllowFile

isAllowDir

setAllowDir

getMinTime

setMinTime

setMinTime

getMaxTime

setMaxTime

setMaxTime

isTimeSet

isMinTimeSet

isMaxTimeSet

getMinLen

setMinLen

getMaxLen

setMaxLen

isLenSet

set

accept

accept

getFileFilter

clone

equals

hashCode

toString

parse

parse