|
JAFS API v2 | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--java.io.File | +--org.openafs.jafs.File
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:
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(); }
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
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 |
public File(String pathname) throws AFSFileException
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.
pathname
- A pathname string
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
.
validate()
public File(String pathname, boolean validate)
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.
pathname
- A pathname stringvalidate
- A boolean flag to indicate if this abstract path
should be validated.
NullPointerException
- If the pathname
argument is null
File(String)
,
validate()
public File(String parent, String filename) throws AFSFileException
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.
parent
- The parent pathname stringfilename
- This file's pathname string (child of specified parent)
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
.
validate()
public File(String parent, String filename, boolean validate) throws AFSFileException
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.
parent
- The parent pathname stringfilename
- This file's pathname string (child of specified parent)validate
- A boolean flag to indicate if this abstract path
should be validated.
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
.
File(String, String)
,
validate()
public File(File parent, String filename) throws AFSFileException
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.
parent
- The parent abstract pathnamefilename
- This file's pathname string (child of specified parent)
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
.
validate()
public File(File parent, String filename, boolean validate) throws AFSFileException
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.
parent
- The parent abstract pathnamefilename
- This file's pathname string (child of specified parent)validate
- A boolean flag to indicate if this abstract path
should be validated.
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
.
validate()
,
File(File, String)
Method Detail |
public void validate() throws AFSSecurityException
stat
on the
actual AFS file and update its respective field members; defining
this file object's attributes.
AFSSecurityException
- If an AFS exception occurs while attempting to stat and set this
AFS file object's attributes.public boolean isValidated()
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
method should return false, however this
implies that the attribute accessors are valid and accurate; thus implying
successful validation.
exists()
This method is useful before calling any of the attribute accessors to ensure a valid response.
true
if and only if the file denoted by this
abstract pathname has been validated during or after object construction;
false
otherwisepublic void refresh() throws AFSSecurityException
validate()
.
AFSSecurityException
- If an AFS exception occurs while attempting to stat and update this
AFS file object's attributes.validate()
public boolean isDirectory()
isDirectory
in class File
true
if and only if the file denoted by this
abstract pathname exists and is a directory;
false
otherwisepublic boolean isFile()
isFile
in class File
true
if and only if the file denoted by this
abstract pathname exists and is a normal file;
false
otherwisepublic boolean isMountPoint()
true
if and only if the file denoted by this
abstract pathname exists and is a mount point;
false
otherwisepublic boolean isLink()
true
if and only if the file denoted by this
abstract pathname exists and is a symbolic-link;
false
otherwisepublic boolean exists()
exists
in class File
true
if and only if the file denoted by this
abstract pathname exists; false
otherwisepublic long lastModified()
lastModified
in class File
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 occurspublic long length()
length
in class File
0L
if the file does not existpublic String getTarget()
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.
isLink()
public String[] list()
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.
list
in class File
null
if
this abstract pathname does not denote a directory, or if an
I/O error occurs.public ArrayList listArray() throws AFSFileException
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.
null
if
this abstract pathname does not denote a directory, or if an
I/O error occurs.
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.list()
public boolean delete()
delete
in class File
true
if and only if the file or directory is
successfully deleted; false
otherwisepublic boolean copyTo(File dest) throws AFSFileException
dest
- The new abstract pathname for the named file
true
if and only if the file that was copied
reports the same file size (length) as that of this file;
false
otherwise
AFSFileException
- If an I/O or AFS exception is encountered while copying the file.public int getPermissionsMask()
ACL.Entry.getPermissionsMask()
public boolean canAdmin()
ACL
of the directory denoted by this abstract pathname.
true
if and only if the directory specified by this
abstract pathname exists and can be administered by the
current user; false
otherwiseACL.Entry.canAdmin()
public boolean canDelete()
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
otherwiseACL.Entry.canDelete()
public boolean canInsert()
true
if and only if the directory specified by this
abstract pathname exists and a file can be inserted by the
current user; false
otherwiseACL.Entry.canInsert()
public boolean canLock()
true
if and only if the file specified by this
abstract pathname exists and can be locked by the
current user; false
otherwiseACL.Entry.canLock()
public boolean canLookup()
true
if and only if the directory specified by this
abstract pathname exists and its contents can be listed by the
current user; false
otherwiseACL.Entry.canLookup()
public boolean canRead()
canRead
in class File
true
if and only if the file specified by this
abstract pathname exists and can be read by the
current user; false
otherwiseACL.Entry.canRead()
public boolean canWrite()
canWrite
in class File
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.ACL.Entry.canWrite()
public boolean close()
true
if and only if the directory is
successfully closed; false
otherwisepublic int getErrorCode()
ErrorTable
static class method
ErrorTable.getMessage(int)
ErrorTable.getMessage(int)
public String getErrorMessage()
ErrorTable
class.
ErrorTable.getMessage(int)
public int compareTo(File file)
file
- The File object to be compared to this file's filename
public int compareTo(Object o) throws ClassCastException
compareTo(File)
. Otherwise, it throws a
ClassCastException
, since File objects can only be
compared to File objects.
compareTo
in interface Comparable
compareTo
in class File
o
- The Object
to be compared to this abstract pathname
ClassCastException
- if the argument is not an
File object
ClassCastException
Comparable
public boolean mkdir()
mkdir
in class File
true
if and only if the directory was
created; false
otherwisepublic boolean renameTo(File dest)
dest
- The new abstract pathname for the named file
true
if and only if the renaming succeeded;
false
otherwise
NullPointerException
- If parameter dest
is null
public boolean setAttributes() throws AFSSecurityException
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.
true
if and only if the current user is allowed to stat the file;
false
otherwise.
AFSSecurityException
validate()
|
JAFS API v2 | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |