WebLogic Server 5.1.0 API Reference

weblogic.io.common
Interface T3File

public interface T3File

Interface that defines a T3File. T3Files are produced by WebLogic File Systems, and as such may represent local files on the client or remote files on the server. This makes it easy to write code that treats the two uniformly.

In addition to methods that mirror those of java.io.File, T3File has methods to produce T3FileInputStreams and T3FileOutputStreams. All of these methods behave the same for local and remote files except for the following. First, there is no notion of the "current user directory" on a remote file system, so all file names are absolute. Second, the bufferSize, readAhead, and writeBehind arguments to the methods for producing streams are ignored in the local case.

Here's an example of how this interface is used in the process of deleting a remote file:

   T3Client t3 = new T3Client("t3://host:port");

   // Get file system and file.
   T3FileSystem myfs = t3.services.io().getFileSystem("myFileSystem");
   T3File myFile = myfs.getFile("someDirectory/someFile"); 

   // Use java.io.File-style methods to delete the file
   myFile.delete();
 

Author:

Copyright (c) 1996-1998 by WebLogic, Inc. All Rights Reserved., Copyright (c) 1998-1999 by BEA Systems, Inc. All Rights Reserved.
Copyright © 2000 BEA Systems, Inc. All Rights Reserved.

See Also:

T3FileSystem, T3FileInputStream, T3FileOutputStream

Method Summary

boolean	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	equals(java.lang.Object obj) Compares this object against the specified object.
boolean	exists() Tests if this T3File exists.
T3File	extend(java.lang.String suffix) Returns a new T3File defined by this file's path extended by a suffix.
java.lang.String	getAbsolutePath() Returns the absolute pathname of the file represented by this object.
java.lang.String	getCanonicalPath() Returns the canonical form of this T3File object's pathname.
T3FileInputStream	getFileInputStream() Gets a new T3FileInputStream object for reading from the file.
T3FileInputStream	getFileInputStream(int bufferSize, int readAhead) Gets a new T3FileInputStream object for reading from the file.
T3FileOutputStream	getFileOutputStream() Gets a new T3FileOutputStream object for writing to the file.
T3FileOutputStream	getFileOutputStream(int bufferSize, int writeBehind) Gets a new T3FileOutputStream object for writing to the file.
java.lang.String	getName() Returns the name of the file represented by this object.
java.lang.String	getParent() Returns the parent part of the pathname of this T3File object, or null if the name has no parent part.
java.lang.String	getPath() Returns the pathname of the file represented by this object.
int	hashCode() Computes a hashcode for the file.
boolean	isAbsolute() Tests if the file represented by this T3File object is an absolute pathname.
boolean	isDirectory() Tests if the file represented by this T3File object is a directory.
boolean	isFile() Tests if the file represented by this T3File object is a "normal" file.
long	lastModified() Returns the time that the file represented by this T3File object was last modified.
long	length() Returns the length of the file represented by this T3File object.
java.lang.String[]	list() Returns a list of the files in the directory specified by this T3File object.
java.lang.String[]	list(java.io.FilenameFilter filter) Returns a list of the files in the directory specified by this T3File that satisfy the specified filter.
boolean	mkdir() Creates a directory whose pathname is specified by this T3File object.
boolean	mkdirs() Creates a directory whose pathname is specified by this T3File object, including any necessary parent directories.
boolean	renameTo(T3File dest) Renames the file specified by this T3File object to have the pathname given by the T3File argument.
java.lang.String	toString() Returns a string representation of this object.

Method Detail

getFileInputStream

public T3FileInputStream getFileInputStream()
                                     throws T3Exception

Gets a new T3FileInputStream object for reading from the file. If it is remote, uses the default bufferSize and readAhead.

Returns:

the T3FileInputStream

Throws:

T3Exception - if there is an error creating the stream

getFileInputStream

public T3FileInputStream getFileInputStream(int bufferSize,
                                            int readAhead)
                                     throws T3Exception

Gets a new T3FileInputStream object for reading from the file. If it is remote, uses the specified bufferSize and readAhead. The size of the buffer is in bytes, and readAhead refers to the number of buffers fetched in advance of the user's request.

Parameters:

bufferSize - Size of transfer buffers in bytes

readAhead - Number of transfer buffers fetched in advance

Returns:

the T3FileInputStream

Throws:

T3Exception - if there is an error

getFileOutputStream

public T3FileOutputStream getFileOutputStream()
                                       throws T3Exception

Gets a new T3FileOutputStream object for writing to the file. If it is remote, uses the default bufferSize and writeBehind.

Returns:

the T3FileOutputStream

Throws:

T3Exception - if there is an error

getFileOutputStream

public T3FileOutputStream getFileOutputStream(int bufferSize,
                                              int writeBehind)
                                       throws T3Exception

Gets a new T3FileOutputStream object for writing to the file. If it is remote, uses the specified bufferSize and writeBehind. The size of the buffer is in bytes, and writeBehind refers to the number of unwritten buffers that can be outstanding before the next write blocks.

Parameters:

bufferSize - Size of transfer buffers in bytes

writeBehind - Number of unwritten transfer buffers

Returns:

the T3FileOutputStream

Throws:

T3Exception - if there is an error

extend

public T3File extend(java.lang.String suffix)

Returns a new T3File defined by this file's path extended by a suffix.

Parameters:

suffix - the path suffix

Returns:

the T3File with extended path

getName

public java.lang.String getName()

Returns the name of the file represented by this object. The name is everything in the pathame after the last occurrence of the separator character.

Returns:

the name of the file (without any directory components) represented by this T3File object

See Also:

getPath()

getPath

public java.lang.String getPath()

Returns the pathname of the file represented by this object.

Returns:

the pathname represented by this T3File object

getAbsolutePath

public java.lang.String getAbsolutePath()

Returns the absolute pathname of the file represented by this object. If this object represents 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. Remote file systems do not have a current user directory, so remote file names are always absolute.

The system property user.dir contains the current user directory.

Returns:

a system-dependent absolute pathname for this T3File

See Also:

getPath(), isAbsolute()

getCanonicalPath

public java.lang.String getCanonicalPath()
                                  throws java.io.IOException

Returns the canonical form of this T3File object's pathname. 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.

Throws:

java.io.IOException - if an I/O error occurs, which is possible because the construction of the canonical path may require file system queries

getParent

public java.lang.String getParent()

Returns the parent part of the pathname of this T3File object, or null if the name has no parent part. 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.

See Also:

getPath(), getCanonicalPath()

exists

public boolean exists()
               throws java.lang.SecurityException

Tests if this T3File exists.

Returns:

true if the file specified by this object exists; false otherwise

Throws:

java.lang.SecurityException - if a security manager exists, its checkRead method is called with the pathname of this T3File to see if the application is allowed read access to the file

See Also:

getPath(), SecurityManager.checkRead(java.lang.String)

canWrite

public boolean canWrite()
                 throws java.lang.SecurityException

Tests if the application can write to this file.

Returns:

true if the application is allowed to write to the file specified by this object; false otherwise

Throws:

java.lang.SecurityException - if a security manager exists, its checkWrite method is called with the pathname of this T3File to see if the application is allowed write access to the file

See Also:

getPath(), SecurityManager.checkWrite(java.lang.String)

canRead

public boolean canRead()
                throws java.lang.SecurityException

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

Throws:

java.lang.SecurityException - if a security manager exists, its checkRead method is called with the pathname of this T3File to see if the application is allowed read access to the file

See Also:

getPath(), SecurityManager.checkRead(java.lang.String)

isFile

public boolean isFile()
               throws java.lang.SecurityException

Tests if the file represented by this T3File 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

Throws:

java.lang.SecurityException - if a security manager exists, its checkRead method is called with the pathname of this T3File to see if the application is allowed read access to the file

See Also:

getPath(), SecurityManager.checkRead(java.lang.String)

isDirectory

public boolean isDirectory()
                    throws java.lang.SecurityException

Tests if the file represented by this T3File object is a directory.

Returns:

true if this T3File exists and is a directory; false otherwise

Throws:

java.lang.SecurityException - if a security manager exists, its checkRead method is called with the pathname of this T3File to see if the application is allowed read access to the file

See Also:

getPath(), SecurityManager.checkRead(java.lang.String)

isAbsolute

public boolean isAbsolute()

Tests if the file represented by this T3File object is an absolute pathname. 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. Remote file systems do not have a current user directory, so remote file names are always absolute.

Returns:

true if the pathname indicated by the T3File object is an absolute pathname; false otherwise

See Also:

getPath()

lastModified

public long lastModified()
                  throws java.lang.SecurityException

Returns the time that the file represented by this T3File 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

Throws:

java.lang.SecurityException - if a security manager exists, its checkRead method is called with the pathname of this T3File to see if the application is allowed read access to the file

See Also:

getPath(), SecurityManager.checkRead(java.lang.String)

length

public long length()
            throws java.lang.SecurityException

Returns the length of the file represented by this T3File object.

Returns:

the length, in bytes, of the file specified by this object, or 0L if the specified file does not exist

Throws:

java.lang.SecurityException - if a security manager exists, its checkRead method is called with the pathname of this T3File to see if the application is allowed read access to the file

See Also:

getPath(), SecurityManager.checkRead(java.lang.String)

mkdir

public boolean mkdir()
              throws java.lang.SecurityException

Creates a directory whose pathname is specified by this T3File object.

Returns:

true if the directory could be created; false otherwise

Throws:

java.lang.SecurityException - if a security manager exists, its checkWrite method is called with the pathname of this T3File to see if the application is allowed write access to the file

See Also:

getPath(), SecurityManager.checkWrite(java.lang.String)

renameTo

public boolean renameTo(T3File dest)
                 throws java.lang.SecurityException

Renames the file specified by this T3File object to have the pathname given by the T3File argument. The renaming fails if the two files are not on the same file system.

Parameters:

dest - the new filename

Returns:

true if the renaming succeeds; false otherwise

Throws:

java.lang.SecurityException - if a security manager exists, its checkWrite method is called both with the pathname of this file object and with the pathname of the destination target object to see if the application is allowed to write to both files

See Also:

getPath(), SecurityManager.checkWrite(java.lang.String)

mkdirs

public boolean mkdirs()
               throws java.lang.SecurityException

Creates a directory whose pathname is specified by this T3File object, including any necessary parent directories.

Returns:

true if the directory (or directories) could be created; false otherwise

Throws:

java.lang.SecurityException - if a security manager exists, its checkWrite method is called with the pathname of each of the directories that is to be created, before any of the directories are created

See Also:

getPath(), SecurityManager.checkWrite(java.lang.String)

list

public java.lang.String[] list()
                        throws java.lang.SecurityException

Returns a list of the files in the directory specified by this T3File 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)

Throws:

java.lang.SecurityException - if a security manager exists, its checkRead method is called with the pathname of this T3File to see if the application is allowed read access to the file

See Also:

getPath(), SecurityManager.checkRead(java.lang.String)

list

public java.lang.String[] list(java.io.FilenameFilter filter)
                        throws java.lang.SecurityException

Returns a list of the files in the directory specified by this T3File that satisfy the specified filter. If the file system is remote, the filename filter must be serializable.

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)

Throws:

java.lang.SecurityException - if a security manager exists, its checkRead method is called with the pathname of this T3File to see if the application is allowed read access to the file

See Also:

getPath(), FilenameFilter, SecurityManager.checkRead(java.lang.String)

delete

public boolean delete()
               throws java.lang.SecurityException

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

Throws:

java.lang.SecurityException - if a security manager exists, its checkDelete method is called with the pathname of this T3File to see if the application is allowed to delete the file

See Also:

getPath(), SecurityManager.checkDelete(java.lang.String)

hashCode

public int hashCode()

Computes a hashcode for the file.

Returns:

a hash code value for this T3File object

Overrides:

hashCode in class java.lang.Object

equals

public boolean equals(java.lang.Object obj)

Compares this object against the specified object. Returns true if and only if the argument:

1. is a non-null T3File object;
2. is on the same file system as this object; and
3. has pathname equal to the pathname of this object.

Parameters:

obj - the object to compare with

Returns:

true if the objects are the same; false otherwise

Overrides:

equals in class java.lang.Object

toString

public java.lang.String toString()

Returns a string representation of this object.

Returns:

a string giving the pathname of this object

Overrides:

toString in class java.lang.Object

See Also:

getPath()