com.novell.zos.dataGrid
Interface GridFile

public interface GridFile

General Data Grid interface for individual files or directories.

This interface rather closely mirrors java.io.File. It does not, however, extend that class, since the standard Java I/O classes would not understand the semantics of this extended version. In particular, path names specified by this class refer to remote files that may not be directly accessible via the file system, as expected by standard Java file I/O classes.

The mirroring of java.io.File is done strictly for consistency and familiarity. There are a few methods in java.io.File that don't make sense in the context of the data grid, and have thus been omitted. However, the commonly used methods such as canWrite, mkdir(), and so on are implemented and provide functionality for data grid paths that is analogous to that provided by java.io.File for local file system paths.

Nested Class Summary

static class

GridFile.CancelException Exception thrown by cancelled requests.

Method Summary

void	append(String data) Append the string data to the end of the grid file referenced by this path.
void	cancel() Cancel the currently running command.
boolean	canRead() Return true if this object represents a readable file or directory.
boolean	canWrite() Return true if this object represents a writeable file or directory.
boolean	copyTo(GridFile dest) Copy a file or directory from one path to another.
boolean	createNewFile() Create a new empty file.
boolean	delete() Delete the file or directory referenced by this path.
boolean	exists() Return true if this object represents an existing file or directory.
void	flushCache() Delete any localy cached copy of the file referenced by this object.
void	follow(OutputStream out, OutputStream err, String watchJob, long maxUnchanged, long offset, long count, long interval, long refresh, long timeout, boolean lineMode, boolean retryMode, boolean quietMode, boolean nameMode, boolean countLines) Output and/or follow the contents of a grid file in real time.
void	get(File localFile) Fetch the Data Grid file or directory to the local system.
GridFile	getCanonicalFile() Return the unique absolute normalized path name for this object.
String	getCanonicalPath() Return the unique absolute normalized path name for this object.
String	getChecksum() Return the checksum of the referenced file.
String	getErrorMessage() Return the the error message for the last method call on this object.
String	getLinkName() Return the last component of the logical path returned by getLinkPath.
String	getLinkPath() Return the logical path for this file before traversing the final link.
String	getLinkTarget() Return the link target if the current file is a link.
String	getName() Return the string name of the path represented by this object.
String	getParent() Return the "parent directory" name for this object's path.
GridFile	getParentFile() Return the "parent directory" object for this object's path.
String	getPath() Return the string name of the path represented by this object.
boolean	isCached() Return true if the file referenced by this object is cached locally.
boolean	isDirectory() Return true if this object represents a directory.
boolean	isFile() Return true if this object represents a regular file.
boolean	isLink() Return true if this file object refers to a link.
long	lastModified() Return the time of last modification for the file or directory referenced by this object.
long	length() Return the length of the file referenced by this object.
String[]	list() List the files in a directory.
String[]	list(GridFileNameFilter filter) List the files in a directory with a filter.
GridFile[]	listFiles() List files and subdirectories under the current directory.
GridFile[]	listFiles(GridFileFilter filter) List files and subdirectories under the current directory using a filter.
GridFile[]	listFiles(GridFileNameFilter filter) List files and subdirectories under the current directory using a filter.
boolean	mkdir() Create a new empty directory.
boolean	mkdirs() Recursively create a new empty directory.
void	multicast(File localFile, DGLogger mclogger, String nodeId, long mcMin, long mcQuorum, long mcWait, long mcRate, boolean fallBack, boolean fallBackOnError) Attempt to fetch the specified file as part of a combined multicast transfer.
void	put(File localFile) Store the specified local file or directory under the grid path referenced by this object.
void	query() Force an immediate query on the data grid.
boolean	renameTo(GridFile dest) Move a file or directory from one path to another.
void	setCaching(boolean caching) Enable or disable caching.

Method Detail

getErrorMessage

String getErrorMessage()

Return the the error message for the last method call on this object.

If there was no error, then the empty string (length zero) is returned. This method never returns null

Returns:

The error message for the last message call, or an empty string if there was no error.

query

void query()
           throws DataGridException

Force an immediate query on the data grid.

Queries the data grid for the file, path, or directory represented by this GridFile object and caches the information for later use. This method may be called in cases where it is desirable to detect the data grid being down, since methods such as exist() follow the java.io.File convention of not throwing exceptions.

Throws:

DataGridNotAvailableException - Thrown if the data grid cannot be reached due to a network error.

DataGridException - Thrown if other errors prevent access to the data grid.

getName

String getName()

Return the string name of the path represented by this object.

Returns the last component of the canonical grid name fo this object.

Returns:

The string name of the path represented by this object.

getPath

String getPath()

Return the string name of the path represented by this object.

Returns:

The string name of the path represented by this object.

getParent

String getParent()

Return the "parent directory" name for this object's path.

If at the top level, null is returned to indicate that this path is at the top "root" level.

Returns:

The "parent directory" name.

getParentFile

GridFile getParentFile()

Return the "parent directory" object for this object's path.

If at the top level, null is returned to indicate that this path is at the top "root" level.

Returns:

The "parent directory" object.

getCanonicalPath

String getCanonicalPath()
                        throws IOException

Return the unique absolute normalized path name for this object.

All components of the path are normalized to a consistent form, and the path is converted to its fully qualified absolute path. The canonical path for a given data grid file will always be the same string.

Returns:

The normalized path as a string name.

Throws:

IOException - Thrown if a system or I/O error prevents determination of the normalized path.

getCanonicalFile

GridFile getCanonicalFile()
                          throws IOException

Return the unique absolute normalized path name for this object.

All components of the path are normalized to a consistent form, and the path is converted to its fully qualified absolute path. The canonical path for a given data grid file will always be the same string.

Returns:

The normalized path as a string name.

Throws:

IOException - Thrown if a system or I/O error prevents determination of the normalized path.

isLink

boolean isLink()

Return true if this file object refers to a link.

This method only returns true if the final component of the original path used to query this file was a link.

Returns:

true if the final component of getPath() refers to a link.

getLinkName

String getLinkName()
                   throws IOException

Return the last component of the logical path returned by getLinkPath.

This method only returns a non-null value if the final component of the original path used to query this file was a link.

Returns:

The name of the link to the current file if the last component in the path is a link.

Throws:

IOException - If an I/O error prevents a lookup of the link information.

getLinkPath

String getLinkPath()
                   throws IOException

Return the logical path for this file before traversing the final link.

This method only returns a non-null value if the final component of the original path used to query this file was a link.

Returns:

The path without traversing the final link component.

Throws:

IOException - If an I/O error prevents a lookup of the link information.

getLinkTarget

String getLinkTarget()
                     throws IOException

Return the link target if the current file is a link.

Returns the contents of the link. The returned string is a logical path relative to the results from getLinkPath(). If the current file is not a link, then null is returned.

Returns:

The link target.

Throws:

IOException - If an I/O error prevents a lookup of the link information.

canRead

boolean canRead()

Return true if this object represents a readable file or directory.

Returns:

true if the referenced file/directory is readable.

canWrite

boolean canWrite()

Return true if this object represents a writeable file or directory.

Returns:

true if the referenced file/directory is writeable.

exists

boolean exists()

Return true if this object represents an existing file or directory.

Returns:

true if the referenced file/directory exists.

isDirectory

boolean isDirectory()

Return true if this object represents a directory.

Returns:

true if this grid path represents a directory.

isFile

boolean isFile()

Return true if this object represents a regular file.

Returns:

true if this grid path represents a regular file.

lastModified

long lastModified()

Return the time of last modification for the file or directory referenced by this object.

If the object does not exist, then 0L is returned.

Returns:

The time of last modification as the number of milliseconds Since Jan.1,1970 00:00:00.

length

long length()

Return the length of the file referenced by this object.

If the referenced object does not exist, or is not a file, then 0L is returned.

Returns:

The length of the referenced file.

getChecksum

String getChecksum()

Return the checksum of the referenced file.

If this object does not refer to an existing, readable file, then null is returned.

Returns:

The checksum, in hex string form, of the referenced file.

isCached

boolean isCached()

Return true if the file referenced by this object is cached locally.

If this object does not reference a file, then false is returned.

Returns:

true if the file is cached locally.

setCaching

void setCaching(boolean caching)

Enable or disable caching.

Parameters:

caching - If true, then the client will attempt to cache local copies of files.

flushCache

void flushCache()

Delete any localy cached copy of the file referenced by this object.

Used to force a fresh update of the file from the server. If the referenced object is a directory then all locally cached copies of any file at this directory or below are deleted.

createNewFile

boolean createNewFile()
                      throws IOException

Create a new empty file.

If this object refers to a path for which getParent() refers to a directory, and which does not currently exist, then a new empty file is created on the data grid.

Returns:

true if a new file was successfully created.

Throws:

IOException

delete

boolean delete()

Delete the file or directory referenced by this path.

If this path references a file, then the file is removed from the grid. If a directory is referenced, then the directory is recursively deleted.

Returns:

true if a the file or directory was successfully deleted.

list

String[] list()

List the files in a directory.

If the current object refers to a directory, then the files and directories immediately contained by it are returned as an array of string path component names, relative to the directory referenced by this object.

Note that the returned names are relative to their parent directory. To get a list of absolute names, use listFiles(), or simply append '/' and each name to the current object's path.

If the current object does not refer to a directory, then null is returned.

Returns:

The list of files or subdirectories immediately underneath the the directory referenced by this object.

list

String[] list(GridFileNameFilter filter)

List the files in a directory with a filter.

If the current object refers to a directory, then the files and directories immediately contained by it are returned as an array of string path component names, relative to the directory referenced by this object.

Note that the returned names are relative to their parent directory. To get a list of absolute names, use listFiles(), or simply append '/' and each name to the current object's path.

If the current object does not refer to a directory, then null is returned.

Parameters:

filter - Filtering object to include/exclude files from the list.

Returns:

The list of files or subdirectories immediately underneath the the directory referenced by this object.

listFiles

GridFile[] listFiles()

List files and subdirectories under the current directory.

If the current object refers to a directory, then the list of files or directories immediately beneath it are returned as an array of GridFile objects. The returned objects will contain absolute paths to the files or subdirectories.

If the current object does not refer to a directory, then null is returned.

Returns:

An array of files or directories immediately below the directory referenced by the current object.

listFiles

GridFile[] listFiles(GridFileNameFilter filter)

List files and subdirectories under the current directory using a filter.

If the current object refers to a directory, then the list of files or directories immediately beneath it are returned as an array of GridFile objects. The returned objects will contain absolute paths to the files or subdirectories.

If the current object does not refer to a directory, then null is returned.

Parameters:

filter - Name based file filter object.

Returns:

An array of files or directories immediately below the directory referenced by the current object.

listFiles

GridFile[] listFiles(GridFileFilter filter)

List files and subdirectories under the current directory using a filter.

If the current object refers to a directory, then the list of files or directories immediately beneath it are returned as an array of GridFile objects. The returned objects will contain absolute paths to the files or subdirectories.

If the current object does not refer to a directory, then null is returned.

Parameters:

filter - Object based file filter object.

Returns:

An array of files or directories immediately below the directory referenced by the current object.

mkdir

boolean mkdir()

Create a new empty directory.

If this object refers to a path for which getParent() refers to a directory, and which does not currently exist, then a new empty directory is created on the data grid.

Returns:

true if a new directory was successfully created.

mkdirs

boolean mkdirs()

Recursively create a new empty directory.

If no component in the path referenced by this object is a regular file, and the current user has permission to do so, then a directory is created that reflects the current data grid path. Any intermediat subdirectories are automatically created as well.

Returns:

true if a new directory was successfully created.

renameTo

boolean renameTo(GridFile dest)

Move a file or directory from one path to another.

This method is enhanced over the java.io.File version in that it automatically renames OR copies (recursively if necessary) the grid path referenced by this object to the grid path referenced by dest.

Returns:

True if the file or directory was successfully renamed.

copyTo

boolean copyTo(GridFile dest)

Copy a file or directory from one path to another.

This method is enhanced over the java.io.File version in that it provides a completely server-side copy. This is more efficient for grid operations that simply want to duplicat a grid file as another grid file without having to physically copy the file contents over the network.

Returns:

True if the file or directory was successfully copied.

get

void get(File localFile)
         throws DataGridException,
                IOException

Fetch the Data Grid file or directory to the local system.

Physically copy the file or directory referenced by this object to the local file system. The file(s) are copied to the local path specified by localFile. Directories are recursively copied.

This method will block and wait until all files are copied locally. The actual copying is handled by the current data grid client provider.

Parameters:

localFile - Abstract local path to which the file(s) are to be copied.

Throws:

DataGridException - Thrown if a system or configuration error prevents the copy of files from the grid.

IOException - Thrown if a network failure or I/O error prevents the copy of files from the grid.

multicast

void multicast(File localFile,
               DGLogger mclogger,
               String nodeId,
               long mcMin,
               long mcQuorum,
               long mcWait,
               long mcRate,
               boolean fallBack,
               boolean fallBackOnError)
               throws DataGridException,
                      IOException

Attempt to fetch the specified file as part of a combined multicast transfer.

Behaves the same as get, except that an initial attempt is made to fetch the file as part of a multicast to this and potentially many other hosts at the same time. If successful, the total network bandwith consumed by all hosts can be greatly reduced.

If multicasting is not available or not enough hosts are willing to muticast the same file in the specified wait period, then this operation transparently falls back to a normal unicast get() request.

This call is intended for use by a set of nodes running the same job and requesting the same large file from the data grid. The mcMin, mcQuorum, and mcWait are ignored for requests after the first to join any given multicast session.

Like get(), this operation honors caching requests.

Parameters:

localFile - Abstract local path to which the file(s) are to be copied.

mclogger - Multicasting subsystem log wrapper instance.

nodeId - The Node ID of the current node.

mcMin - The minimum number of receivers needed in order to multicast. If not reached, then unicast is used.

mcQuorum - The number of receivers which, when reached, will cause immediate multicast of the requested file regardless of the value of mcWait.

mcWait - The number of milliseconds to wait for other hosts to join in the requested multicast.

mcRate - The requested data rate in bytes per second.

fallBack - If true then fall back to unicast if multicast disabled.

fallBackOnError - If true then fall back to unicast if multicast fails.

Throws:

DataGridException - Thrown if a system or configuration error prevents the copy of files from the grid.

IOException - Thrown if a network failure or I/O error prevents the copy of files from the grid.

put

void put(File localFile)
         throws DataGridException,
                IOException

Store the specified local file or directory under the grid path referenced by this object.

Physically copies the local file or directory (recursively if needed) to the data grid under the path specified by this object. The parent directory of this object's path must already exist and be writable.

This method will block and wait until all files are copied to the grid. The actual copying is handled by the current data grid client provider.

Parameters:

localFile - The local path from which the file or directory is to be copied.

Throws:

DataGridException - Thrown if a system or configuration error prevents the copy of files to the grid.

IOException - Thrown if a network failure or I/O error prevents the copy of files to the grid.

follow

void follow(OutputStream out,
            OutputStream err,
            String watchJob,
            long maxUnchanged,
            long offset,
            long count,
            long interval,
            long refresh,
            long timeout,
            boolean lineMode,
            boolean retryMode,
            boolean quietMode,
            boolean nameMode,
            boolean countLines)
            throws DataGridException,
                   IOException

Output and/or follow the contents of a grid file in real time.

This operation performs the same function as Linux 'tail'. It can display the first or last N lines of a file, and/or actively follow bytes or lines added to the end of a file.

Parameters:

out - The OutputStream to which normal output will be written.

err - The OutputStream to which error and status messages will be written.

watchJob - Optional Job ID to watch. Return immediately when the job completes.

maxUnchanged - The maximum number of intervals after which the file is reopened by name in case it has been deleted and recreated.

offset - The offset (lines or bytes, depending on lineMode) at which to start reading the file.

count - The maximum number of lines or bytes (depending on lineMode) to read and output to out

interval - The number of milliseconds between rechecks of the file.

refresh - The request refresh period, in milliseconds. To avoid dead 'tail' sessions on the server, the client refreshes the request according to this interval.

timeout - The maximum number of milliseconds to wait when no bytes are received.

lineMode - If true, then offset is computed as lines of text, with either CRLF or LF counting as a line separator. Otherwise, the offset is computed as 8 bit bytes.

retryMode - If true, and the remote file does not yet exist, then the remote file watcher thread will keep trying until the file appears.

quietMode - If true, Then the remote file watcher will not send warnings or informational messages over the "error" channel.

nameMode - if true, then the remote file is "followed by name". That is, each test of the file checks whether the file has been deleted and/or replaced with a new file. This follows the semantics of the 'tail --follow=name' option for the Linux version of the 'tail' program.

countLines - If true then count is given in lines instead of bytes.

Throws:

DataGridException

IOException

cancel

void cancel()

Cancel the currently running command.

This call allows another thread to cancel and abort the currently running command. This is useful for stopping a follow command. (a.k.a. "matrix tail")

No exception is thrown by this method. If no command is currently running or the current command cannot be cancelled, no action is taken.

append

void append(String data)
            throws DataGridException

Append the string data to the end of the grid file referenced by this path.

If the file does not exist, it is created.

Throws:

DataGridException - Thrown if a system or configuration error prevents the append of data to the grid file.