bb.io.filefilter
Class SuffixFilter

java.lang.Object
  extended by javax.swing.filechooser.FileFilter
      extended by bb.io.filefilter.BaseFilter
          extended by bb.io.filefilter.RegexFilter
              extended by bb.io.filefilter.SuffixFilter
All Implemented Interfaces:
FileFilter
Direct Known Subclasses:
CameraFileFilter, ClassFilter, CompoundFilter.UnitTest.TestFilter, HtmlFilter, JarFilter, JarOrZipFilter, JavaFilter, SoundFileFilter, TarFilter, ZipFilter

public class SuffixFilter
extends RegexFilter

Subclass of RegexFilter that makes it convenient to match Files based on their endings.

Instances are constructed with a Set of desired suffixes. A File is accepted if it ends in at least one of the suffixes (i.e. the suffixes are connected by an implicit OR). The suffix matching is always case insensitive but is otherwise a literal match against the suffixes; these qualities are what make this class more convenient than RegexFilter (users need not know regular expressions).

In general, only a File's name is examined, however, one of the constructors takes a PartMode arg that allows other possibilities (e.g. examine a File's path). Furthermore, that constructor also allows precise control over how normal files, directories, and "other" file system elements are handled. These features, along with the fact that the suffix is arbitrary (can be more or less than a file's extension) make this class much more powerful than the JDK's FileNameExtensionFilter.

This class is multithread safe: it is immutable. In particular, it maintains its ancestor class's immutability.

Author:
Brent Boyer

Nested Class Summary
static class SuffixFilter.UnitTest
          See the Overview page of the project's javadocs for a general description of this unit test class.
 
Field Summary
private  Set<String> suffixes
           
 
Constructor Summary
SuffixFilter(Set<String> suffixes)
          Calls this(suffixes, FileMode.test, DirectoryMode.reject).
SuffixFilter(Set<String> suffixes, FileMode fileMode, DirectoryMode directoryMode)
          Calls this(suffixes, fileMode, directoryMode, OtherMode.reject, PartMode.name).
SuffixFilter(Set<String> suffixes, FileMode fileMode, DirectoryMode directoryMode, OtherMode otherMode, PartMode partMode)
          Constructs a new SuffixFilter instance.
SuffixFilter(String... suffixes)
          Calls this( RegexFilter.toSet(java.lang.String...)(suffixes) ).
 
Method Summary
 String getDescription()
           The implementation here has some introductory text, followed by a comma separated list of all of the regexes present in RegexFilter.patterns.
protected  String getDescriptionIntro()
           
 Set<String> getSuffixes()
          Returns a read-only view of suffixes.
static Set<Pattern> toPatternLiterals(Set<String> suffixes)
          Converts suffixes into a set of Patterns that match any String that ends in a literal occurrence (case insensitive) of an element of suffixes.
 
Methods inherited from class bb.io.filefilter.RegexFilter
getPatterns, passesTest, toPatterns, toSet
 
Methods inherited from class bb.io.filefilter.BaseFilter
accept, acceptImpl, extractPart, getDirectoryMode, getFileMode, getListener, getOtherMode, getPartMode, passesTest
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

suffixes

private final Set<String> suffixes
Constructor Detail

SuffixFilter

public SuffixFilter(String... suffixes)
             throws IllegalArgumentException
Calls this( RegexFilter.toSet(java.lang.String...)(suffixes) ). So, this filter will always test normal files (and only tests the name of them), and always rejects directories and "other" file system elements.

Throws:
IllegalArgumentException

SuffixFilter

public SuffixFilter(Set<String> suffixes)
             throws IllegalArgumentException
Calls this(suffixes, FileMode.test, DirectoryMode.reject). So, this filter will always test normal files (and only tests the name of them), and always rejects directories and "other" file system elements.

Throws:
IllegalArgumentException

SuffixFilter

public SuffixFilter(Set<String> suffixes,
                    FileMode fileMode,
                    DirectoryMode directoryMode)
             throws IllegalArgumentException
Calls this(suffixes, fileMode, directoryMode, OtherMode.reject, PartMode.name). So, this filter will always reject "other" file system elements, and for normal files/directories, only tests the name of each File (assuming FileMode.test/DirectoryMode.test).

Throws:
IllegalArgumentException

SuffixFilter

public SuffixFilter(Set<String> suffixes,
                    FileMode fileMode,
                    DirectoryMode directoryMode,
                    OtherMode otherMode,
                    PartMode partMode)
             throws IllegalArgumentException
Constructs a new SuffixFilter instance.

Contract: this instance will preserve the iteration order of suffixes.

Parameters:
suffixes - Set that if a File's name/path (depending on partMode) ends with, result in the File being accepted; for top performance, use a Set implementation with predictable iteration order, and ensure that the most frequently used suffixes are iterated over first
fileMode - a FileMode instance that specifies how normal files will be handled
directoryMode - a DirectoryMode instance that specifies how directories will be handled
otherMode - a OtherMode instance that specifies how "other" file system elements will be handled
partMode - a PartMode instance that specifies what part of a File's full path will be tested
Throws:
IllegalArgumentException - if suffixes is null or 0-length; fileMode, directoryMode, otherMode, or partMode are null
Method Detail

toPatternLiterals

public static Set<Pattern> toPatternLiterals(Set<String> suffixes)
                                      throws IllegalArgumentException
Converts suffixes into a set of Patterns that match any String that ends in a literal occurrence (case insensitive) of an element of suffixes.

Contract: if this method returns normally, the result will be non-null, non-empty, and the Set type will be one which perfectly preserves the original iteration order of suffixes.

Parameters:
suffixes - Set of arbitrary Strings; for top performance, use a Set implementation with predictable iteration order, and ensure that the most frequently used suffixes are iterated over first
Throws:
IllegalArgumentException - if suffixes is null or 0-length; any element of suffixes is blank

getSuffixes

public Set<String> getSuffixes()
Returns a read-only view of suffixes.


getDescription

public String getDescription()

The implementation here has some introductory text, followed by a comma separated list of all of the regexes present in RegexFilter.patterns.

The implementation here has some introductory text, followed by a comma separated list of the suffixes.

Overrides:
getDescription in class RegexFilter

getDescriptionIntro

protected String getDescriptionIntro()
Overrides:
getDescriptionIntro in class RegexFilter