org.gridlab.gat.io
Class File

java.lang.Object
  extended by java.io.File
      extended by org.gridlab.gat.io.File
All Implemented Interfaces:
Serializable, Comparable<File>, Advertisable, Monitorable

public class File
extends File
implements Monitorable, Advertisable, Serializable

An abstract representation of a physical file. See File.

An instance of this class presents an abstract, system-independent view of a physical file. User interfaces and operating systems use system-dependent pathname strings to identify physical files. GAT, however, uses an operating system independent pathname string to identify a physical file. A physical file in GAT is identified by a URI.

An instance of this File class allows for various high-level operations to be performed on a physical file. For example, one can, with a single API call, copy a physical file from one location to a second location, move a physical file from one location to a second location, delete a physical file, and perform various other operations on a physical file. The utility of this high-level view of a physical file is multi-fold. The client of an instance of this class does not have to concern themselves with the details of reading every single byte of a physical file when all they wish to do is copy the physical file to a new location. Similarly, a client does not have to deal with all the various error states that can occur when moving a physical file. Have all the various bytes been read correctly? Have all the various bytes been saved correctly? Did the deletion of the original file proceed correctly? The client simply has to call a single API call and the physical file is moved.

See Also:
Serialized Form

Field Summary
 
Fields inherited from class java.io.File
pathSeparator, pathSeparatorChar, separator, separatorChar
 
Constructor Summary
File(org.gridlab.gat.io.FileInterface f)
          Do not use this constructor, it is for internal GAT use.
 
Method Summary
 void addMetricListener(MetricListener metricListener, Metric metric)
          This method adds the passed instance of a MetricListener to the list of MetricListeners which are notified of MetricEvents by an instance of this class.
 boolean canRead()
           
 boolean canWrite()
           
 int compareTo(File pathname)
           
 void copy(URI loc)
          This method copies the physical file represented by this File instance to a physical file identified by the passed URI.
 boolean createNewFile()
           
 boolean delete()
           
 void deleteOnExit()
           
 boolean equals(Object obj)
           
 boolean exists()
           
 File getAbsoluteFile()
           
 String getAbsolutePath()
           
 File getCanonicalFile()
           
 String getCanonicalPath()
           
<V extends FileAttributeView>
V
getFileAttributeView(Class<V> type, boolean followSymbLinks)
          Returns a file attribute view of a given type.
 org.gridlab.gat.io.FileInterface getFileInterface()
          Returns the FileInterface object associated with this File.
 MetricEvent getMeasurement(Metric metric)
          Returns a MetricEvent that represents the measured Metric.
 MetricDefinition getMetricDefinitionByName(String name)
          Gets the MetricDefinition using its name.
 List<MetricDefinition> getMetricDefinitions()
          This method returns a List of MetricDefinition instances.
 String getName()
           
 String getParent()
           
 File getParentFile()
           
 String getPath()
           
 int hashCode()
           
 boolean isAbsolute()
           
 boolean isDirectory()
           
 boolean isFile()
           
 boolean isHidden()
           
 long lastModified()
           
 long length()
           
 String[] list()
           
 String[] list(FilenameFilter filter)
           
 File[] listFiles()
           
 File[] listFiles(FileFilter filter)
           
 File[] listFiles(FilenameFilter filter)
           
 String marshal()
          Create a String representation of this object.
 boolean mkdir()
           
 boolean mkdirs()
           
 void move(URI location)
          This method moves the physical file represented by this File instance to a physical file identified by the passed URI.
 void recursivelyDeleteDirectory()
          This method deletes a directory and everything that is in it.
 void removeMetricListener(MetricListener metricListener, Metric metric)
          Removes the passed MetricListener from the List of MetricListeners which are notified of MetricEvents corresponding to the passed Metric instance.
 boolean renameTo(File dest)
           
 boolean setLastModified(long time)
           
 boolean setReadOnly()
           
 URI toGATURI()
           
 String toString()
           
 URI toURI()
           
 URL toURL()
           
 
Methods inherited from class java.io.File
canExecute, compareTo, createTempFile, createTempFile, getFreeSpace, getTotalSpace, getUsableSpace, listRoots, setExecutable, setExecutable, setReadable, setReadable, setWritable, setWritable
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

File

public File(org.gridlab.gat.io.FileInterface f)
Do not use this constructor, it is for internal GAT use.

Method Detail

copy

public void copy(URI loc)
          throws GATInvocationException
This method copies the physical file represented by this File instance to a physical file identified by the passed URI.

Parameters:
loc - The new location
Throws:
GATInvocationException - Thrown upon problems accessing the remote instance

getFileInterface

public org.gridlab.gat.io.FileInterface getFileInterface()
Returns the FileInterface object associated with this File. Use The FileInterface offers the same functionality as the File object. The difference between the FileInterface object and the File object is that the FileInterface is an internal GAT object and it will throw GATInvocationExceptions upon failures, whereas the File object would have default values.

This might be handy in certain circumstances. Suppose that one checks whether a file exists and if not one creates a file at that location. Using the File object the code will look like this:

if (!file.exists()) { file.createNewFile(); }

Now suppose that the exists() call fails because the network is down for a moment. The File object will return false for this call, because the network was down, even though the file might exist. To overcome this one can change the code to code which uses the FileInterface instead of the File object:

if (!file.getFileInterface().exists()) { file.getFileInterface().createNewFile(); }

Now an exception will be thrown by the FileInterface if the network is down. It is possible to retry the code until the network is up again.

Returns:
the FileInterface object

move

public void move(URI location)
          throws GATInvocationException
This method moves the physical file represented by this File instance to a physical file identified by the passed URI.

Parameters:
location - The URI to which to move the physical file corresponding to this File instance
Throws:
GATInvocationException - Thrown upon problems accessing the remote instance

recursivelyDeleteDirectory

public void recursivelyDeleteDirectory()
                                throws GATInvocationException
This method deletes a directory and everything that is in it. This method can only be called on a directory, not on a file.

Throws:
GATInvocationException

canRead

public boolean canRead()
Overrides:
canRead in class File
See Also:
File.canRead()

canWrite

public boolean canWrite()
Overrides:
canWrite in class File
See Also:
File.canWrite()

compareTo

public int compareTo(File pathname)
See Also:
File.compareTo(java.io.File)

createNewFile

public boolean createNewFile()
                      throws IOException
Overrides:
createNewFile in class File
Throws:
IOException
See Also:
File.createNewFile()

delete

public boolean delete()
Overrides:
delete in class File
See Also:
File.delete()

deleteOnExit

public void deleteOnExit()
Overrides:
deleteOnExit in class File
See Also:
File.deleteOnExit()

equals

public boolean equals(Object obj)
Overrides:
equals in class File
See Also:
File.equals(java.lang.Object)

exists

public boolean exists()
Overrides:
exists in class File
See Also:
File.exists()

getAbsoluteFile

public File getAbsoluteFile()
Overrides:
getAbsoluteFile in class File
See Also:
File.getAbsoluteFile()

getAbsolutePath

public String getAbsolutePath()
Overrides:
getAbsolutePath in class File
See Also:
File.getAbsolutePath()

getCanonicalFile

public File getCanonicalFile()
                      throws IOException
Overrides:
getCanonicalFile in class File
Throws:
IOException
See Also:
File.getCanonicalFile()

getCanonicalPath

public String getCanonicalPath()
                        throws IOException
Overrides:
getCanonicalPath in class File
Throws:
IOException
See Also:
File.getCanonicalPath()

getFileAttributeView

public <V extends FileAttributeView> V getFileAttributeView(Class<V> type,
                                                            boolean followSymbLinks)
Returns a file attribute view of a given type.

A file attribute view provides a read-only or updatable view of a set of file attributes. This method is intended to be used where the file attribute view defines type-safe methods to read or update the file attributes. The type parameter is the type of the attribute view required and the method returns an instance of that type if supported. The BasicFileAttributeView type supports access to the basic attributes of a file. Invoking this method to select a file attribute view of that type will always return an instance of that class.

The followSymbLinks option may be used to indicate how symbolic links are handled by the resulting file attribute view for the case that the file is a symbolic link. By default, symbolic links are followed. If the option is set to false then symbolic links are not followed. This option is ignored by implementations that do not support symbolic links.

Parameters:
type - The Class object corresponding to the file attribute view
followSymbLinks - boolean indicating how symbolic links are handled
Returns:
A file attribute view of the specified type, or null if the attribute view type is not available

getName

public String getName()
Overrides:
getName in class File
See Also:
File.getName()

getParent

public String getParent()
Overrides:
getParent in class File
See Also:
File.getParent()

getParentFile

public File getParentFile()
Overrides:
getParentFile in class File
Returns:
the parent file
See Also:
File.getParentFile()

getPath

public String getPath()
Overrides:
getPath in class File
See Also:
File.getPath()

hashCode

public int hashCode()
Overrides:
hashCode in class File
See Also:
File.hashCode()

isAbsolute

public boolean isAbsolute()
Overrides:
isAbsolute in class File
See Also:
File.isAbsolute()

isDirectory

public boolean isDirectory()
Overrides:
isDirectory in class File
See Also:
File.isDirectory()

isFile

public boolean isFile()
Overrides:
isFile in class File
See Also:
File.isFile()

isHidden

public boolean isHidden()
Overrides:
isHidden in class File
See Also:
File.isHidden()

lastModified

public long lastModified()
Overrides:
lastModified in class File
See Also:
Please note there's an issue with the gt4 file adaptor (gt4gridftp). It takes time zones into account where as the {@link java.io.File#lastModified()} doesn't. For instance a file that's last modified on 10 July 1984 at 00:00 GMT +2:00 will have a last modified time of 9 July 1984 at 22:00 using the gt4 file adaptor. The {@link java.io.File#lastModified()} will return 10 July 1984, 00:00.

length

public long length()
Overrides:
length in class File
See Also:
File.length()

list

public String[] list()
Overrides:
list in class File
See Also:
File.list()

list

public String[] list(FilenameFilter filter)
Overrides:
list in class File
See Also:
File.list(java.io.FilenameFilter)

listFiles

public File[] listFiles()
Overrides:
listFiles in class File
See Also:
File.listFiles()

listFiles

public File[] listFiles(FileFilter filter)
Overrides:
listFiles in class File
See Also:
File.listFiles(java.io.FileFilter)

listFiles

public File[] listFiles(FilenameFilter filter)
Overrides:
listFiles in class File
See Also:
File.listFiles(java.io.FilenameFilter)

mkdir

public boolean mkdir()
Overrides:
mkdir in class File
See Also:
File.mkdir()

mkdirs

public boolean mkdirs()
Overrides:
mkdirs in class File
See Also:
File.mkdirs()

renameTo

public boolean renameTo(File dest)
Overrides:
renameTo in class File
See Also:
File.renameTo(java.io.File)

setLastModified

public boolean setLastModified(long time)
Overrides:
setLastModified in class File
See Also:
File.setLastModified(long)

setReadOnly

public boolean setReadOnly()
Overrides:
setReadOnly in class File
See Also:
File.setReadOnly()

toString

public String toString()
Overrides:
toString in class File
See Also:
File.toString()

toURI

public URI toURI()
Overrides:
toURI in class File
See Also:
File.toURI()

toGATURI

public URI toGATURI()
See Also:
File.toURI()

toURL

public URL toURL()
          throws MalformedURLException
Overrides:
toURL in class File
Throws:
MalformedURLException
See Also:
this method does {@link java.io.File#toURI()}.toURL(), because {@link java.io.File#toURL()} is deprecated.

marshal

public String marshal()
Description copied from interface: Advertisable
Create a String representation of this object. This method should not be used, it is used internally in the GAT.

Specified by:
marshal in interface Advertisable
Returns:
a String representation of this object

addMetricListener

public void addMetricListener(MetricListener metricListener,
                              Metric metric)
                       throws GATInvocationException
Description copied from interface: Monitorable
This method adds the passed instance of a MetricListener to the list of MetricListeners which are notified of MetricEvents by an instance of this class. The passed MetricListener is only notified of MetricEvents which correspond to Metric instance passed to this method.

Specified by:
addMetricListener in interface Monitorable
Parameters:
metricListener - The MetricListener to notify of MetricEvents
metric - The Metric corresponding to the MetricEvents for which the passed MetricListener will be notified
Throws:
GATInvocationException - The MetricListener cannot be added

getMeasurement

public MetricEvent getMeasurement(Metric metric)
                           throws GATInvocationException
Description copied from interface: Monitorable
Returns a MetricEvent that represents the measured Metric.

Specified by:
getMeasurement in interface Monitorable
Returns:
a MetricEvent that represents the measured Metric.
Throws:
GATInvocationException - the measurement failed

getMetricDefinitionByName

public MetricDefinition getMetricDefinitionByName(String name)
                                           throws GATInvocationException
Description copied from interface: Monitorable
Gets the MetricDefinition using its name.

Specified by:
getMetricDefinitionByName in interface Monitorable
Parameters:
name - The MetricDefinition name
Returns:
The MetricDefinition with the given name
Throws:
GATInvocationException - An error occurred while getting the list of Metrics or no Metric with this name exists

getMetricDefinitions

public List<MetricDefinition> getMetricDefinitions()
                                            throws GATInvocationException
Description copied from interface: Monitorable
This method returns a List of MetricDefinition instances. Each instance in this List is a MetricDefinition which can be monitored on this instance.

Specified by:
getMetricDefinitions in interface Monitorable
Returns:
An List of MetricDefinition instances. Each instance in this List is a Metric which can be monitored on this instance
Throws:
GATInvocationException - An error occurred while getting the list of metrics

removeMetricListener

public void removeMetricListener(MetricListener metricListener,
                                 Metric metric)
                          throws GATInvocationException
Description copied from interface: Monitorable
Removes the passed MetricListener from the List of MetricListeners which are notified of MetricEvents corresponding to the passed Metric instance.

Specified by:
removeMetricListener in interface Monitorable
Parameters:
metricListener - The MetricListener to notify of MetricEvents
metric - The Metric corresponding to the MetricEvents for which the passed MetricListener has been notified
Throws:
GATInvocationException - The MetricListener cannot be removed