com.mucommander.file.impl
Class CachedFile

java.lang.Object
  com.mucommander.file.AbstractFile
      com.mucommander.file.impl.ProxyFile
          com.mucommander.file.impl.CachedFile

All Implemented Interfaces:

PermissionAccesses, PermissionTypes

public class CachedFile
extends ProxyFile

CachedFile is a ProxyFile that caches the return values of most AbstractFile getter methods. This allows to limit the number of calls to the underlying file methods which can have a cost since they often are I/O bound. The methods that are cached are those overridden by this class, except for the ls methods, which are overridden only to allow recursion (see CachedFile(com.mucommander.file.AbstractFile, boolean)).

The values are retrieved and cached only when the 'cached methods' are called for the first time; they are not preemptively retrieved in the constructor, so using this class has no negative impact on performance, except for the small extra CPU cost added by proxying the methods and the extra RAM used to store cached values.

Once the values are retrieved and cached, they never change: the same value will always be returned once a method has been called for the first time. That means if the underlying file changes (e.g. its size or date has changed), the changes will not be reflected by this CachedFile. Thus, this class should only be used when a 'real-time' view of the file is not required, or when the file instance is used only for a small amount of time.

Author:

Maxence Bernard

Field Summary

Fields inherited from class com.mucommander.file.impl.ProxyFile

file

Fields inherited from class com.mucommander.file.AbstractFile

DEFAULT_SEPARATOR, fileURL, IO_BUFFER_SIZE, MUST_HINT, MUST_NOT_HINT, SHOULD_HINT, SHOULD_NOT_HINT, windowsDriveRootPattern

Fields inherited from interface com.mucommander.file.PermissionTypes

EXECUTE_PERMISSION, READ_PERMISSION, WRITE_PERMISSION

Fields inherited from interface com.mucommander.file.PermissionAccesses

GROUP_ACCESS, OTHER_ACCESS, USER_ACCESS

Constructor Summary

CachedFile(AbstractFile file, boolean recursiveInstances)
Creates a new CachedFile instance around the specified AbstractFile, caching returned values of cached methods as they are called.

Method Summary

boolean	canRunProcess() Returns true if it's possible to run processes on the underlying file system.
boolean	exists() Returns true if this file exists.
java.lang.String	getAbsolutePath() Returns the absolute path to this file: For local files, the sole path is returned, and not a URL with the scheme and host parts (e.g.
AbstractFile	getCanonicalFile() Returns an AbstractFile representing the canonical path of this file, or this if the absolute and canonical path of this file are identical. Note that the returned file may or may not exist, for example if this file is a symlink to a file that doesn't exist.
java.lang.String	getCanonicalPath() Returns the canonical path to this file, resolving any symbolic links or '..' and '.' occurrences.
long	getDate() Returns this file's last modified date, in milliseconds since the epoch (00:00:00 GMT, January 1, 1970).
java.lang.String	getExtension() Returns this file's extension, null if this file's name doesn't have an extension.
long	getFreeSpace() Returns the free space (in bytes) on the disk/volume where this file is, -1 if this information is not available.
java.lang.String	getGroup() Returns information about the group this file belongs to.
java.lang.String	getName() Returns this file's name.
java.lang.String	getOwner() Returns information about the owner of this file.
AbstractFile	getParent() Returns this file's parent, null if it doesn't have one.
FilePermissions	getPermissions() Returns this file's permissions, as a FilePermissions object.
java.lang.String	getPermissionsString() Returns a string representation of this file's permissions.
AbstractFile	getRoot() Returns the root folder that contains this file either as a direct or an indirect child.
long	getSize() Returns this file's size in bytes, 0 if this file doesn't exist, -1 if the size is undetermined.
long	getTotalSpace() Returns the total space (in bytes) of the disk/volume where this file is, -1 if this information is not available.
boolean	isBrowsable() Returns true if this file is browsable.
boolean	isDirectory() Returns true if this file is a directory, false in any of the following cases: this file does not exist this file is a regular file this file is browsable (as reported by AbstractFile.isBrowsable() but not a directory
boolean	isHidden() Returns true if this file is hidden.
boolean	isRoot() Returns true if this file is a root folder.
boolean	isSymlink() Returns true if this file is a symbolic link.
AbstractFile[]	ls() Returns the children files that this file contains.
AbstractFile[]	ls(FileFilter filter) Returns the children files that this file contains, filtering out files that do not match the specified FileFilter.
AbstractFile[]	ls(FilenameFilter filter) Returns the children files that this file contains, filtering out files that do not match the specified FilenameFilter.

Methods inherited from class com.mucommander.file.impl.ProxyFile

canChangeDate, canGetGroup, canGetOwner, changeDate, changePermission, changePermissions, copyStream, copyTo, delete, deleteRecursively, equals, getChangeablePermissions, getCopyToHint, getInputStream, getInputStream, getJavaNetURL, getMoveToHint, getOutputStream, getProxiedFile, getRandomAccessInputStream, getRandomAccessOutputStream, getSeparator, getUnderlyingFileObject, getURL, hashCode, hasRandomAccessInputStream, hasRandomAccessOutputStream, importPermissions, importPermissions, mkdir, mkfile, moveTo, runProcess, setParent, toString

Methods inherited from class com.mucommander.file.AbstractFile

addTrailingSeparator, calculateChecksum, calculateChecksum, calculateChecksum, changePermissions, checkCopyPrerequisites, copyRecursively, deleteRecursively, getAbsolutePath, getAncestor, getAncestor, getCanonicalPath, getChild, getDirectChild, getExtension, getIcon, getIcon, getNameWithoutExtension, getParentArchive, getParentSilently, getTopAncestor, hasAncestor, hasAncestor, isParentOf, mkdir, mkdirs, mkfile, removeTrailingSeparator

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

CachedFile

public CachedFile(AbstractFile file,
                  boolean recursiveInstances)

Creates a new CachedFile instance around the specified AbstractFile, caching returned values of cached methods as they are called. If recursion is enabled, the methods returning AbstractFile will return CachedFile instances, allowing the cache files recursively.

Parameters:

file - the AbstractFile instance for which returned values of getter methods should be cached

recursiveInstances - if true, AbstractFile instances returned by this class will be wrapped into CachedFile instances

Method Detail

getSize

public long getSize()

Description copied from class: AbstractFile

Returns this file's size in bytes, 0 if this file doesn't exist, -1 if the size is undetermined.

Overrides:

getSize in class ProxyFile

Returns:

this file's size in bytes, 0 if this file doesn't exist, -1 if the size is undetermined

getDate

public long getDate()

Description copied from class: AbstractFile

Returns this file's last modified date, in milliseconds since the epoch (00:00:00 GMT, January 1, 1970).

Overrides:

getDate in class ProxyFile

Returns:

this file's last modified date, in milliseconds since the epoch (00:00:00 GMT, January 1, 1970)

canRunProcess

public boolean canRunProcess()

Description copied from class: AbstractFile

Returns true if it's possible to run processes on the underlying file system.

Overrides:

canRunProcess in class ProxyFile

Returns:

true if it's possible to run processes on the underlying file system, false otherwise.

isSymlink

public boolean isSymlink()

Description copied from class: AbstractFile

Returns true if this file is a symbolic link. Symbolic links need to be handled with special care, especially when manipulating files recursively.

Overrides:

isSymlink in class ProxyFile

Returns:

true if this file is a symbolic link

isDirectory

public boolean isDirectory()

Description copied from class: AbstractFile

Returns true if this file is a directory, false in any of the following cases:

• this file does not exist
• this file is a regular file
• this file is browsable (as reported by AbstractFile.isBrowsable() but not a directory

Overrides:

isDirectory in class ProxyFile

Returns:

true if this file is a directory, false in any of the cases listed above

isBrowsable

public boolean isBrowsable()

Description copied from class: AbstractFile

Returns true if this file is browsable. A file is considered browsable if it contains children files that can be exposed by calling the ls() methods. AbstractArchiveFile implementations will usually return true, as will directories (directories are always browsable).

Overrides:

isBrowsable in class ProxyFile

Returns:

true if this file is browsable

isHidden

public boolean isHidden()

Description copied from class: AbstractFile

Returns true if this file is hidden.

This default implementation is solely based on the filename and returns true if this file's name starts with '.'. This method should be overriden if the underlying filesystem has a notion of hidden files.

Overrides:

isHidden in class ProxyFile

Returns:

true if this file is hidden

getAbsolutePath

public java.lang.String getAbsolutePath()

Description copied from class: AbstractFile

Returns the absolute path to this file:

• For local files, the sole path is returned, and not a URL with the scheme and host parts (e.g. /path/to/file, not file://localhost/path/to/file)
• For any other file protocol, the full URL including the protocol and host parts is returned (e.g. smb://192.168.1.1/root/blah)

The returned path will always be free of any login and password and thus can be safely displayed or stored.

Overrides:

getAbsolutePath in class ProxyFile

Returns:

the absolute path to this file

getCanonicalPath

public java.lang.String getCanonicalPath()

Description copied from class: AbstractFile

Returns the canonical path to this file, resolving any symbolic links or '..' and '.' occurrences.

This implementation simply returns the value of AbstractFile.getAbsolutePath(), and thus should be overridden if canonical path resolution is available.

Overrides:

getCanonicalPath in class ProxyFile

Returns:

the canonical path to this file

getExtension

public java.lang.String getExtension()

Description copied from class: AbstractFile

Returns this file's extension, null if this file's name doesn't have an extension.

A filename has an extension if and only if:
- it contains at least one . character
- the last . is not the last character of the filename
- the last . is not the first character of the filename

Overrides:

getExtension in class ProxyFile

Returns:

this file's extension, null if this file's name doesn't have an extension

getName

public java.lang.String getName()

Description copied from class: AbstractFile

Returns this file's name.

The returned name is the filename extracted from this file's FileURL as returned by FileURL.getFilename(). If the filename is null (e.g. http://google.com), the FileURL's host will be returned instead. If the host is null (e.g. smb://), an empty String will be returned. Thus, the returned name will never be null.

This method should be overridden if a special processing (e.g. URL-decoding) needs to be applied to the returned filename.

Overrides:

getName in class ProxyFile

Returns:

this file's name

getFreeSpace

public long getFreeSpace()

Description copied from class: AbstractFile

Returns the free space (in bytes) on the disk/volume where this file is, -1 if this information is not available.

Overrides:

getFreeSpace in class ProxyFile

Returns:

the free space (in bytes) on the disk/volume where this file is, -1 if this information is not available.

getTotalSpace

public long getTotalSpace()

Description copied from class: AbstractFile

Returns the total space (in bytes) of the disk/volume where this file is, -1 if this information is not available.

Overrides:

getTotalSpace in class ProxyFile

Returns:

the total space (in bytes) of the disk/volume where this file is, -1 if this information is not available

exists

public boolean exists()

Description copied from class: AbstractFile

Returns true if this file exists.

Overrides:

exists in class ProxyFile

Returns:

true if this file exists

getPermissions

public FilePermissions getPermissions()

Description copied from class: AbstractFile

Returns this file's permissions, as a FilePermissions object. Note that this file may only support certain permission bits, use the permission mask to find out which bits are supported.

This method may return permissions for which none of the bits are supported, but may never return null.

Overrides:

getPermissions in class ProxyFile

Returns:

this file's permissions, as a FilePermissions object

getPermissionsString

public java.lang.String getPermissionsString()

Description copied from class: AbstractFile

Returns a string representation of this file's permissions.

The first character is 'l' if this file is a symbolic link,'d' if it is a directory, '-' otherwise. Then the string contains up to 3 character triplets, for each of the 'user', 'group' and 'other' access types, each containing the following characters:

• 'r' if this file has read permission, '-' otherwise
• 'w' if this file has write permission, '-' otherwise
• 'x' if this file has executable permission, '-' otherwise

The first character triplet for 'user' access will always be added to the permissions. Then the 'group' and 'other' triplets will only be added if at least one of the user permission bits is supported, as tested with this file's permissions mask. Here are a couple examples to illustrate:

• a directory for which the file permissions' mask is 0 will return the string d---, no matter what permission values the FilePermissions returned by AbstractFile.getPermissions() contains
.
• a regular file for which the file permissions' mask returns 777 (full permissions support) and which has read/write/executable permissions for all three 'user', 'group' and 'other' access types will return -rwxrwxrwx
.

Overrides:

getPermissionsString in class ProxyFile

Returns:

a string representation of this file's permissions

getOwner

public java.lang.String getOwner()

Description copied from class: AbstractFile

Returns information about the owner of this file. The kind of information that is returned is implementation-dependant. It may typically be a username (e.g. 'bob') or a user ID (e.g. '501'). If the owner information is not available to the AbstractFile implementation (cannot be retrieved or the filesystem doesn't have any notion of owner) or not available for this particular file, null will be returned.

Overrides:

getOwner in class ProxyFile

Returns:

information about the owner of this file

getGroup

public java.lang.String getGroup()

Description copied from class: AbstractFile

Returns information about the group this file belongs to. The kind of information that is returned is implementation-dependant. It may typically be a group name (e.g. 'www-data') or a group ID (e.g. '501'). If the group information is not available to the AbstractFile implementation (cannot be retrieved or the filesystem doesn't have any notion of owner) or not available for this particular file, null will be returned.

Overrides:

getGroup in class ProxyFile

Returns:

information about the owner of this file

isRoot

public boolean isRoot()

Description copied from class: AbstractFile

Returns true if this file is a root folder.

This default implementation characterizes root folders in the following way:

• For local files under Windows: if the path corresponds a drive's root ('C:\' for instance)
• For local files under other OS: if the path is "/"
• For any other file kinds: if the FileURL's path is '/'

Overrides:

isRoot in class ProxyFile

Returns:

true if this file is a root folder

getParent

public AbstractFile getParent()
                       throws java.io.IOException

Description copied from class: AbstractFile

Returns this file's parent, null if it doesn't have one.

Overrides:

getParent in class ProxyFile

Returns:

this file's parent, null if it doesn't have one

Throws:

java.io.IOException - if the parent file could not be instanciated

getRoot

public AbstractFile getRoot()
                     throws java.io.IOException

Description copied from class: AbstractFile

Returns the root folder that contains this file either as a direct or an indirect child. If this file is already a root folder (has no parent), this is returned.

Overrides:

getRoot in class ProxyFile

Returns:

the root folder that contains this file

Throws:

java.io.IOException - if the root file or one parent file could not be instanciated

getCanonicalFile

public AbstractFile getCanonicalFile()

Description copied from class: AbstractFile

Returns an AbstractFile representing the canonical path of this file, or this if the absolute and canonical path of this file are identical.
Note that the returned file may or may not exist, for example if this file is a symlink to a file that doesn't exist.

Overrides:

getCanonicalFile in class ProxyFile

Returns:

an AbstractFile representing the canonical path of this file, or this if the absolute and canonical path of this file are identical.

ls

public AbstractFile[] ls()
                  throws java.io.IOException

Description copied from class: AbstractFile

Returns the children files that this file contains. For this operation to be successful, this file must be 'browsable', i.e. AbstractFile.isBrowsable() must return true. This method may return a zero-length array if it has no children but may never return null.

Overrides:

ls in class ProxyFile

Returns:

the children files that this file contains

Throws:

java.io.IOException - if this operation is not possible (file is not browsable) or if an error occurred.

ls

public AbstractFile[] ls(FileFilter filter)
                  throws java.io.IOException

Description copied from class: AbstractFile

Returns the children files that this file contains, filtering out files that do not match the specified FileFilter. For this operation to be successful, this file must be 'browsable', i.e. AbstractFile.isBrowsable() must return true.

Overrides:

ls in class ProxyFile

Parameters:

filter - the FileFilter to be used to filter files out from the list, may be null

Returns:

the children files that this file contains

Throws:

java.io.IOException - if this operation is not possible (file is not browsable) or if an error occurred.

ls

public AbstractFile[] ls(FilenameFilter filter)
                  throws java.io.IOException

Description copied from class: AbstractFile

Returns the children files that this file contains, filtering out files that do not match the specified FilenameFilter. For this operation to be successful, this file must be 'browsable', i.e. AbstractFile.isBrowsable() must return true.

This default implementation filters out files *after* they have been created. This method should be overridden if a more efficient implementation can be provided by subclasses.

Overrides:

ls in class ProxyFile

Parameters:

filter - the FilenameFilter to be used to filter out files from the list, may be null

Returns:

the children files that this file contains

Throws:

java.io.IOException - if this operation is not possible (file is not browsable) or if an error occurred.