bb.io.filefilter
Class BaseFilter

java.lang.Object
  extended by javax.swing.filechooser.FileFilter
      extended by bb.io.filefilter.BaseFilter
All Implemented Interfaces:
FileFilter
Direct Known Subclasses:
BaseFilter.UnitTest.TestFilter, DirectoryFilter, NormalFileFilter, RegexFilter, TarableFilter, VisibleFilter, ZippableFilter

public abstract class BaseFilter
extends FileFilter
implements FileFilter

Abstract base class for other File filter implementations that defines some common functionality.

The first area addressed by this class is how to limit what kinds of Files may be accepted. THe types of Files are normal files, directories, and "other" file system elements. Different filter implementations can have different policies regarding these types. This class offers constructors whose fileMode/directoryMode/otherMode args specify the policies.

The next area addressed by this class is specifying what part of a File's path will be tested. This class offers constructors whose partMode arg specifies the policy.

Concrete subclasses must implement the passesTest(String) and getDescription() methods.

Note that this class is both a subclass of javax.swing.filechooser.FileFilter (so that it can be passed to JFileChooser), as well as an implementation of java.io.FileFilter (so that it is suitable as an argument to File.listFiles).

This class is multithread safe if its listener field is multithread safe, since other than possible deep state in that field, it is immutable. In particular, it is always properly constructed, all of its fields are final, and none of their state can be changed after construction except possibly any deep state inside listener. See p. 53 of Java Concurrency In Practice for more discussion. One way that listener can be multithread safe is if it is null.

Author:
Brent Boyer

Nested Class Summary
static class BaseFilter.UnitTest
          See the Overview page of the project's javadocs for a general description of this unit test class.
 
Field Summary
private  DirectoryMode directoryMode
           
private  FileMode fileMode
           
private  FileFilterListener listener
           
private  OtherMode otherMode
           
private  PartMode partMode
           
 
Constructor Summary
BaseFilter()
          Calls this(null).
BaseFilter(FileFilterListener listener)
          Calls this(FileMode.test, DirectoryMode.reject, listener).
BaseFilter(FileMode fileMode, DirectoryMode directoryMode)
          Calls this(fileMode, directoryMode, null).
BaseFilter(FileMode fileMode, DirectoryMode directoryMode, FileFilterListener listener)
          Calls this(fileMode, directoryMode, OtherMode.reject, PartMode.name, listener).
BaseFilter(FileMode fileMode, DirectoryMode directoryMode, OtherMode otherMode, PartMode partMode)
          Calls this(fileMode, directoryMode, OtherMode.reject, PartMode.name, null).
BaseFilter(FileMode fileMode, DirectoryMode directoryMode, OtherMode otherMode, PartMode partMode, FileFilterListener listener)
          Constructs a new BaseFilter instance.
 
Method Summary
 boolean accept(File file)
          Reports whether or not file is accepted by this filter and fires the event to the FileFilterListener if it is non-null.
protected  boolean acceptImpl(File file)
          Reports whether or not file is accepted by this filter.
protected  String extractPart(File file)
          Extracts and returns the part of file's full path that is specified by getPartMode().
abstract  String getDescription()
          
 DirectoryMode getDirectoryMode()
          Returns directoryMode.
 FileMode getFileMode()
          Returns fileMode.
 FileFilterListener getListener()
          Returns listener.
 OtherMode getOtherMode()
          Returns otherMode.
 PartMode getPartMode()
          Returns partMode.
protected  boolean passesTest(File file)
          Applies this filter's test to file.
protected  boolean passesTest(String part)
          Determines whether or not part (which is some part of a File's full path) passes this filter's test.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

fileMode

private final FileMode fileMode

directoryMode

private final DirectoryMode directoryMode

otherMode

private final OtherMode otherMode

partMode

private final PartMode partMode

listener

private final FileFilterListener listener
Constructor Detail

BaseFilter

public BaseFilter()
Calls this(null). So, this filter will always test normal files (and only tests the name of them), and always rejects directories and "other" file system elements. It also has no FileFilterListener.


BaseFilter

public BaseFilter(FileFilterListener listener)
Calls this(FileMode.test, DirectoryMode.reject, listener). So, this filter will always test normal files (and only tests the name of them), and always rejects directories and "other" file system elements. All filter events are sent to listener.


BaseFilter

public BaseFilter(FileMode fileMode,
                  DirectoryMode directoryMode)
           throws IllegalArgumentException
Calls this(fileMode, directoryMode, null). 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). It also has no FileFilterListener.

Throws:
IllegalArgumentException

BaseFilter

public BaseFilter(FileMode fileMode,
                  DirectoryMode directoryMode,
                  FileFilterListener listener)
           throws IllegalArgumentException
Calls this(fileMode, directoryMode, OtherMode.reject, PartMode.name, listener). 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). All filter events are sent to listener.

Throws:
IllegalArgumentException

BaseFilter

public BaseFilter(FileMode fileMode,
                  DirectoryMode directoryMode,
                  OtherMode otherMode,
                  PartMode partMode)
           throws IllegalArgumentException
Calls this(fileMode, directoryMode, OtherMode.reject, PartMode.name, null). So, this filter has no FileFilterListener.

Throws:
IllegalArgumentException

BaseFilter

public BaseFilter(FileMode fileMode,
                  DirectoryMode directoryMode,
                  OtherMode otherMode,
                  PartMode partMode,
                  FileFilterListener listener)
           throws IllegalArgumentException
Constructs a new BaseFilter instance.

Parameters:
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
listener - a FileFilterListener instance that can be supplied to receive filter events; may be null
Throws:
IllegalArgumentException - if fileMode, directoryMode, otherMode, or partMode is null
Method Detail

getFileMode

public FileMode getFileMode()
Returns fileMode.


getDirectoryMode

public DirectoryMode getDirectoryMode()
Returns directoryMode.


getOtherMode

public OtherMode getOtherMode()
Returns otherMode.


getPartMode

public PartMode getPartMode()
Returns partMode.


getListener

public FileFilterListener getListener()
Returns listener.


accept

public boolean accept(File file)
               throws IllegalArgumentException,
                      SecurityException
Reports whether or not file is accepted by this filter and fires the event to the FileFilterListener if it is non-null.

Implementation here merely wraps a call to acceptImpl.

Specified by:
accept in interface FileFilter
Specified by:
accept in class FileFilter
Throws:
IllegalArgumentException - if file is null
SecurityException - if a security manager exists and its SecurityManager.checkRead(java.lang.String) method denies read access to the file

acceptImpl

protected boolean acceptImpl(File file)
                      throws IllegalArgumentException,
                             SecurityException
Reports whether or not file is accepted by this filter.

Implementation here sees if file is a normal file/directory/"other" file system element and applies getFileMode()/getDirectoryMode()/getOtherMode() as appropriate. If the mode calls for the filter's test to be applied to file, then returns passesTest(file).

Throws:
IllegalArgumentException - if file is null
SecurityException - if a security manager exists and its SecurityManager.checkRead(java.lang.String) method denies read access to the file

passesTest

protected boolean passesTest(File file)
Applies this filter's test to file.

Implementation here returns passesTest( extractPart(file) ).


extractPart

protected String extractPart(File file)
Extracts and returns the part of file's full path that is specified by getPartMode().


passesTest

protected boolean passesTest(String part)
Determines whether or not part (which is some part of a File's full path) passes this filter's test.

The implementation here always throws an IllegalStateException.

Subclasses must either override this method or ensure that it is never called. There are two ways that they can achieve the latter. First, they could make FileMode/DirectoryMode/OtherMode choices that cover all cases before any other detail of the file is considered. This is the approach taken by DirectoryFilter and NormalFileFilter. Second, they could override one or more of the methods in this method's call chain (i.e. override passesTest(File), acceptImpl, accept). in a manner that does not call the implementation here. This is the approach taken by many classes, such as TarableFilter and VisibleFilter.

This method is not abstract to avoid forcing subclasses which do not call it (as described above) to implement it.


getDescription

public abstract String getDescription()

Specified by:
getDescription in class FileFilter