AbstractFile (muCommander API)

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

com.mucommander.file
Class AbstractFile

java.lang.Object
  com.mucommander.file.AbstractFile

All Implemented Interfaces:: PermissionAccesses, PermissionTypes

Direct Known Subclasses:: ArchiveEntryFile, BookmarkFile, DummyFile, FTPFile, HTTPFile, LocalFile, NFSFile, ProxyFile, SFTPFile, SMBFile

public abstract class AbstractFile
extends java.lang.Object
implements PermissionTypes, PermissionAccesses
extends java.lang.Object
implements PermissionTypes, PermissionAccesses

AbstractFile is the superclass of all files.

AbstractFile classes should never be instanciated directly. Instead, the FileFactory getFile methods should be used to get a file instance from a path or FileURL location.

Author:: Maxence Bernard
See Also:: FileFactory, ProxyFile

Field Summary
`static java.lang.String`	`DEFAULT_SEPARATOR` Default path separator
`protected FileURL`	`fileURL` URL representing this file
`static int`	`IO_BUFFER_SIZE` Size of the read/write buffer
`static int`	`MUST_HINT` Indicates `copyTo(AbstractFile)`/`moveTo(AbstractFile)` must be used to copy/move the file (e.g.
`static int`	`MUST_NOT_HINT` Indicates `copyTo(AbstractFile)`/`moveTo(AbstractFile)` must not be used to copy/move the file (e.g.
`static int`	`SHOULD_HINT` Indicates `copyTo(AbstractFile)`/`moveTo(AbstractFile)` should be used to copy/move the file (e.g.
`static int`	`SHOULD_NOT_HINT` Indicates `copyTo(AbstractFile)`/`moveTo(AbstractFile)` should not be used to copy/move the file (default)
`protected static java.util.regex.Pattern`	`windowsDriveRootPattern` Pattern matching Windows drive root folders, e.g.

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
`protected`	`AbstractFile(FileURL url)` Creates a new file instance with the given URL.

Method Summary
`protected java.lang.String`	`addTrailingSeparator(java.lang.String path)` Tests if the given path contains a trailing separator, and if not, adds one to the returned path.
`static java.lang.String`	`calculateChecksum(java.io.InputStream in, java.security.MessageDigest messageDigest)` Returns the checksum (also referred to as hash or digest) of the given `InputStream` calculated by reading the stream and feeding the bytes to the given `MessageDigest` until EOF is reached.
`java.lang.String`	`calculateChecksum(java.security.MessageDigest messageDigest)` Returns a checksum of this file (also referred to as hash or digest) calculated by reading this file's contents and feeding the bytes to the given `MessageDigest`, until EOF is reached.
`java.lang.String`	`calculateChecksum(java.lang.String algorithm)` Returns a checksum of this file (also referred to as hash or digest) calculated by reading this file's contents and feeding the bytes to the given `MessageDigest`, until EOF is reached.
`abstract boolean`	`canChangeDate()` Returns `true` if this file's date can be changed using `changeDate(long)`.
`abstract boolean`	`canGetGroup()` Returns `true` if this file implementation is able to return some information about file groups, not necessarily for all files or this file in particular but at least for some of them.
`abstract boolean`	`canGetOwner()` Returns `true` if this file implementation is able to return some information about file owners, not necessarily for all files or this file in particular but at least for some of them.
`abstract boolean`	`canRunProcess()` Returns `true` if it's possible to run processes on the underlying file system.
`abstract boolean`	`changeDate(long lastModified)` Changes last modified date and returns `true` if date was changed successfully, `false` if the operation could not be completed, either because this method is not implemented for this file type, or because of insufficient permissions or a low-level I/O error.
`abstract boolean`	`changePermission(int access, int permission, boolean enabled)` Changes the specified permission bit.
`boolean`	`changePermissions(FilePermissions permissions)` Convenience method that calls `changePermissions(int)` with the given permissions' int value.
`boolean`	`changePermissions(int permissions)` Changes this file's permissions to the specified permissions int and returns `true` if the operation was successful, `false` if at least one of the file permissions could not be changed.
`protected void`	`checkCopyPrerequisites(AbstractFile destFile, boolean allowCaseVariations)` Checks the prerequisites of a copy (or move) operation.
`protected void`	`copyRecursively(AbstractFile sourceFile, AbstractFile destFile)` Copies the source file to the destination one and recurses on directory contents.
`void`	`copyStream(java.io.InputStream in, boolean append)` Copies the contents of the given `InputStream` to this file.
`boolean`	`copyTo(AbstractFile destFile)` Copies this file to a specified destination file, overwriting the destination if it exists.
`abstract void`	`delete()` Deletes this file and this file only (does not recurse on folders).
`void`	`deleteRecursively()` Deletes this file.
`protected void`	`deleteRecursively(AbstractFile file)` Deletes the given file.
`boolean`	`equals(java.lang.Object f)` Tests a file for equality: returns `true` if the given file has the same canonical path, as returned by `getCanonicalPath()`.
`abstract 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.
`java.lang.String`	`getAbsolutePath(boolean appendSeparator)` Returns the absolute path to this file.
`AbstractFile`	`getAncestor()` Returns the immediate ancestor of this `AbstractFile` if it has one, `this` otherwise: if this file is a `ProxyFile`, returns the return value of `ProxyFile.getProxiedFile()` if this file is not a `ProxyFile`, returns `this`
`AbstractFile`	`getAncestor(java.lang.Class abstractFileClass)` Returns the first ancestor of this file that is an instance of the given Class or of a subclass of the given Class, or `this` if this instance's class matches those criteria.
`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.
`java.lang.String`	`getCanonicalPath(boolean appendSeparator)` Returns the canonical path to this file, resolving any symbolic links or '..' and '.' occurrences.
`abstract PermissionBits`	`getChangeablePermissions()` Returns a bit mask describing the permission bits that can be changed on this file when calling `changePermission(int, int, boolean)` and `changePermissions(int)`.
`AbstractFile`	`getChild(java.lang.String relativePath)` Returns a child of this file, whose path is the concatenation of this file's path and the given relative path.
`int`	`getCopyToHint(AbstractFile destFile)` Returns a hint that indicates whether the `copyTo(AbstractFile)` method should be used to copy this file to the specified destination file, rather than copying the file 'manually', using `copyStream(InputStream, boolean)`, or `getInputStream()` and `getOutputStream(boolean)`.
`abstract long`	`getDate()` Returns this file's last modified date, in milliseconds since the epoch (00:00:00 GMT, January 1, 1970).
`AbstractFile`	`getDirectChild(java.lang.String filename)` Returns a direct child of this file, whose path is the concatenation of this file's path and the given filename.
`java.lang.String`	`getExtension()` Returns this file's extension, `null` if this file's name doesn't have an extension.
`static java.lang.String`	`getExtension(java.lang.String filename)` Returns the given filename's extension, `null` if the filename doesn't have an extension.
`abstract long`	`getFreeSpace()` Returns the free space (in bytes) on the disk/volume where this file is, `-1` if this information is not available.
`abstract java.lang.String`	`getGroup()` Returns information about the group this file belongs to.
`javax.swing.Icon`	`getIcon()` Returns an icon representing this file, using the default `FileIconProvider` registered in `FileFactory`.
`javax.swing.Icon`	`getIcon(java.awt.Dimension preferredResolution)` Returns an icon representing this file, using the default `FileIconProvider` registered in `FileFactory`.
`abstract java.io.InputStream`	`getInputStream()` Returns an `InputStream` to read the contents of this file.
`java.io.InputStream`	`getInputStream(long offset)` Returns an `InputStream` to read this file's contents, starting at the specified offset (in bytes).
`java.net.URL`	`getJavaNetURL()` Creates and returns a `java.net.URL` referring to the same location as the `FileURL` associated with this `AbstractFile`.
`int`	`getMoveToHint(AbstractFile destFile)` Returns a hint that indicates whether the `moveTo(AbstractFile)` method should be used to move this file to the specified destination file, rather than moving the file using `copyStream(InputStream, boolean)` or `getInputStream()` and `getOutputStream(boolean)`.
`java.lang.String`	`getName()` Returns this file's name.
`java.lang.String`	`getNameWithoutExtension()` Returns the name of the file without its extension.
`abstract java.io.OutputStream`	`getOutputStream(boolean append)` Returns an `OuputStream` to write the contents of this file, appending or overwriting the existing contents.
`abstract java.lang.String`	`getOwner()` Returns information about the owner of this file.
`abstract AbstractFile`	`getParent()` Returns this file's parent, `null` if it doesn't have one.
`AbstractArchiveFile`	`getParentArchive()` Convenience method that returns the parent `AbstractArchiveFile` that contains this file.
`AbstractFile`	`getParentSilently()` Convience method that returns this file's parent, `null` if it doesn't have one or if it couldn't be instanciated.
`abstract FilePermissions`	`getPermissions()` Returns this file's permissions, as a `FilePermissions` object.
`java.lang.String`	`getPermissionsString()` Returns a string representation of this file's permissions.
`abstract RandomAccessInputStream`	`getRandomAccessInputStream()` Returns a `RandomAccessInputStream` to read the contents of this file with random access.
`abstract RandomAccessOutputStream`	`getRandomAccessOutputStream()` Returns a `RandomAccessOutputStream` to write the contents of this file with random access.
`AbstractFile`	`getRoot()` Returns the root folder that contains this file either as a direct or an indirect child.
`java.lang.String`	`getSeparator()` Returns the path separator used by this file.
`abstract long`	`getSize()` Returns this file's size in bytes, `0` if this file doesn't exist, `-1` if the size is undetermined.
`AbstractFile`	`getTopAncestor()` Iterates through the ancestors returned by `getAncestor()` until the top-most ancestor is reached and returns it.
`abstract long`	`getTotalSpace()` Returns the total space (in bytes) of the disk/volume where this file is, -1 if this information is not available.
`abstract java.lang.Object`	`getUnderlyingFileObject()` Returns the file Object of the underlying API providing access to the filesystem.
`FileURL`	`getURL()` Returns the `FileURL` instance that represents this file's location.
`boolean`	`hasAncestor()` Returns `true` if this `AbstractFile` has an ancestor, i.e.
`boolean`	`hasAncestor(java.lang.Class abstractFileClass)` Returns `true` if this file is or has an ancestor (immediate or not) that is an instance of the given `Class` or of a subclass of the `Class`.
`int`	`hashCode()`
`abstract boolean`	`hasRandomAccessInputStream()` Returns `true` if the underlying filesystem has support for random access input streams.
`abstract boolean`	`hasRandomAccessOutputStream()` Returns `true` if the underlying filesystem has support for random access output streams.
`void`	`importPermissions(AbstractFile sourceFile)` This method is a shorthand for `importPermissions(AbstractFile, FilePermissions)` called with `FilePermissions.DEFAULT_DIRECTORY_PERMISSIONS` if this file is a directory or `FilePermissions.DEFAULT_FILE_PERMISSIONS` if this file is a regular file.
`void`	`importPermissions(AbstractFile sourceFile, FilePermissions defaultPermissions)` Imports the given source file's permissions, overwriting this file's permissions.
`boolean`	`isBrowsable()` Returns `true` if this file is browsable.
`abstract 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 `isBrowsable()` but not a directory
`boolean`	`isHidden()` Returns `true` if this file is hidden.
`boolean`	`isParentOf(AbstractFile file)` Returns `true` if this file is a parent folder of the given file, or if the two files are equal.
`boolean`	`isRoot()` Returns `true` if this file is a root folder.
`abstract boolean`	`isSymlink()` Returns `true` if this file is a symbolic link.
`abstract 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.
`abstract void`	`mkdir()` Creates this file as a directory.
`void`	`mkdir(java.lang.String name)` Convenience method that creates a directory as a direct child of this directory.
`void`	`mkdirs()` Creates this file as a directory and any parent directory that does not already exist.
`void`	`mkfile()` Creates this file as an empty, non-directory file.
`void`	`mkfile(java.lang.String name)` Convenience method that creates a file as a direct child of this directory.
`boolean`	`moveTo(AbstractFile destFile)` Moves this file to a specified destination file, overwriting the destination if it exists.
`protected java.lang.String`	`removeTrailingSeparator(java.lang.String path)` Tests if the given path contains a trailing separator, and if it does, removes it from the returned path.
`abstract AbstractProcess`	`runProcess(java.lang.String[] tokens)` Creates a process executing the specified command tokens using this file as a working directory.
`abstract void`	`setParent(AbstractFile parent)` Sets this file's parent.
`java.lang.String`	`toString()` Returns a String representation of this file.

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

Field Detail

fileURL

protected FileURL fileURL

URL representing this file

DEFAULT_SEPARATOR

public static final java.lang.String DEFAULT_SEPARATOR

Default path separator

See Also:: Constant Field Values

SHOULD_HINT

public static final int SHOULD_HINT

Indicates copyTo(AbstractFile)/moveTo(AbstractFile) *should* be used to copy/move the file (e.g. more efficient)

See Also:: Constant Field Values

SHOULD_NOT_HINT

public static final int SHOULD_NOT_HINT

Indicates copyTo(AbstractFile)/moveTo(AbstractFile) *should not* be used to copy/move the file (default)

See Also:: Constant Field Values

MUST_HINT

public static final int MUST_HINT

Indicates copyTo(AbstractFile)/moveTo(AbstractFile) *must* be used to copy/move the file (e.g. no other way to do so)

See Also:: Constant Field Values

MUST_NOT_HINT

public static final int MUST_NOT_HINT

Indicates copyTo(AbstractFile)/moveTo(AbstractFile) *must not* be used to copy/move the file (e.g. not implemented)

See Also:: Constant Field Values

IO_BUFFER_SIZE

public static final int IO_BUFFER_SIZE

Size of the read/write buffer

See Also:: Constant Field Values

windowsDriveRootPattern

protected static final java.util.regex.Pattern windowsDriveRootPattern

Pattern matching Windows drive root folders, e.g. C:\

Constructor Detail

AbstractFile

protected AbstractFile(FileURL url)

Creates a new file instance with the given URL.

Parameters:: url - the FileURL instance that represents this file's location

Method Detail

getURL

public FileURL getURL()

Returns the FileURL instance that represents this file's location.

Returns:: the FileURL instance that represents this file's location

getJavaNetURL

public java.net.URL getJavaNetURL()
                           throws java.net.MalformedURLException

Creates and returns a java.net.URL referring to the same location as the FileURL associated with this AbstractFile. The java.net.URL is created from the string representation of this file's FileURL. Thus, any credentials this FileURL contains are preserved, but properties are lost.

The returned URL uses this AbstractFile to access the associated resource, via the underlying URLConnection which delegates to this class.

It is important to note that this method is provided for interoperability purposes, for the sole purpose of connecting to APIs that require a java.net.URL.

Returns:: a java.net.URL referring to the same location as this FileURL
Throws:: java.net.MalformedURLException - if the java.net.URL could not parse the location of this FileURL

getName

public java.lang.String getName()

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.

Returns:: this file's name

getExtension

public java.lang.String getExtension()

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

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

getAbsolutePath

public 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. /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.

Returns:: the absolute path to this file

getCanonicalPath

public java.lang.String getCanonicalPath()

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

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

Returns:: the canonical path to this file

getCanonicalFile

public 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.

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





getSeparator
public java.lang.String getSeparator()

Returns the path separator used by this file.

 This default implementation returns the default separator "/", this method should be overridden if the path
 separator used by the file implementation is different.






Returns:
the path separator used by this file





isBrowsable
public boolean isBrowsable()

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).






Returns:
true if this file is browsable





isHidden
public boolean isHidden()

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.






Returns:
true if this file is hidden





getRoot
public AbstractFile getRoot()
                     throws java.io.IOException

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.






Returns:
the root folder that contains this file
Throws:
java.io.IOException - if the root file or one parent file could not be instanciated





isRoot
public boolean isRoot()

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 '/'
 
 






Returns:
true if this file is a root folder





getInputStream
public java.io.InputStream getInputStream(long offset)
                                   throws java.io.IOException

Returns an InputStream to read this file's contents, starting at the specified offset (in bytes).
 A java.io.IOException is thrown if the file doesn't exist. 

 This method should be overridden whenever possible to provide a more efficient implementation as this
 default implementation uses InputStream.skip(long) which, depending on the particular InputStream
 implementation may just read bytes and discards them, which is very slow.





Parameters:
offset - the offset in bytes from the beginning of the file, must be >0
Returns:
an InputStream to read this file's contents, skipping the specified number of bytes
Throws:
java.io.IOException - if this file cannot be read or is a folder.





copyStream
public void copyStream(java.io.InputStream in,
                       boolean append)
                throws FileTransferException

Copies the contents of the given InputStream to this file. The provided InputStream
 will *NOT* be closed by this method.
 
 This method should be overridden by file protocols that do not offer a getOutputStream(boolean)
 implementation, but that can take an InputStream and use it to write the file.

 Read and write operations are buffered, with a buffer of IO_BUFFER_SIZE bytes. For performance
 reasons, this buffer is provided by BufferPool. There is no need to provide a BufferedInputStream.

 Copy progress can optionally be monitored by supplying a CounterInputStream.





Parameters:
in - the InputStream to read from
append - if true, data written to the OutputStream will be appended to the end of this file. If false, any existing data will be overwritten.
Throws:
FileTransferException - if something went wrong while reading from the InputStream or writing to this file





checkCopyPrerequisites
protected final void checkCopyPrerequisites(AbstractFile destFile,
                                            boolean allowCaseVariations)
                                     throws FileTransferException

Checks the prerequisites of a copy (or move) operation.
 Throws a FileTransferException in any of the following conditions are true, does nothing otherwise:
 
   this file does not exist
   this file and the destination file are the same, unless allowCaseVariations is true
 and the destination filename is a case variation of the source
   this file is a parent of the destination file
 





Parameters:
destFile - the destination file to copy this file to
allowCaseVariations - if true and the destination file is a case variation of source, no exception will be thrown
Throws:
FileTransferException - in any of the cases listed above, use FileTransferException.getReason() to
 know the reason.





copyTo
public boolean copyTo(AbstractFile destFile)
               throws FileTransferException

Copies this file to a specified destination file, overwriting the destination if it exists. If this file is a
 directory, any file or directory it contains will also be copied.

 This method returns true if the operation was successfully completed, false if the
 operation could not be performed because of unsatisfied conditions (not an error).
 A FileTransferException if the operation was attempted but failed for any of the following reasons:
 

  this file and the destination file are the same
  this file is a directory and a parent of the destination file (operation would otherwise loop indefinitely)
  this file (or one if its child) could not be read
  the destination file (or one of its child) could not be written
  an I/O error occurred
 
 

 This generic implementation will always attempt to copy files, thus either return true or
 throw an exception, but will never return false. Symbolic links are skipped when encountered:
 neither the link nor the linked file is copied. Also noteworthy is that no clean up is performed if an error
 occurs in the midst of a transfer: files that have been copied (even partially) are left in the destination.

 This method should be overridden by filesystems which are able to provide a more efficient implementation --
 in particular, network-based filesystems that can perform a server-to-server copy.





Parameters:
destFile - the destination file to copy this file to
Returns:
true if the operation could be successfully be completed, false if the operation could not be performed
 because of unsatisfied conditions (not an error)
Throws:
FileTransferException - in any of the cases listed above, use FileTransferException.getReason() to
 know the reason.





getCopyToHint
public int getCopyToHint(AbstractFile destFile)

Returns a hint that indicates whether the copyTo(AbstractFile) method should be used to
 copy this file to the specified destination file, rather than copying the file 'manually', using
 copyStream(InputStream, boolean), or getInputStream() and getOutputStream(boolean).

 Potential returned values are:
 

 SHOULD_HINT if copyTo() should be preferred (more efficient)
 
SHOULD_NOT_HINT if the file should rather be copied using copyStream()
 
MUST_HINT if the file can only be copied using copyTo(), that's the case when getOutputStream() or copyStream() is not implemented
 
MUST_NOT_HINT if the file can only be copied using copyStream()
 
 

 This default implementation returns SHOULD_NOT_HINT as some granularity is lost when using
  copyTo() making it impossible to monitor progress when copying a file.
 This method should be overridden when copyTo() should be favored over copyStream().





Parameters:
destFile - the destination file that is considered being copied
Returns:
the hint int indicating whether the copyTo(AbstractFile) method should be used





moveTo
public boolean moveTo(AbstractFile destFile)
               throws FileTransferException

Moves this file to a specified destination file, overwriting the destination if it exists. If this file is a
 directory, any file or directory it contains will also be moved.
 After normal completion, this file will not exist anymore: exists() will return false.

 This method returns true if the operation was successfully completed, false if the
 operation could not be performed because of unsatisfied conditions (not an error).
 A FileTransferException if the operation was attempted but failed for any of the following reasons:
 

  this file and the destination file are the same
  this file is a directory and a parent of the destination file (operation would otherwise loop indefinitely)
  this file (or one if its child) could not be read
  this file (or one of its child) could not be written
  the destination file (or one of its children) could not be written
  an I/O error occurred
 
 

 This generic implementation will always attempt to move files, thus either return true or
 throw an exception, but will never return false.
 Symbolic links are not moved to the destination when encountered: neither the link nor the linked file is moved,
 and the symlink file is deleted.

 This implementation first copies the file and it contents (if any) and then deletes it. Deletion occurs only
 after all files have been successfully copied. Also noteworthy is that no clean up is performed if an error
 occurs in the midst of a transfer: files that have been copied (even partially) are left in the destination.

 This method should be overridden by filesystems which are able to provide a more efficient implementation --
 in particular, network-based filesystems that can perform remote renaming.





Parameters:
destFile - the destination file to move this file to
Returns:
true if the operation could be successfully be completed, false if the operation could not be performed
 because of unsatisfied conditions (not an error)
Throws:
FileTransferException - in any of the cases listed above, use FileTransferException.getReason() to
 know the reason.





getMoveToHint
public int getMoveToHint(AbstractFile destFile)

Returns a hint that indicates whether the moveTo(AbstractFile) method should be used to
 move this file to the specified destination file, rather than moving the file using
 copyStream(InputStream, boolean) or getInputStream() and getOutputStream(boolean).

 Potential returned values are:
 

 SHOULD_HINT if copyTo() should be preferred (more efficient)
 
SHOULD_NOT_HINT if the file should rather be copied using copyStream()
 
MUST_HINT if the file can only be copied using copyTo(), that's the case when getOutputStream() or copyStream() is not implemented
 
MUST_NOT_HINT if the file can only be copied using copyStream()
 
 

 This default implementation returns SHOULD_HINT if both this file and the specified destination file
 use the same protocol and are located on the same host, SHOULD_NOT_HINT otherwise.
 This method should be overridden to return SHOULD_NOT_HINT if the underlying file protocol doesn't not
 allow direct move/renaming without copying the contents of the source (this) file.





Parameters:
destFile - the destination file that is considered being copied
Returns:
the hint int indicating whether the moveTo(AbstractFile) method should be used





mkfile
public void mkfile()
            throws java.io.IOException

Creates this file as an empty, non-directory file. This method will fail (throw an IOException)
 if this file already exists. Note that this method may not always yield a zero-byte file (see below).

 This generic implementation simply creates a zero-byte file. AbstractRWArchiveFile implementations
 may want to override this method so that it creates a valid archive with no entry. To illustrate, an empty Zip
 file with proper headers is 22-byte long.






Throws:
java.io.IOException - if the file could not be created, either because it already exists or because of an I/O error





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

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. isBrowsable() must return
 true.





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

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. 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.





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.





changePermissions
public boolean changePermissions(int permissions)

Changes this file's permissions to the specified permissions int and returns true if
 the operation was successful, false if at least one of the file permissions could not be changed.
 The permissions int should be constructed using the permission types and accesses defined in
 PermissionTypes and PermissionAccesses.

 Implementation note: the default implementation of this method calls sequentially changePermission(int, int, boolean),
 for each permission and access (that's a total 9 calls). This may affect performance on filesystems which need
 to perform an I/O request to change each permission individually. In that case, and if the fileystem allows
 to change all permissions at once, this method should be overridden.





Parameters:
permissions - new permissions for this file
Returns:
true if the operation was successful, false if at least one of the file permissions could not be changed





importPermissions
public void importPermissions(AbstractFile sourceFile)

This method is a shorthand for importPermissions(AbstractFile, FilePermissions) called with
 FilePermissions.DEFAULT_DIRECTORY_PERMISSIONS if this file is a directory or
 FilePermissions.DEFAULT_FILE_PERMISSIONS if this file is a regular file.





Parameters:
sourceFile - the file from which to import permissions





importPermissions
public void importPermissions(AbstractFile sourceFile,
                              FilePermissions defaultPermissions)

Imports the given source file's permissions, overwriting this file's permissions. Only the bits that are
 supported by the source file (as reported by the permissions' mask) are preserved. Other bits are be
 set to those of the specified default permissions.
 See SimpleFilePermissions.padPermissions(FilePermissions, FilePermissions) for more information about
 permissions padding.





Parameters:
sourceFile - the file from which to import permissions
defaultPermissions - default permissions to use
See Also:
SimpleFilePermissions.padPermissions(FilePermissions, FilePermissions)





getPermissionsString
public java.lang.String getPermissionsString()

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 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.
 
 






Returns:
a string representation of this file's permissions





deleteRecursively
public void deleteRecursively()
                       throws java.io.IOException

Deletes this file. If the file is a directory, enclosing files are deleted recursively.
 Symbolic links to directories are simply deleted, without deleting the contents of the linked directory.






Throws:
java.io.IOException - if an error occurred while deleting a file or listing a directory's contents





getNameWithoutExtension
public final java.lang.String getNameWithoutExtension()

Returns the name of the file without its 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

 If this file has no extension, its full name is returned.






Returns:
this file's name, without its extension.
See Also:
getName(), 
getExtension()





getAbsolutePath
public final java.lang.String getAbsolutePath(boolean appendSeparator)

Returns the absolute path to this file.
 A separator character will be appended to the returned path if true is passed.





Parameters:
appendSeparator - if true, a separator will be appended to the returned path
Returns:
the absolute path to this file





getCanonicalPath
public final java.lang.String getCanonicalPath(boolean appendSeparator)

Returns the canonical path to this file, resolving any symbolic links or '..' and '.' occurrences.
 A separator character will be appended to the returned path if true is passed.





Parameters:
appendSeparator - if true, a separator will be appended to the returned path
Returns:
the canonical path to this file





getChild
public final AbstractFile getChild(java.lang.String relativePath)
                            throws java.io.IOException

Returns a child of this file, whose path is the concatenation of this file's path and the given relative path.
 Although this method does not enforce it, the specified path should be relative, i.e. should not start with
 a separator.

 An IOException may be thrown if the child file could not be instanciated but the returned file
 instance should never be null.





Parameters:
relativePath - the child's path, relative to this file's path
Returns:
an AbstractFile representing the requested child file, never null
Throws:
java.io.IOException - if the child file could not be instanciated





getDirectChild
public final AbstractFile getDirectChild(java.lang.String filename)
                                  throws java.io.IOException

Returns a direct child of this file, whose path is the concatenation of this file's path and the given filename.
 An IOException will be thrown in any of the following cases:
 
  if the filename contains one or several path separator (the file would not be a direct child)
  if the child file could not be instanciated
 
 This method never returns <null.

 Although getChild(java.lang.String) can be used to retrieve a direct child file, this method should be favored because
 it allows to use this file instance as the parent of the returned child file.





Parameters:
filename - the name of the child file to be created
Returns:
an AbstractFile representing the requested direct child file, never null
Throws:
java.io.IOException - in any of the cases listed above





getParentSilently
public final AbstractFile getParentSilently()

Convience method that returns this file's parent, null if it doesn't have one or if it couldn't
 be instanciated. This method is less granular than getParent() but is convenient in cases where no
 distinction is made between having no parent and not being able to instanciate it.






Returns:
this file's parent, null if it doesn't have one or if it couldn't be instanciated





mkdir
public final void mkdir(java.lang.String name)
                 throws java.io.IOException

Convenience method that creates a directory as a direct child of this directory.
 This method will fail if this file is not a directory.





Parameters:
name - name of the directory to create
Throws:
java.io.IOException - if the directory could not be created, either because the file already exists or for any
 other reason.





mkdirs
public final void mkdirs()
                  throws java.io.IOException

Creates this file as a directory and any parent directory that does not already exist. This method will fail
 (throw an IOException) if this file already exists. It may also fail because of an I/O error ;
 in this case, this method will not remove the parent directories it has created (if any).






Throws:
java.io.IOException - if this file already exists or if an I/O error occurred.





mkfile
public final void mkfile(java.lang.String name)
                  throws java.io.IOException

Convenience method that creates a file as a direct child of this directory.
 This method will fail if this file is not a directory.





Parameters:
name - name of the file to create
Throws:
java.io.IOException - if the file could not be created, either because the file already exists or for any
 other reason.





getAncestor
public final AbstractFile getAncestor()

Returns the immediate ancestor of this AbstractFile if it has one, this otherwise:
 
  if this file is a ProxyFile, returns the return value of ProxyFile.getProxiedFile()
  
if this file is not a ProxyFile, returns this
 






Returns:
the immediate ancestor of this AbstractFile if it has one, this otherwise





getAncestor
public final AbstractFile getAncestor(java.lang.Class abstractFileClass)

Returns the first ancestor of this file that is an instance of the given Class or of a subclass of the given
 Class, or this if this instance's class matches those criteria. Returns null if this
 file has no such ancestor.
 Note that the specified must correspond to an AbstractFile subclass. Specifying any other Class will
 always yield to this method returning null. Also note that this method will always return
 this if AbstractFile.class is specified.





Parameters:
abstractFileClass - a Class corresponding to an AbstractFile subclass
Returns:
the first ancestor of this file that is an instance of the given Class or of a subclass of the given
 Class, or this if this instance's class matches those criteria. Returns null if this
 file has no such ancestor.





getTopAncestor
public final AbstractFile getTopAncestor()

Iterates through the ancestors returned by getAncestor() until the top-most ancestor is reached and
 returns it. If this file has no ancestor, this will be returned.






Returns:
returns the top-most ancestor of this file, this if this file has no ancestor





hasAncestor
public final boolean hasAncestor()

Returns true if this AbstractFile has an ancestor, i.e. if this file is a
 ProxyFile, false otherwise.






Returns:
true if this AbstractFile has an ancestor, false otherwise.





hasAncestor
public final boolean hasAncestor(java.lang.Class abstractFileClass)

Returns true if this file is or has an ancestor (immediate or not) that is an instance of the given
 Class or of a subclass of the Class. Note that the specified must correspond to an
 AbstractFile subclass. Specifying any other Class will always yield to this method returning
 false. Also note that this method will always return true if
 AbstractFile.class is specified.





Parameters:
abstractFileClass - a Class corresponding to an AbstractFile subclass
Returns:
true if this file has an ancestor (immediate or not) that is an instance of the given Class
 or of a subclass of the given Class.





isParentOf
public final boolean isParentOf(AbstractFile file)

Returns true if this file is a parent folder of the given file, or if the two files are equal.





Parameters:
file - the AbstractFile to test
Returns:
true if this file is a parent folder of the given file, or if the two files are equal





getParentArchive
public final AbstractArchiveFile getParentArchive()

Convenience method that returns the parent AbstractArchiveFile that contains this file. If this file
 is an AbstractArchiveFile or an ancestor of AbstractArchiveFile, this is returned. If this file
 is not contained by an archive or is not an archive, null is returned.






Returns:
the parent AbstractArchiveFile that contains this file





getIcon
public final javax.swing.Icon getIcon(java.awt.Dimension preferredResolution)

Returns an icon representing this file, using the default FileIconProvider
 registered in FileFactory. The specified preferred resolution will be used as a hint, but the returned
 icon may have different dimension; see FileIconProvider.getFileIcon(AbstractFile, java.awt.Dimension)
 for full details.
 This method may return null if the JVM is running on a headless environment.





Parameters:
preferredResolution - the preferred icon resolution
Returns:
an icon representing this file, null if the JVM is running on a headless environment
See Also:
FileFactory.getDefaultFileIconProvider(), 
FileIconProvider.getFileIcon(AbstractFile, java.awt.Dimension)





getIcon
public final javax.swing.Icon getIcon()

Returns an icon representing this file, using the default FileIconProvider
 registered in FileFactory. The default preferred resolution for the icon is 16x16 pixels.
 This method may return null if the JVM is running on a headless environment.






Returns:
an icon representing this file, null if the JVM is running on a headless environment
See Also:
FileFactory.getDefaultFileIconProvider(), 
FileIconProvider.getFileIcon(AbstractFile, java.awt.Dimension)





calculateChecksum
public final java.lang.String calculateChecksum(java.lang.String algorithm)
                                         throws java.io.IOException,
                                                java.security.NoSuchAlgorithmException

Returns a checksum of this file (also referred to as hash or digest) calculated by reading this
 file's contents and feeding the bytes to the given MessageDigest, until EOF is reached.

 The checksum is returned as an hexadecimal string, such as "6d75636f0a". The length of this string depends on
 the kind of algorithm.

 Note: this method does not reset the MessageDigest after the checksum has been calculated.





Parameters:
algorithm - the algorithm to use for calculating the checksum
Returns:
this file's checksum, as an hexadecimal string
Throws:
java.io.IOException - if an I/O error occurred while calculating the checksum
java.security.NoSuchAlgorithmException - if the specified algorithm does not correspond to any MessageDigest registered
 with the Java Cryptography Extension.





calculateChecksum
public final java.lang.String calculateChecksum(java.security.MessageDigest messageDigest)
                                         throws java.io.IOException

Returns a checksum of this file (also referred to as hash or digest) calculated by reading this
 file's contents and feeding the bytes to the given MessageDigest, until EOF is reached.

 The checksum is returned as an hexadecimal string, such as "6d75636f0a". The length of this string depends on
 the kind of MessageDigest.

 Note: this method does not reset the MessageDigest after the checksum has been calculated.





Parameters:
messageDigest - the MessageDigest to use for calculating the checksum
Returns:
this file's checksum, as an hexadecimal string
Throws:
java.io.IOException - if an I/O error occurred while calculating the checksum





addTrailingSeparator
protected final java.lang.String addTrailingSeparator(java.lang.String path)

Tests if the given path contains a trailing separator, and if not, adds one to the returned path.
 The separator used is the one returned by getSeparator().





Parameters:
path - the path for which to add a trailing separator
Returns:
the path with a trailing separator





removeTrailingSeparator
protected final java.lang.String removeTrailingSeparator(java.lang.String path)

Tests if the given path contains a trailing separator, and if it does, removes it from the returned path.
 The separator used is the one returned by getSeparator().





Parameters:
path - the path for which to remove the trailing separator
Returns:
the path free of a trailing separator





copyRecursively
protected final void copyRecursively(AbstractFile sourceFile,
                                     AbstractFile destFile)
                              throws FileTransferException

Copies the source file to the destination one and recurses on directory contents.
 This method assumes that the destination file does not exists, this must be checked prior to calling this method.
 Symbolic links are skipped when encountered: neither the link nor the linked file are copied.





Parameters:
sourceFile - the file to copy
destFile - the destination file
Throws:
FileTransferException - if an error occurred while copying the file





deleteRecursively
protected final void deleteRecursively(AbstractFile file)
                                throws java.io.IOException

Deletes the given file. If the file is a directory, enclosing files are deleted recursively.
 Symbolic links to directories are simply deleted, without deleting the contents of the linked directory.





Parameters:
file - the file to delete
Throws:
java.io.IOException - if an error occurred while deleting a file or listing a directory's contents





changePermissions
public final boolean changePermissions(FilePermissions permissions)

Convenience method that calls changePermissions(int) with the given permissions' int value.





Parameters:
permissions - new permissions for this file
Returns:
true if the operation was successful, false if at least one of the file permissions could not be changed





getExtension
public static java.lang.String getExtension(java.lang.String filename)

Returns the given filename's extension, null if the filename 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





Parameters:
filename - a filename, not a full path
Returns:
the given filename's extension, null if the filename doesn't have an extension





calculateChecksum
public static java.lang.String calculateChecksum(java.io.InputStream in,
                                                 java.security.MessageDigest messageDigest)
                                          throws java.io.IOException

Returns the checksum (also referred to as hash or digest) of the given InputStream
 calculated by reading the stream and feeding the bytes to the given MessageDigest until EOF is
 reached.

 Important: this method does not close the InputStream, and does n

com.mucommander.file Class AbstractFile

fileURL

DEFAULT_SEPARATOR

SHOULD_HINT

SHOULD_NOT_HINT

MUST_HINT

MUST_NOT_HINT

IO_BUFFER_SIZE

windowsDriveRootPattern

AbstractFile

getURL

getJavaNetURL

getName

getExtension

getAbsolutePath

getCanonicalPath

getCanonicalFile

getSeparator

isBrowsable

isHidden

getRoot

isRoot

getInputStream

copyStream

checkCopyPrerequisites

copyTo

getCopyToHint

moveTo

getMoveToHint

mkfile

ls

ls

changePermissions

importPermissions

importPermissions

getPermissionsString

deleteRecursively

getNameWithoutExtension

getAbsolutePath

getCanonicalPath

getChild

getDirectChild

getParentSilently

mkdir

mkdirs

mkfile

getAncestor

getAncestor

getTopAncestor

hasAncestor

hasAncestor

isParentOf

getParentArchive

getIcon

getIcon

calculateChecksum

calculateChecksum

addTrailingSeparator

removeTrailingSeparator

copyRecursively

deleteRecursively

changePermissions

getExtension

calculateChecksum

com.mucommander.file
Class AbstractFile