org.openafs.jafs
Class File

java.lang.Object
  |
  +--java.io.File
        |
        +--org.openafs.jafs.File

All Implemented Interfaces:

Comparable, Serializable

public class File

extends File

implements Comparable

An abstract representation of AFS file and directory pathnames. This class is an extension of the standard Java File class with file-based manipulation methods overridden by integrated AFS native methods.

Extension methods include:

1. isMountPoint()
2. isLink()
3. isValidated()
4. validate()
5. refresh()
6. getErrorCode()
7. getErrorMessage()

For performance optimization, all newly constructed File objects are only validated once. Furthermore, if an abstract pathname denotes a symbolic-link, then the isLink() attribute is set to true and the getTarget() field member is populated with this symbolic-link's target resource. (see getTarget())

If you are interested in validating the target resource, simply call validate() before calling any of the attribute accessors. This action will stat the target resource, identifying its associated attributes and populating them in this objects field members.

Following is an example of how to construct a new AFS File Object:

     try {
         File file = new File("/afs/mycell.com/proj/");
         if (file.isDirectory()) {
           System.out.println("This is a directory.");
         } else if (file.isLink()) {
           System.out.println("This is a symbolic-link.");
           System.out.println("  Its target is: " + file.getTarget());
           file.validate();
           if (file.isFile()) {
             System.out.println("  This object is now a file!");
           } else if (file.isDirectory()) {
             System.out.println("  This object is now a directory!");
           } else if (file.isMountPoint()) {
             System.out.println("  This object is now a volume mount point!");
           }
         } else if (file.isMountPoint()) {
           System.out.println("This is a volume mount point.");
         } else if (file.isFile()) {
           System.out.println("This is file.");
           System.out.println("  its size is: " + file.length());
         }
     } catch (AFSFileException ae) {
         System.out.println("AFS Exception: " + ae.getMessage());
         System.out.println("AFS Error Code: " + ae.getErrorCode());
     } catch (Exception e) {
         System.out.println("Exception: " + e.getMessage());
         e.printStackTrace();
     }
 

Version:

2.0, 04/16/2001 - Completely revised class for efficiency., 1.3, 10/12/2000 - Introduced error code capture from native methods., 1.2, 05/30/2000

See Also:

Serialized Form

Field Summary

Fields inherited from class java.io.File

pathSeparator, pathSeparatorChar, separator, separatorChar

Constructor Summary

File(File parent, String filename)
Creates a new File instance from a parent abstract pathname and a child pathname string and validates it against the file system.

File(File parent, String filename, boolean validate)
Creates a new File instance from a parent abstract pathname and a child pathname string.

File(String pathname)
Creates a new File instance by converting the given pathname string into an abstract pathname and validating it against the file system.

File(String pathname, boolean validate)
Creates a new File instance by converting the given pathname string into an abstract pathname.

File(String parent, String filename)
Creates a new File instance from a parent pathname string and a child pathname string and validates it against the file system.

File(String parent, String filename, boolean validate)
Creates a new File instance from a parent pathname string and a child pathname string.

Method Summary

boolean	canAdmin() Tests whether the user can administer the ACL (see: ACL of the directory denoted by this abstract pathname.
boolean	canDelete() Tests whether the current user can delete the files or subdirectories of the directory denoted by this abstract pathname.
boolean	canInsert() Tests whether the current user can insert a file into the directory denoted by this abstract pathname.
boolean	canLock() Tests whether the current user can lock the file denoted by this abstract pathname.
boolean	canLookup() Tests whether the current user can lookup the contents of the directory denoted by this abstract pathname.
boolean	canRead() Tests whether the current user can read the file denoted by this abstract pathname.
boolean	canWrite() Tests whether the current user can modify to the file denoted by this abstract pathname.
boolean	close() Closes the directory denoted by this abstract pathname.
int	compareTo(File file) Compares two File objects relative to their filenames and does not compare their respective absolute paths.
int	compareTo(Object o) Compares this file to another File object.
boolean	copyTo(File dest) Copies the file denoted by this abstract pathname to the destination file provided.
boolean	delete() Deletes the file or directory denoted by this abstract pathname.
boolean	exists() Tests whether the file denoted by this abstract pathname exists.
int	getErrorCode() Returns the AFS specific error number (code).
String	getErrorMessage() Returns the AFS error message string defined by the ErrorTable class.
int	getPermissionsMask() Returns the permissions mask of the ACL for this object relative to the user accessing it.
String	getTarget() Returns an abstract pathname string that represents the target resource of of this file, if it is a symbolic-link.
boolean	isDirectory() Tests whether the file denoted by this abstract pathname is a directory.
boolean	isFile() Tests whether the file denoted by this abstract pathname is a normal file.
boolean	isLink() Tests whether the file denoted by this abstract pathname is a symbolic-link.
boolean	isMountPoint() Tests whether the file denoted by this abstract pathname is an AFS Volume Mount Point.
boolean	isValidated() Tests whether the file denoted by this abstract pathname has been validated.
long	lastModified() Returns the time that the file denoted by this abstract pathname was last modified.
long	length() Returns the length of the file denoted by this abstract pathname.
String[]	list() Returns an array of strings naming the files and directories in the directory denoted by this abstract pathname.
ArrayList	listArray() Returns an ArrayList object containing strings naming the files and directories in the directory denoted by this abstract pathname.
boolean	mkdir() Creates the directory named by this abstract pathname.
void	refresh() Refreshes this AFS file object by updating its attributes.
boolean	renameTo(File dest) Renames the file denoted by this abstract pathname.
boolean	setAttributes() Performs a file stat on the actual AFS file and populates this object's respective field members with the appropriate values.
void	validate() Validates this abstract pathname as an attributed AFS file object.

Methods inherited from class java.io.File

compareTo, createNewFile, createTempFile, createTempFile, deleteOnExit, equals, getAbsoluteFile, getAbsolutePath, getCanonicalFile, getCanonicalPath, getName, getParent, getParentFile, getPath, hashCode, isAbsolute, isHidden, list, listFiles, listFiles, listFiles, listRoots, mkdirs, renameTo, setLastModified, setReadOnly, toString, toURI, toURL

Methods inherited from class java.lang.Object

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

Constructor Detail

File

public File(String pathname)
     throws AFSFileException

Creates a new File instance by converting the given pathname string into an abstract pathname and validating it against the file system. If the given string is an empty string, then the result is the empty abstract pathname; otherwise the abstract pathname is validated to represent a qualified file object.

Parameters:

pathname - A pathname string

Throws:

NullPointerException - If the pathname argument is null

AFSFileException - If the user constructing this AFS file object is denied access to stat the file or simply a stat cannot be performed on the file. The reason code and message will be available from AFSFileException.getErrorCode() and AFSFileException.getMessage() respectively.

This exception will not be thrown if the file does not exist. Rather, the exists() attribute will be set to false.

See Also:

validate()

File

public File(String pathname,
            boolean validate)

Creates a new File instance by converting the given pathname string into an abstract pathname. If the given string is an empty string, then the result is the empty abstract pathname.

The abstract pathname will remain abstract unless the validate parameter is set to true. This means that the abstract pathname will not be validated and therefore the file object will not represent a qualified, attributed, AFS file resource. Rather, this constructor provides a method by which you can construct a non-validated File object (one that does not contain the file's complete status information).

This constructor is useful for creating file objects of file/path names that you know exist, however are unauthorized to validate (or stat - to obtain complete status information). For example, if you are permitted to lookup (see: canLookup()) the contents of a given directory yet not permitted to read (see: canRead()), then this constructor would enable you to render the contents of the directory without validating each entry.

Please note: this is the only constructor that does not throw an AFSFileException.

Parameters:

pathname - A pathname string

validate - A boolean flag to indicate if this abstract path should be validated.

Throws:

NullPointerException - If the pathname argument is null

See Also:

File(String), validate()

File

public File(String parent,
            String filename)
     throws AFSFileException

Creates a new File instance from a parent pathname string and a child pathname string and validates it against the file system.

If parent is null then the new File instance is created as if by invoking the single-argument File constructor on the given filename string (child pathname).

Otherwise the parent pathname string is taken to denote a directory, and the filename string is taken to denote either a directory or a file. The directory or file will then be validated to represent a qualified file object.

Parameters:

parent - The parent pathname string

filename - This file's pathname string (child of specified parent)

Throws:

NullPointerException - If child is null

AFSFileException - If the user constructing this AFS file object is denied access to stat the file or simply a stat cannot be performed on the file. The reason code and message will be available from AFSFileException.getErrorCode() and AFSFileException.getMessage() respectively.

This exception will not be thrown if the file does not exist. Rather, the exists() attribute will be set to false.

See Also:

validate()

File

public File(String parent,
            String filename,
            boolean validate)
     throws AFSFileException

Creates a new File instance from a parent pathname string and a child pathname string.

If parent is null then the new File instance is created as if by invoking the single-argument File constructor on the given filename string (child pathname).

Otherwise the parent pathname string is taken to denote a directory, and the filename string is taken to denote either a directory or a file.

The abstract pathname will remain abstract unless the validate parameter is set to true. This means that the abstract pathname will not be validated and therefore the file object will not represent a qualified, attributed, AFS file resource. Rather, this constructor provides a method by which you can construct a non-validated File object (one that does not contain the file's complete status information).

This constructor is useful for creating file objects of file/path names that you know exist, however are unauthorized to validate (or stat - to obtain complete status information). For example, if you are permitted to lookup (see: canLookup()) the contents of a given directory yet not permitted to read (see: canRead()), then this constructor would enable you to render the contents of the directory without validating each entry.

Parameters:

parent - The parent pathname string

filename - This file's pathname string (child of specified parent)

validate - A boolean flag to indicate if this abstract path should be validated.

Throws:

NullPointerException - If child is null

AFSFileException - If the user constructing this AFS file object is denied access to stat the file or simply a stat cannot be performed on the file. The reason code and message will be available from AFSFileException.getErrorCode() and AFSFileException.getMessage() respectively.

This exception will not be thrown if the file does not exist. Rather, the exists() attribute will be set to false.

See Also:

File(String, String), validate()

File

public File(File parent,
            String filename)
     throws AFSFileException

Creates a new File instance from a parent abstract pathname and a child pathname string and validates it against the file system.

If parent is null then the new File instance is created as if by invoking the single-argument File constructor on the given filename string (child pathname).

Otherwise the parent abstract pathname is taken to denote a directory, and the filename string is taken to denote either a directory or a file. The directory or file will then be validated to represent a qualified file object.

Parameters:

parent - The parent abstract pathname

filename - This file's pathname string (child of specified parent)

Throws:

NullPointerException - If child is null

AFSFileException - If the user constructing this AFS file object is denied access to stat the file or simply a stat cannot be performed on the file. The reason code and message will be available from AFSFileException.getErrorCode() and AFSFileException.getMessage() respectively.

This exception will not be thrown if the file does not exist. Rather, the exists() attribute will be set to false.

See Also:

validate()

File

public File(File parent,
            String filename,
            boolean validate)
     throws AFSFileException

Creates a new File instance from a parent abstract pathname and a child pathname string.

If parent is null then the new File instance is created as if by invoking the single-argument File constructor on the given filename string (child pathname).

Otherwise the parent abstract pathname is taken to denote a directory, and the filename string is taken to denote either a directory or a file.

The abstract pathname will remain abstract unless the validate parameter is set to true. This means that the abstract pathname will not be validated and therefore the file object will not represent a qualified, attributed, AFS file resource. Rather, this constructor provides a method by which you can construct a non-validated File object (one that does not contain the file's complete status information).

This constructor is useful for creating file objects of file/path names that you know exist, however are unauthorized to validate (or stat - to obtain complete status information). For example, if you are permitted to lookup (see: canLookup()) the contents of a given directory yet not permitted to read (see: canRead()), then this constructor would enable you to render the contents of the directory without validating each entry.

Parameters:

parent - The parent abstract pathname

filename - This file's pathname string (child of specified parent)

validate - A boolean flag to indicate if this abstract path should be validated.

Throws:

NullPointerException - If child is null

AFSFileException - If the user constructing this AFS file object is denied access to stat the file or simply a stat cannot be performed on the file. The reason code and message will be available from AFSFileException.getErrorCode() and AFSFileException.getMessage() respectively.

This exception will not be thrown if the file does not exist. Rather, the exists() attribute will be set to false.

See Also:

validate(), File(File, String)

Method Detail

validate

public void validate()
              throws AFSSecurityException

Validates this abstract pathname as an attributed AFS file object. This method will, if authorized, perform a stat on the actual AFS file and update its respective field members; defining this file object's attributes.

Throws:

AFSSecurityException - If an AFS exception occurs while attempting to stat and set this AFS file object's attributes.

isValidated

public boolean isValidated()

Tests whether the file denoted by this abstract pathname has been validated.

Validation is always attempted upon construction of the file object, therefore if this method returns false, then you are not permitted to validate this file and consequently all attribute accessors will be invalid.

This method should return true even if this abstract pathname does not exist. If this is abstract pathname does not exist then the exists() method should return false, however this implies that the attribute accessors are valid and accurate; thus implying successful validation.

This method is useful before calling any of the attribute accessors to ensure a valid response.

Returns:

true if and only if the file denoted by this abstract pathname has been validated during or after object construction; false otherwise

refresh

public void refresh()
             throws AFSSecurityException

Refreshes this AFS file object by updating its attributes. This method currently provides the same functionality as validate().

Throws:

AFSSecurityException - If an AFS exception occurs while attempting to stat and update this AFS file object's attributes.

See Also:

validate()

isDirectory

public boolean isDirectory()

Tests whether the file denoted by this abstract pathname is a directory.

Overrides:

isDirectory in class File

Returns:

true if and only if the file denoted by this abstract pathname exists and is a directory; false otherwise

isFile

public boolean isFile()

Tests whether the file denoted by this abstract pathname is a normal file. A file is normal if it is not a directory and, in addition, satisfies other system-dependent criteria. Any non-directory file created by a Java application is guaranteed to be a normal file.

Overrides:

isFile in class File

Returns:

true if and only if the file denoted by this abstract pathname exists and is a normal file; false otherwise

isMountPoint

public boolean isMountPoint()

Tests whether the file denoted by this abstract pathname is an AFS Volume Mount Point.

Returns:

true if and only if the file denoted by this abstract pathname exists and is a mount point; false otherwise

isLink

public boolean isLink()

Tests whether the file denoted by this abstract pathname is a symbolic-link.

Returns:

true if and only if the file denoted by this abstract pathname exists and is a symbolic-link; false otherwise

exists

public boolean exists()

Tests whether the file denoted by this abstract pathname exists.

Overrides:

exists in class File

Returns:

true if and only if the file denoted by this abstract pathname exists; false otherwise

lastModified

public long lastModified()

Returns the time that the file denoted by this abstract pathname was last modified.

Overrides:

lastModified in class File

Returns:

A long value representing the time the file was last modified, measured in milliseconds since the epoch (00:00:00 GMT, January 1, 1970), or 0L if the file does not exist or if an I/O error occurs

length

public long length()

Returns the length of the file denoted by this abstract pathname.

Overrides:

length in class File

Returns:

The length, in bytes, of the file denoted by this abstract pathname, or 0L if the file does not exist

getTarget

public String getTarget()

Returns an abstract pathname string that represents the target resource of of this file, if it is a symbolic-link.

If this abstract pathname does not denote a symbolic-link, then this method returns null. Otherwise a string is returned that represents the target resource of this symbolic-link.

Returns:

A string representation of this symbolic-link's target resource.

See Also:

isLink()

list

public String[] list()

Returns an array of strings naming the files and directories in the directory denoted by this abstract pathname.

If this abstract pathname does not denote a directory, then this method returns null. Otherwise an array of strings is returned, one for each file or directory in the directory. Names denoting the directory itself and the directory's parent directory are not included in the result. Each string is a file name rather than a complete path.

There is no guarantee that the name strings in the resulting array will appear in any specific order; they are not, in particular, guaranteed to appear in alphabetical order.

Overrides:

list in class File

Returns:

An array of strings naming the files and directories in the directory denoted by this abstract pathname. The array will be empty if the directory is empty. Returns null if this abstract pathname does not denote a directory, or if an I/O error occurs.

listArray

public ArrayList listArray()
                    throws AFSFileException

Returns an ArrayList object containing strings naming the files and directories in the directory denoted by this abstract pathname.

If this abstract pathname does not denote a directory, then this method returns null. Otherwise an array of strings is returned, one for each file or directory in the directory. Names denoting the directory itself and the directory's parent directory are not included in the result. Each string is a file name rather than a complete path.

There is no guarantee that the name strings in the resulting array will appear in any specific order; they are not, in particular, guaranteed to appear in alphabetical order.

Returns:

An array of strings naming the files and directories in the directory denoted by this abstract pathname. The array will be empty if the directory is empty. Returns null if this abstract pathname does not denote a directory, or if an I/O error occurs.

Throws:

AFSSecurityException - If you are not authorized to list the contents of this directory

AFSFileException - If this file object is not a mount point, link , or directory or an unexpected AFS error occurs.

See Also:

list()

delete

public boolean delete()

Deletes the file or directory denoted by this abstract pathname. If this pathname denotes a directory, then the directory must be empty in order to be deleted.

Overrides:

delete in class File

Returns:

true if and only if the file or directory is successfully deleted; false otherwise

copyTo

public boolean copyTo(File dest)
               throws AFSFileException

Copies the file denoted by this abstract pathname to the destination file provided. Then checks the newly copied file's size to test for file size consistency.

Parameters:

dest - The new abstract pathname for the named file

Returns:

true if and only if the file that was copied reports the same file size (length) as that of this file; false otherwise

Throws:

AFSFileException - If an I/O or AFS exception is encountered while copying the file.

getPermissionsMask

public int getPermissionsMask()

Returns the permissions mask of the ACL for this object relative to the user accessing it.

Returns:

the permissions mask of this object based upon the current user.

See Also:

ACL.Entry.getPermissionsMask()

canAdmin

public boolean canAdmin()

Tests whether the user can administer the ACL (see: ACL of the directory denoted by this abstract pathname.

Returns:

true if and only if the directory specified by this abstract pathname exists and can be administered by the current user; false otherwise

See Also:

ACL.Entry.canAdmin()

canDelete

public boolean canDelete()

Tests whether the current user can delete the files or subdirectories of the directory denoted by this abstract pathname.

Returns:

true if and only if the directory specified by this abstract pathname exists and permits deletion of its files and subdirectories by the current user; false otherwise

See Also:

ACL.Entry.canDelete()

canInsert

public boolean canInsert()

Tests whether the current user can insert a file into the directory denoted by this abstract pathname.

Returns:

true if and only if the directory specified by this abstract pathname exists and a file can be inserted by the current user; false otherwise

See Also:

ACL.Entry.canInsert()

canLock

public boolean canLock()

Tests whether the current user can lock the file denoted by this abstract pathname.

Returns:

true if and only if the file specified by this abstract pathname exists and can be locked by the current user; false otherwise

See Also:

ACL.Entry.canLock()

canLookup

public boolean canLookup()

Tests whether the current user can lookup the contents of the directory denoted by this abstract pathname.

Returns:

true if and only if the directory specified by this abstract pathname exists and its contents can be listed by the current user; false otherwise

See Also:

ACL.Entry.canLookup()

canRead

public boolean canRead()

Tests whether the current user can read the file denoted by this abstract pathname.

Overrides:

canRead in class File

Returns:

true if and only if the file specified by this abstract pathname exists and can be read by the current user; false otherwise

See Also:

ACL.Entry.canRead()

canWrite

public boolean canWrite()

Tests whether the current user can modify to the file denoted by this abstract pathname.

Overrides:

canWrite in class File

Returns:

true if and only if the file system actually contains a file denoted by this abstract pathname and the current user is allowed to write to the file; false otherwise.

See Also:

ACL.Entry.canWrite()

close

public boolean close()

Closes the directory denoted by this abstract pathname.

Returns:

true if and only if the directory is successfully closed; false otherwise

getErrorCode

public int getErrorCode()

Returns the AFS specific error number (code). This code can be interpreted by use of ErrorTable static class method ErrorTable.getMessage(int)

Returns:

the AFS error code (number) associated with the last action performed on this object.

See Also:

ErrorTable.getMessage(int)

getErrorMessage

public String getErrorMessage()

Returns the AFS error message string defined by the ErrorTable class.

Returns:

the AFS error message string associated with the last action performed on this object.

See Also:

ErrorTable.getMessage(int)

compareTo

public int compareTo(File file)

Compares two File objects relative to their filenames and does not compare their respective absolute paths. Alphabetic case is significant in comparing filenames.

Parameters:

file - The File object to be compared to this file's filename

Returns:

Zero if the argument is equal to this file's filename, a value less than zero if this file's filename is lexicographically less than the argument, or a value greater than zero if this file's filename is lexicographically greater than the argument

Since:

JDK1.2

compareTo

public int compareTo(Object o)
              throws ClassCastException

Compares this file to another File object. If the other object is an abstract pathname, then this function behaves like compareTo(File). Otherwise, it throws a ClassCastException, since File objects can only be compared to File objects.

Specified by:

compareTo in interface Comparable

Overrides:

compareTo in class File

Parameters:

o - The Object to be compared to this abstract pathname

Returns:

If the argument is an File object, returns zero if the argument is equal to this file's filename, a value less than zero if this file's filename is lexicographically less than the argument, or a value greater than zero if this file's filename is lexicographically greater than the argument

Throws:

ClassCastException - if the argument is not an File object

ClassCastException

Since:

JDK1.2

See Also:

Comparable

mkdir

public boolean mkdir()

Creates the directory named by this abstract pathname.

Overrides:

mkdir in class File

Returns:

true if and only if the directory was created; false otherwise

renameTo

public boolean renameTo(File dest)

Renames the file denoted by this abstract pathname.

Parameters:

dest - The new abstract pathname for the named file

Returns:

true if and only if the renaming succeeded; false otherwise

Throws:

NullPointerException - If parameter dest is null

setAttributes

public boolean setAttributes()
                      throws AFSSecurityException

Performs a file stat on the actual AFS file and populates this object's respective field members with the appropriate values. method will, if authorized, perform a stat on the actual AFS file and update its respective field members; defining this file object's attributes.

This method should not be used directly for refreshing or validating this AFS file object. Please use validate() instead.

Returns:

true if and only if the current user is allowed to stat the file; false otherwise.

AFSSecurityException

See Also:

validate()