Class XFile
The XFile object is functionally equivalent to the java.io.File object with the ability to handle not only native pathnames but also URL-style pathnames. URL pathnames have some advantages over native pathnames:
- The name is platform-independent.
You can use the same name to reference a file independent of the pathname syntax supported by the underlying operating system. The component separator in a URL pathname is always a forward slash. - The name can be global in scope.
For instance, a URL name can refer to a file anywhere on the Internet, e.g.nfs://santa.northpole.org/toys/catalog
- The name can refer explicitly to an access scheme.
For example:file:///C|/java/bin
(a local directory)nfs://myserver/home/ed
(directory on NFS server)ftp://ftpsrv/pub/pkg.zip
(file on FTP server)
- Consistent rules for composition of relative names.
URLs support a well defined set of rules for the use of names relative to a "base" URL described in RFC 1808.
For instance:Base Relative Composition file:///a/b/c
x
file:///a/b/c/x
nfs://server/a/b/c
/y
nfs://server/y
nfs://server/a/b/c
../z
nfs://server/a/b/z
file:///a/b/c
d/.
nfs://server/a/b/c/d
file:///a/b/c
nfs://srv/x
nfs://srv/x
- Will support Universal Resource Names.
Although URLs are necessarily location dependent, location indepent Universal Resource Names (URN) names can be used within the same structure (see RFC 2141.
Pathnames that are not represented as URL names will be assumed to represent "native" names and XFile will present the same semantics as the java.io.File class.
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionboolean
canRead()
Tests if the application can read from the specified file.boolean
canWrite()
Tests if the application can write to this file.boolean
delete()
Deletes the file specified by this object.boolean
Compares this object against the specified object.boolean
exists()
Tests if thisXFile
exists.Returns the absolute pathname of the file represented by this object.Returns the canonical form of thisXFile
object's pathname.Get the XFileExtensionAccessorReturns the name of the filesystem, the string before the colon of the URL.getName()
Returns the name of the file represented by this object.Returns the parent part of the pathname of thisXFile
object, ornull
if the name has no parent part.getPath()
Returns the pathname of the file represented by this object.int
hashCode()
Computes a hashcode for the file.boolean
Tests if the file represented by thisXFile
object is an absolute pathname.boolean
Tests if the file represented by thisXFile
object is a directory.boolean
isFile()
Tests if the file represented by thisXFile
object is a "normal" file.long
Returns the time that the file represented by thisXFile
object was last modified.long
length()
Returns the length of the file represented by thisXFile
object.String[]
list()
Returns a list of the files in the directory specified by thisXFile
object.String[]
list
(XFilenameFilter filter) Returns a list of the files in the directory specified by thisXFile
that satisfy the specified filter.boolean
mkdir()
Creates a directory whose pathname is specified by thisXFile
object.boolean
mkdirs()
Creates a directory whose pathname is specified by thisXFile
object, including any necessary parent directories.protected XFileAccessor
boolean
Renames the file specified by thisXFile
object to have the pathname given by theXFile
argument.toString()
Returns a string representation of this object.
-
Constructor Details
-
XFile
Creates aXFile
instance that represents the file whose pathname is the given url argument. If the the name argument contains the string "://" then it is assumed to be a URL name. The characters prior to the colon are assumed to be the filesystem scheme name, e.g. "file", "nfs", etc. The rest of the URL name is assumed to be structured according to the Common Internet Scheme syntax described in RFC 1738; an optional location part followed by a hierarchical set of slash separated directories.<scheme>://<location>/<path>
- Parameters:
name
- the file url- Throws:
NullPointerException
- if the file url is equal tonull
.
-
XFile
Creates aXFile
instance that represents the file with the specified name in the specified directory. If thedir
XFile isnull
, or if thename
string is a full URL, then the single-arg constructor is used on thename
.If the
dir
XFile represents a native file and thename
stringisAbsolute
then the single-arg constructor is used on thename
. If thename
is not absolute then the resulting path is the simple concatenation of thedir
path with the file separator and thename
as for the two-arg constructor of theFile
class.If the
dir
XFile represents a URL name then thedir
is assumed to be a base URL and thename
string is evaluated as a relative URL according to the rules described in RFC 1808.Dir Name Composition file:///a/b/c
x
file:///a/b/c/x
nfs://server/a/b/c
/y
nfs://server/y
nfs://server/a/b/c
../z
nfs://server/a/b/z
file:///a/b/c
d/.
nfs://server/a/b/c/d
file:///a/b/c
nfs://srv/x
nfs://srv/x
C:\Data\Programs
myprog.exe
C:\Data\Programs\myprog.exe
- Parameters:
dir
- the directory.name
- absolute or relative file name or URL
-
-
Method Details
-
newAccessor
-
getExtensionAccessor
Get the XFileExtensionAccessor- Returns:
- instance of XFileExtensionAccessor or null if there is no XFileExtensionAccessor.
-
getFileSystemName
Returns the name of the filesystem, the string before the colon of the URL. If this XFile represents a native path then the "file" filesystem will be returned.- Returns:
- the name of the filesystem.
-
getName
Returns the name of the file represented by this object. The name is the last component of the pathname. For a URL this is the last, non-terminating slash. For a native file it is the portion of the pathname after the last occurrence of the separator character.- Returns:
- the name of the file (without any directory components)
represented by this
XFile
object.
-
getPath
Returns the pathname of the file represented by this object.- Returns:
- the pathname represented by this
XFile
object.If the object is a URL type, the path is the part of the URL following the location, e.g.
new XFile("nfs://location/a/b/c").getPath() == "a/b/c"
new XFile("file:///a/b/c").getPath() == "a/b/c"
new XFile("nfs://server/").getPath() == ""
-
getAbsolutePath
Returns the absolute pathname of the file represented by this object. If this object is represented by a native pathname and is an absolute pathname, then return the pathname. Otherwise, return a pathname that is a concatenation of the current user directory, the separator character, and the pathname of this file object. The system propertyuser.dir
contains the current user directory.If the object is represented by a URL then return the entire URL string.
- Returns:
- a system-dependent absolute pathname for this
XFile
.
-
getCanonicalPath
Returns the canonical form of thisXFile
object's pathname. If the object is represented by a URL name then the full URL is always returned. URL names are always canonical.For native paths the precise definition of canonical form is system-dependent, but it usually specifies an absolute pathname in which all relative references and references to the current user directory have been completely resolved. The canonical form of a pathname of a nonexistent file may not be defined.
- Returns:
- the canonical path of the object
- Throws:
IOException
- If an I/O error occurs, which is possible because the construction of the canonical path may require filesystem queries.
-
getParent
Returns the parent part of the pathname of thisXFile
object, ornull
if the name has no parent part. If the name is a URL then the parent part is the URL with the last component of the pathname removed. If the URL has no pathname part, then the URL is returned unchanged.For native paths the parent part is generally everything leading up to the last occurrence of the separator character, although the precise definition is system dependent. On UNIX, for example, the parent part of
"/usr/lib"
is"/usr"
whose parent part is"/"
, which in turn has no parent. On Windows platforms, the parent part of"c:\java"
is"c:\"
, which in turn has no parent.- Returns:
- the name of the parent directory
-
isAbsolute
public boolean isAbsolute()Tests if the file represented by thisXFile
object is an absolute pathname. If the object is represented by a URL thentrue
is always returned.
If theXFile
represents a native name then the definition of an absolute pathname is system dependent. For example, on UNIX, a pathname is absolute if its first character is the separator character. On Windows platforms, a pathname is absolute if its first character is an ASCII '\' or '/', or if it begins with a letter followed by a colon.- Returns:
true
if the pathname indicated by theXFile
object is an absolute pathname;false
otherwise.
-
exists
public boolean exists()Tests if thisXFile
exists.- Returns:
true
if the file specified by this object exists;false
otherwise.
-
canWrite
public boolean canWrite()Tests if the application can write to this file.- Returns:
true
if the application is allowed to write to a file whose name is specified by this object;false
otherwise.
-
canRead
public boolean canRead()Tests if the application can read from the specified file.- Returns:
true
if the file specified by this object exists and the application can read the file;false
otherwise.
-
isFile
public boolean isFile()Tests if the file represented by thisXFile
object 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.- Returns:
true
if the file specified by this object exists and is a "normal" file;false
otherwise.
-
isDirectory
public boolean isDirectory()Tests if the file represented by thisXFile
object is a directory.- Returns:
true
if thisXFile
exists and is a directory;false
otherwise.
-
lastModified
public long lastModified()Returns the time that the file represented by thisXFile
object was last modified.The return value is system dependent and should only be used to compare with other values returned by last modified. It should not be interpreted as an absolute time.
- Returns:
- the time the file specified by this object was last
modified, or
0L
if the specified file does not exist.
-
length
public long length()Returns the length of the file represented by thisXFile
object.- Returns:
- the length, in bytes, of the file specified by this
object, or
0L
if the specified file does not exist. The length constitutes the number of bytes readable via an InputStream. The length value for a directory is undefined.
-
renameTo
Renames the file specified by thisXFile
object to have the pathname given by theXFile
argument. This object anddest
must represent filesystems of the same type. For instance: both native or both of the same URL scheme. After a successful renameTo, this object continues to be a valid reference to the file. Only the name is different. If the destination filename already exists, it will be replaced. The application must have permission to modify the source and destination directory.- Parameters:
dest
- the new filename.- Returns:
true
if the renaming succeeds;false
otherwise.
-
mkdir
public boolean mkdir()Creates a directory whose pathname is specified by thisXFile
object. If any parent directories in the pathname do not exist, the method will return false.- Returns:
true
if the directory could be created;false
otherwise.
-
mkdirs
public boolean mkdirs()Creates a directory whose pathname is specified by thisXFile
object, including any necessary parent directories.- Returns:
true
if the directory (or directories) could be created;false
otherwise.
-
list
Returns a list of the files in the directory specified by thisXFile
object.- Returns:
- an array of file names in the specified directory.
This list does not include the current directory or the
parent directory ("
.
" and "..
" on Unix systems).
-
list
Returns a list of the files in the directory specified by thisXFile
that satisfy the specified filter.- Parameters:
filter
- a filename filter.- Returns:
- an array of file names in the specified directory.
This list does not include the current directory or the
parent directory ("
.
" and "..
" on Unix systems). - See Also:
-
com.sun.xfilenameFilter
-
delete
public boolean delete()Deletes the file specified by this object. If the target file to be deleted is a directory, it must be empty for deletion to succeed.- Returns:
true
if the file is successfully deleted;false
otherwise.
-
hashCode
public int hashCode()Computes a hashcode for the file. -
equals
Compares this object against the specified object. Returnstrue
if and only if the argument is notnull
and is aXFile
object whose pathname is equal to the pathname of this object. -
toString
Returns a string representation of this object.
-