|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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 |
---|
String getErrorMessage()
If there was no error, then the empty string (length zero) is returned.
This method never returns null
void query() throws DataGridException
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.
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.String getName()
Returns the last component of the canonical grid name fo this object.
String getPath()
String getParent()
If at the top level, null
is returned to
indicate that this path is at the top "root" level.
GridFile getParentFile()
If at the top level, null
is returned to
indicate that this path is at the top "root" level.
String getCanonicalPath() throws IOException
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.
IOException
- Thrown if a system or I/O error prevents determination of the
normalized path.GridFile getCanonicalFile() throws IOException
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.
IOException
- Thrown if a system or I/O error prevents determination of the
normalized path.boolean isLink()
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.
true
if the final component of getPath()
refers to a link.String getLinkName() throws IOException
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.
IOException
- If an I/O error prevents a lookup of the link information.String getLinkPath() throws IOException
This method only returns a non-null
value if the
final component of the original path used to query this file
was a link.
IOException
- If an I/O error prevents a lookup of the link information.String getLinkTarget() throws IOException
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.
IOException
- If an I/O error prevents a lookup of the link information.boolean canRead()
true
if this object represents a readable
file or directory.
true
if the referenced file/directory is readable.boolean canWrite()
true
if this object represents a writeable
file or directory.
true
if the referenced file/directory is writeable.boolean exists()
true
if this object represents an existing
file or directory.
true
if the referenced file/directory exists.boolean isDirectory()
true
if this object represents a directory.
true
if this grid path represents a directory.boolean isFile()
true
if this object represents a regular file.
true
if this grid path represents a regular file.long lastModified()
If the object does not exist, then 0L
is returned.
long length()
If the referenced object does not exist, or is not a file,
then 0L
is returned.
String getChecksum()
If this object does not refer to an existing, readable
file, then null
is returned.
boolean isCached()
true
if the file referenced by this object is
cached locally.
If this object does not reference a file, then false
is returned.
true
if the file is cached locally.void setCaching(boolean caching)
caching
- If true, then the client will attempt to cache local
copies of files.void flushCache()
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.
boolean createNewFile() throws IOException
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.
true
if a new file was successfully created.
IOException
boolean delete()
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.
true
if a the file or directory was successfully deleted.String[] list()
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.
String[] list(GridFileNameFilter 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.
filter
- Filtering object to include/exclude files from the list.
GridFile[] listFiles()
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.
GridFile[] listFiles(GridFileNameFilter 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.
filter
- Name based file filter object.
GridFile[] listFiles(GridFileFilter 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.
filter
- Object based file filter object.
boolean mkdir()
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.
true
if a new directory was successfully created.boolean mkdirs()
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.
true
if a new directory was successfully created.boolean renameTo(GridFile dest)
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
.
boolean copyTo(GridFile dest)
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.
void get(File localFile) throws DataGridException, IOException
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.
localFile
- Abstract local path to which the file(s) are to be copied.
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.void multicast(File localFile, DGLogger mclogger, String nodeId, long mcMin, long mcQuorum, long mcWait, long mcRate, boolean fallBack, boolean fallBackOnError) throws DataGridException, IOException
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.
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.
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.void put(File localFile) throws DataGridException, IOException
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.
localFile
- The local path from which the file or directory is to be copied.
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.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
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.
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.
DataGridException
IOException
void cancel()
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.
void append(String data) throws DataGridException
If the file does not exist, it is created.
DataGridException
- Thrown if a system or configuration error prevents the
append of data to the grid file.
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |