com.mucommander.bookmark.file
Class BookmarkFile

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

All Implemented Interfaces:

PermissionAccesses, PermissionTypes

public class BookmarkFile
extends AbstractFile

Represents a file in the bookmark:// file system.

Author:

Nicolas Rinaudo

Field Summary

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

BookmarkFile(Bookmark bookmark)
Creates a new bookmark file wrapping the specified bookmark.

Method Summary

boolean	canChangeDate() Returns true if this file's date can be changed using AbstractFile.changeDate(long).
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.
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.
boolean	canRunProcess() Returns true if the wrapped file knows how to create processes.
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.
boolean	changePermission(int access, int permission, boolean enabled) Returns false.
boolean	copyTo(AbstractFile destination) Tries to copy the bookmark to the specified destination.
void	delete() Deletes the bookmark.
boolean	equals(java.lang.Object o) Tests a file for equality: returns true if the given file has the same canonical path, as returned by AbstractFile.getCanonicalPath().
boolean	exists() Returns true if the specified bookmark exists.
Bookmark	getBookmark() Returns the underlying bookmark.
java.lang.String	getCanonicalPath() Returns the canonical path to this file, resolving any symbolic links or '..' and '.' occurrences.
PermissionBits	getChangeablePermissions() Returns a bit mask describing the permission bits that can be changed on this file when calling AbstractFile.changePermission(int, int, boolean) and AbstractFile.changePermissions(int).
int	getCopyToHint(AbstractFile destination) Returns a hint that indicates whether the AbstractFile.copyTo(AbstractFile) method should be used to copy this file to the specified destination file, rather than copying the file 'manually', using AbstractFile.copyStream(InputStream, boolean), or AbstractFile.getInputStream() and AbstractFile.getOutputStream(boolean).
long	getDate() Returns this file's last modified date, in milliseconds since the epoch (00:00:00 GMT, January 1, 1970).
long	getFreeSpace() Returns the result of the wrapped file's getFreeSpace() methods.
java.lang.String	getGroup() Returns information about the group this file belongs to.
java.io.InputStream	getInputStream() Returns an InputStream to read the contents of this file.
int	getMoveToHint(AbstractFile destination) Returns AbstractFile.MUST_HINT.
java.lang.String	getName() Returns the underlying bookmark's name.
java.io.OutputStream	getOutputStream(boolean append) Returns an OuputStream to write the contents of this file, appending or overwriting the existing contents.
java.lang.String	getOwner() Returns information about the owner of this file.
AbstractFile	getParent() Returns the wrapped file's parent.
FilePermissions	getPermissions() Returns the same permissions for all boookmark files: rw- (600 octal).
RandomAccessInputStream	getRandomAccessInputStream() Returns a RandomAccessInputStream to read the contents of this file with random access.
RandomAccessOutputStream	getRandomAccessOutputStream() Returns a RandomAccessOutputStream to write the contents of this file with random access.
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 result of the wrapped file's getTotalSpace() methods.
java.lang.Object	getUnderlyingFileObject() Returns the file Object of the underlying API providing access to the filesystem.
boolean	hasRandomAccessInputStream() Returns true if the underlying filesystem has support for random access input streams.
boolean	hasRandomAccessOutputStream() Returns true if the underlying filesystem has support for random access output streams.
boolean	isBrowsable() Returns true.
boolean	isDirectory() Returns false.
boolean	isSymlink() Returns true if this file is a symbolic link.
AbstractFile[]	ls() Returns the wrapped file's descendants.
void	mkdir() Creates this file as a directory.
void	mkfile() Creates this file as an empty, non-directory file.
boolean	moveTo(AbstractFile destination) Tries to move the bookmark to the specified destination.
AbstractProcess	runProcess(java.lang.String[] tokens) Runs the specified command on the wrapped file.
void	setParent(AbstractFile parent) Sets the wrapped file's parent.

Methods inherited from class com.mucommander.file.AbstractFile

addTrailingSeparator, calculateChecksum, calculateChecksum, calculateChecksum, changePermissions, changePermissions, checkCopyPrerequisites, copyRecursively, copyStream, deleteRecursively, deleteRecursively, getAbsolutePath, getAbsolutePath, getAncestor, getAncestor, getCanonicalFile, getCanonicalPath, getChild, getDirectChild, getExtension, getExtension, getIcon, getIcon, getInputStream, getJavaNetURL, getNameWithoutExtension, getParentArchive, getParentSilently, getPermissionsString, getRoot, getSeparator, getTopAncestor, getURL, hasAncestor, hasAncestor, hashCode, importPermissions, importPermissions, isHidden, isParentOf, isRoot, ls, ls, mkdir, mkdirs, mkfile, removeTrailingSeparator, toString

Methods inherited from class java.lang.Object

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

Constructor Detail

BookmarkFile

public BookmarkFile(Bookmark bookmark)
             throws java.io.IOException

Creates a new bookmark file wrapping the specified bookmark.

Parameters:

bookmark - bookmark to wrap.

Throws:

java.io.IOException - if the specified bookmark's URL cannot be resolved.

Method Detail

getBookmark

public Bookmark getBookmark()

Returns the underlying bookmark.

Returns:

the underlying bookmark.

getName

public java.lang.String getName()

Returns the underlying bookmark's name.

Overrides:

getName in class AbstractFile

Returns:

the underlying bookmark's name.

ls

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

Returns the wrapped file's descendants.

Specified by:

ls in class AbstractFile

Returns:

the wrapped file's descendants.

Throws:

java.io.IOException - if an I/O error occurs.

getParent

public AbstractFile getParent()
                       throws java.io.IOException

Returns the wrapped file's parent.

Specified by:

getParent in class AbstractFile

Returns:

the wrapped file's parent.

Throws:

java.io.IOException - if an IO error occurs.

See Also:

setParent(AbstractFile)

canRunProcess

public boolean canRunProcess()

Returns true if the wrapped file knows how to create processes.

Specified by:

canRunProcess in class AbstractFile

Returns:

true if the wrapped file knows how to create processes.

runProcess

public AbstractProcess runProcess(java.lang.String[] tokens)
                           throws java.io.IOException

Runs the specified command on the wrapped file.

Specified by:

runProcess in class AbstractFile

Parameters:

tokens - command to run.

Returns:

a process running the specified command.

Throws:

java.io.IOException - if an IO error occurs.

getFreeSpace

public long getFreeSpace()

Returns the result of the wrapped file's getFreeSpace() methods.

Specified by:

getFreeSpace in class AbstractFile

Returns:

the result of the wrapped file's getFreeSpace() methods.

getTotalSpace

public long getTotalSpace()

Returns the result of the wrapped file's getTotalSpace() methods.

Specified by:

getTotalSpace in class AbstractFile

Returns:

the result of the wrapped file's getTotalSpace() methods.

isDirectory

public boolean isDirectory()

Returns false.

Specified by:

isDirectory in class AbstractFile

Returns:

false.

isBrowsable

public boolean isBrowsable()

Returns true.

Overrides:

isBrowsable in class AbstractFile

Returns:

true.

setParent

public void setParent(AbstractFile parent)

Sets the wrapped file's parent.

Specified by:

setParent in class AbstractFile

Parameters:

parent - object to use as the wrapped file's parent.

See Also:

getParent()

exists

public boolean exists()

Returns true if the specified bookmark exists.

A bookmark is said to exist if and only if it is known to the BookmarkManager.

Specified by:

exists in class AbstractFile

Returns:

true if the specified bookmark exists, false otherwise.

mkfile

public void mkfile()

Description copied from class: AbstractFile

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.

Overrides:

mkfile in class AbstractFile

equals

public boolean equals(java.lang.Object o)

Description copied from class: AbstractFile

Tests a file for equality: returns true if the given file has the same canonical path, as returned by AbstractFile.getCanonicalPath().

It is noteworthy that this method uses java.lang.String#equals(Object) to compare paths, which in some rare cases may return false for non-ascii/Unicode paths that have the same written representation but are not equal according to java.lang.String#equals(Object). Handling such cases would require a locale-aware String comparison which is not an option here.

This method should be overriden for network-based filesystems for which a host can have multiple path representations (hostname and IP address).

Overrides:

equals in class AbstractFile

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 AbstractFile

Returns:

the canonical path to this file

getMoveToHint

public int getMoveToHint(AbstractFile destination)

Returns AbstractFile.MUST_HINT.

If the specified file is a BookmarkFile, then we must use the custom moveTo method. Otherwise, the point is moot as any other move operation will fail.

Overrides:

getMoveToHint in class AbstractFile

Parameters:

destination - where the file will be moved to.

Returns:

AbstractFile.MUST_HINT.

moveTo

public boolean moveTo(AbstractFile destination)
               throws FileTransferException

Tries to move the bookmark to the specified destination.

If the specified destination is an instance of BookmarkFile, this will rename the bookmark. Otherwise, this method will fail.

Overrides:

moveTo in class AbstractFile

Parameters:

destination - where to move the bookmark to.

Returns:

true.

Throws:

FileTransferException - if the specified destination is not an instance of BookmarkFile.

delete

public void delete()

Deletes the bookmark.

Deleting a bookmark means unregistering it from the BookmarkManager.

Specified by:

delete in class AbstractFile

getCopyToHint

public int getCopyToHint(AbstractFile destination)

Description copied from class: AbstractFile

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

Potential returned values are:

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

This default implementation returns AbstractFile.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().

Overrides:

getCopyToHint in class AbstractFile

Parameters:

destination - the destination file that is considered being copied

Returns:

the hint int indicating whether the AbstractFile.copyTo(AbstractFile) method should be used

copyTo

public boolean copyTo(AbstractFile destination)
               throws FileTransferException

Tries to copy the bookmark to the specified destination.

If the specified destination is an instance of BookmarkFile, this will duplicate the bookmark. Otherwise, this method will fail.

Overrides:

copyTo in class AbstractFile

Parameters:

destination - where to copy the bookmark to.

Returns:

true.

Throws:

FileTransferException - if the specified destination is not an instance of BookmarkFile.

getPermissions

public FilePermissions getPermissions()

Returns the same permissions for all boookmark files: rw- (600 octal). Only the 'user' permissions bits are supported.

Specified by:

getPermissions in class AbstractFile

Returns:

this file's permissions.

See Also:

changePermission(int,int,boolean)

changePermission

public boolean changePermission(int access,
                                int permission,
                                boolean enabled)

Returns false.

Bookmarks always have all permissions, this is not changeable. Calls to this method will always be ignored.

Specified by:

changePermission in class AbstractFile

Parameters:

access - ignored.

permission - ignored.

enabled - ignored.

Returns:

false.

See Also:

getPermissions()

getInputStream

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

Description copied from class: AbstractFile

Returns an InputStream to read the contents of this file. Throws an IOException in any of the following cases:

• this file does not exist
• this file is a directory
• this file cannot be read
• a RandomAccessInputStream cannot be provided because the underlying file protocol doesn't have random access support (see AbstractFile.hasRandomAccessInputStream()
• an I/O error occurs

This method may never return null.

Specified by:

getInputStream in class AbstractFile

Returns:

an InputStream to read the contents of this file

Throws:

java.io.IOException - in any of the cases listed above

getOutputStream

public java.io.OutputStream getOutputStream(boolean append)
                                     throws java.io.IOException

Description copied from class: AbstractFile

Returns an OuputStream to write the contents of this file, appending or overwriting the existing contents. This file will be created as a zero-byte file if it does not yet exist. Throws an IOException in any of the following cases:

• this file is a directory
• this file cannot be written
• append is specified but not supported
• an I/O error occurs

This method may never return null.

Specified by:

getOutputStream in class AbstractFile

Parameters:

append - if true, data written to the OutputStream will be appended to the end of this file. If false, any existing data this file contains will be discarded and overwritten.

Returns:

an OuputStream to write the contents of this file

Throws:

java.io.IOException - in any of the cases listed above

mkdir

public void mkdir()
           throws java.io.IOException

Description copied from class: AbstractFile

Creates this file as a directory. This method will fail (throw an IOException) if this file already exists.

Specified by:

mkdir in class AbstractFile

Throws:

java.io.IOException - if the directory could not be created, either because this file already exists or for any other reason.

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

Specified by:

getDate in class AbstractFile

Returns:

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

canChangeDate

public boolean canChangeDate()

Description copied from class: AbstractFile

Returns true if this file's date can be changed using AbstractFile.changeDate(long). It's important to note that a true return value doesn't mean that a call to AbstractFile.changeDate(long) will necessarily succeed ; it could fail because of unsufficient permissions or simply because of a low-level I/O ; but it should at least ensure that AbstractFile.changeDate(long) is implemented and has a chance of succeeding.

Specified by:

canChangeDate in class AbstractFile

Returns:

true if this file's date can be changed using AbstractFile.changeDate(long)

getChangeablePermissions

public PermissionBits getChangeablePermissions()

Description copied from class: AbstractFile

Returns a bit mask describing the permission bits that can be changed on this file when calling AbstractFile.changePermission(int, int, boolean) and AbstractFile.changePermissions(int).

Specified by:

getChangeablePermissions in class AbstractFile

Returns:

a bit mask describing the permission bits that can be changed on this file

changeDate

public boolean changeDate(long lastModified)

Description copied from class: AbstractFile

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.

Specified by:

changeDate in class AbstractFile

Parameters:

lastModified - last modified date, in milliseconds since the epoch (00:00:00 GMT, January 1, 1970)

Returns:

true if date was changed successfully.

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.

Specified by:

getSize in class AbstractFile

Returns:

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

hasRandomAccessInputStream

public boolean hasRandomAccessInputStream()

Description copied from class: AbstractFile

Returns true if the underlying filesystem has support for random access input streams. Note that of true is returned, this doesn't necessarily mean that AbstractFile.getRandomAccessInputStream() will return a RandomAccessInputStream, it might still throw an IOException if random access to the file cannot be provided.

Specified by:

hasRandomAccessInputStream in class AbstractFile

Returns:

true if the underlying filesystem has support for random access input streams

getRandomAccessInputStream

public RandomAccessInputStream getRandomAccessInputStream()
                                                   throws java.io.IOException

Description copied from class: AbstractFile

Returns a RandomAccessInputStream to read the contents of this file with random access. Throws an IOException in any of the following cases:

• this file does not exist
• this file is a directory
• this file cannot be read
• a RandomAccessInputStream cannot be provided because the underlying file protocol doesn't have random access support (see AbstractFile.hasRandomAccessInputStream()
• an I/O error occurs

This method may never return null.

Specified by:

getRandomAccessInputStream in class AbstractFile

Returns:

a RandomAccessInputStream to read the contents of this file with random access

Throws:

java.io.IOException - in any of the cases listed above

hasRandomAccessOutputStream

public boolean hasRandomAccessOutputStream()

Description copied from class: AbstractFile

Returns true if the underlying filesystem has support for random access output streams. Note that of true is returned, this doesn't necessarily mean that AbstractFile.getRandomAccessOutputStream() will return a RandomAccessOutputStream, it might still throw an IOException if random access to the file cannot be provided.

Specified by:

hasRandomAccessOutputStream in class AbstractFile

Returns:

true if the underlying filesystem has support for random access output streams

getRandomAccessOutputStream

public RandomAccessOutputStream getRandomAccessOutputStream()
                                                     throws java.io.IOException

Description copied from class: AbstractFile

Returns a RandomAccessOutputStream to write the contents of this file with random access. This file will be created as a zero-byte file if it does not yet exist. Throws an IOException in any of the following cases:

• this file is a directory
• this file cannot be written
• a RandomAccessOutputStream cannot be provided because the underlying file protocol doesn't have random access support (see AbstractFile.hasRandomAccessOutputStream()
• an I/O error occurs

This method may never return null.

Specified by:

getRandomAccessOutputStream in class AbstractFile

Returns:

a RandomAccessOutputStream to write the contents of this file with random access

Throws:

java.io.IOException - in any of the cases listed above

getUnderlyingFileObject

public java.lang.Object getUnderlyingFileObject()

Description copied from class: AbstractFile

Returns the file Object of the underlying API providing access to the filesystem. The returned Object may expose filesystem-specific functionalities that are not available in AbstractFile. Note however that the returned Object type may change over time, if the underlying API used to provide access to the filesystem changes, so this method should be used only as a last resort.

If the implemented filesystem has no such Object, null is returned.

Specified by:

getUnderlyingFileObject in class AbstractFile

Returns:

the file Object of the underlying API providing access to the filesystem, null if there is none

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.

Specified by:

isSymlink in class AbstractFile

Returns:

true if this file is a symbolic link

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.

Specified by:

getOwner in class AbstractFile

Returns:

information about the owner of this file

canGetOwner

public boolean canGetOwner()

Description copied from class: AbstractFile

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. In other words, a true return value doesn't mean that AbstractFile.getOwner() will necessarily return a non-null value, but rather that there is a chance that it does.

Specified by:

canGetOwner in class AbstractFile

Returns:

true if this file implementation is able to return information about file owners

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.

Specified by:

getGroup in class AbstractFile

Returns:

information about the owner of this file

canGetGroup

public boolean canGetGroup()

Description copied from class: AbstractFile

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. In other words, a true return value doesn't mean that AbstractFile.getGroup() will necessarily return a non-null value, but rather that there is a chance that it does.

Specified by:

canGetGroup in class AbstractFile

Returns:

true if this file implementation is able to return information about file groups