org.ourgrid.common.gum
Interface Gum

All Superinterfaces:
java.rmi.Remote
All Known Implementing Classes:
FakeUserAgentServer, GumProxy, UserAgentServerImpl

public interface Gum
extends java.rmi.Remote

Represents a grid machine, which is an abstraction that allows a user to use a remote machine on the grid without knowing about its particularities (for example: the installed OS) . This interface defines the minimal set of operations needed to execute a task on machines in a grid, abstracting their differences. Namely, the operations that comprise this minimal set are:

All implementations of Gum must be thread-safe. That is, they must support calling of their methods by multiple threads consistently. Furthermore, implementations that also support parallel threads running each method are very much encouraged (that is: multiple file transfers or multiple commands running).

Each instance of Gum also has an unique name that identifies it, and a list of attributes. Such name is the network address (for example: baleia.dsc.ufpb.edu.br) plus a port number (for example: 3089). The tuple (address,port) identifies a single machine in the grid and is used to reference the grid machine.

The attributes of a Gum are a set of name/value pairs that represent the machine characteristics. The semantics of the attributes is given by the user. They are used to verify if a grid machine satisfies the requirements of a request. This verification is done by the provider.

This interface is part of the core interfaces of the OurGrid project, along with Gump and GumpClient. They define a general way of getting access to and use machines on a grid, abstracting differences in doing so.

See Also:
GumClient

Method Summary
 void changeFilePermissions(java.io.File file, int permissions)
          Change the permissions of a file located at the Grid Machine.
 java.lang.String createPlaypen(int size)
          Creates a playpen in the Grid Machine.
 java.lang.String createStorageDirectory()
          Creates the storage directory.
 boolean fileExists(java.io.File file)
          Check if the file denoted by file abstraction exists.
 byte[] getFile(java.lang.String filePath, long filePos, int size)
          Get an array of bytes FROM a file that is located at the Grid Machine.
 java.lang.String getRemoteFileDigest(java.io.File remoteFile)
          Used to return the digest representation of a file.
 long getRemoteFileLastModification(java.io.File remoteFile, boolean normalized)
          Gets the time when the last modification in the specified file has occurred.
 long getRemoteFileLength(java.io.File remoteFile)
          Determines the remote file size in bytes.
 ExecutorResult getResult(ExecutorHandle handle)
          Gives access to the result of execution.
 GumStatus getStatus()
          Gets the status of the grid machine.
 java.lang.String getStorageDirectory()
          Returns the remote storage directory.
 void putFile(java.lang.String remoteFile, byte[] data, boolean firstSlice)
          Put an array of bytes INTO the file specified by removeFile at the Grid Machine.
 ExecutorHandle remoteExecute(java.lang.String remoteDir, java.lang.String command, java.util.Map<java.lang.String,java.lang.String> environmentVars)
          Executes a remote task command in a specific directory on the grid machine.
 void startReplica()
          Determines a replica start.
 void stopReplica()
          Tells the user agent to kill any executing tasks and also clean the environment to a next execution.
 

Method Detail

remoteExecute

ExecutorHandle remoteExecute(java.lang.String remoteDir,
                             java.lang.String command,
                             java.util.Map<java.lang.String,java.lang.String> environmentVars)
                             throws java.rmi.RemoteException,
                                    ExecutorException
Executes a remote task command in a specific directory on the grid machine.

Parameters:
remoteDir - directory where the command will be executed. For example, in a Unix environment, a cd to this directory will be done before running the specified command.
command - the command that will be executed in the specified directory.
environmentVars - a Map containing a set of environment variable names as the keys and the corresponding values as the values set. All these variables will be set before the execution of the command. The keys and values of Map should be String or, at least, override the Object#toString method.
Returns:
A handle that identifies executions dispatched to instances of a native Executor class.
Throws:
java.rmi.RemoteException - if some RMI error occurs during the method invocation.
ExecutorException - if some error occurs during the remote execution of the command

putFile

void putFile(java.lang.String remoteFile,
             byte[] data,
             boolean firstSlice)
             throws java.rmi.RemoteException,
                    java.io.IOException
Put an array of bytes INTO the file specified by removeFile at the Grid Machine.

Parameters:
remoteFile - the name of file that where the array of bytes will be appended
data - an array of bytes that must be appended to the file.
firstSlice - Indicates if the array of bytes is the first slice of the file or not. If true and remoteFile exists, the file will be overwritten. Otherwise, the array of bytes will just be appended to the file.
Throws:
java.rmi.RemoteException - if some RMI error occurs during the putFile() method invocation.
java.io.IOException - if some error occurs during the writing process.

getFile

byte[] getFile(java.lang.String filePath,
               long filePos,
               int size)
               throws java.rmi.RemoteException,
                      java.io.IOException
Get an array of bytes FROM a file that is located at the Grid Machine.

Parameters:
filePath - the path where the file is located.
filePos - the position into the file from the array will be read.
size - the size of array of bytes that must be read.
Returns:
the array of bytes read from the file.
Throws:
java.rmi.RemoteException - if some RMI error occurs during the method invocation
java.io.IOException - if some error occurs during the reading process.

getResult

ExecutorResult getResult(ExecutorHandle handle)
                         throws java.rmi.RemoteException,
                                ExecutorException
Gives access to the result of execution.

Parameters:
handle - a handle that identifies the execution of interest
Returns:
an object that contains information about the execution (exit value, stderr, stdout).
Throws:
java.rmi.RemoteException
ExecutorException

fileExists

boolean fileExists(java.io.File file)
                   throws java.rmi.RemoteException
Check if the file denoted by file abstraction exists.

Parameters:
file - the file that will be searched
Returns:
true if the file exists, false otherwise.
Throws:
java.rmi.RemoteException - if some RMI error occurs during the method invocation

changeFilePermissions

void changeFilePermissions(java.io.File file,
                           int permissions)
                           throws java.rmi.RemoteException,
                                  java.io.IOException
Change the permissions of a file located at the Grid Machine. For example, change the permissions of a script file, in order to execute it.

Parameters:
file - the file which permissions will be changed.
permissions - a string specifying the permissions. The string must be composed of three numbers, like in the UNIX-like systems. For instance, "rwxrwx---" must be represented by "770".
Throws:
java.rmi.RemoteException - if some RMI error occurs during the method invocation
java.io.IOException - if some error occurs while trying to read or write current permission of file.

getRemoteFileLength

long getRemoteFileLength(java.io.File remoteFile)
                         throws java.rmi.RemoteException,
                                java.io.IOException
Determines the remote file size in bytes.

Parameters:
remoteFile - The file located at the Grid Machine which the size must be determined.
Returns:
The size of the file in bytes.
Throws:
java.rmi.RemoteException - if some RMI error occurs during the method invocation
java.io.IOException - If some problem occurs during the access to the file.

getRemoteFileLastModification

long getRemoteFileLastModification(java.io.File remoteFile,
                                   boolean normalized)
                                   throws java.rmi.RemoteException,
                                          java.io.IOException
Gets the time when the last modification in the specified file has occurred.

Parameters:
remoteFile - The file located at the Grid Machine which the modification time will be determined.
normalized - Indicates if the last modification time must be normalized to the TIMEZONE-0.
Returns:
The number of milliseconds from 1/Jan/1970 to the moment of file last modification.
Throws:
java.rmi.RemoteException - if some RMI error occurs during the method invocation
java.io.IOException - if during the access to the file some problem occurs.

getRemoteFileDigest

java.lang.String getRemoteFileDigest(java.io.File remoteFile)
                                     throws java.rmi.RemoteException,
                                            UnableToDigestFileException
Used to return the digest representation of a file. Files with the same content must have the same digest. Different content files must have different digests.

Parameters:
remoteFile - if the file used to generate the digest
Returns:
The digest representation of the file or 0 if its a digest from a directory.
Throws:
UnableToDigestFileException - if there is any problem on the digest generation, like the file is not found, I/O errors or the digest algorithm is not valid.
java.rmi.RemoteException - if some RMI error occurs during the method invocation

createPlaypen

java.lang.String createPlaypen(int size)
                               throws java.rmi.RemoteException,
                                      UnableToCreatePlaypenException
Creates a playpen in the Grid Machine. The playpen is supposed to be an area reserved to store temporary files related to the execution of a Task. It is important that a gum consumer always call stopReplica() after using the gum to assure the playpen will be destroyed.

Parameters:
size - The number of bytes that must be reserved to the playpen.
Returns:
The path to the directory at the Grid Machine corresponding to the playpen.
Throws:
java.rmi.RemoteException - If some RMI error occurs during this method invocation.
UnableToCreatePlaypenException - if the playpen could not be created. This will be usually due to I/O issues, like user space quota exceeded

createStorageDirectory

java.lang.String createStorageDirectory()
                                        throws java.rmi.RemoteException,
                                               UnableToCreateStorageException
Creates the storage directory. If it already exists, nothing is done.

Returns:
the absolute path of the storage directory.
Throws:
java.rmi.RemoteException - if some RMI error occurs during this method invocation.
UnableToCreateStorageException - if the storage directory could not be created. This will be usually due to I/O issues, like user space quota exceeded

getStorageDirectory

java.lang.String getStorageDirectory()
                                     throws java.rmi.RemoteException
Returns the remote storage directory. If it does not exist, it should be created.

Returns:
the path of the storage directory.
Throws:
java.rmi.RemoteException

getStatus

GumStatus getStatus()
                    throws java.rmi.RemoteException
Gets the status of the grid machine. It may assume one of five states: UP, READY, RUNNING, OWNER and DOWN, described above.

Returns:
the status of this GridMachine.
Throws:
java.rmi.RemoteException - if some RMI error occurs during this method invocation.
See Also:
GumStatus

startReplica

void startReplica()
                  throws java.rmi.RemoteException
Determines a replica start. When a replica is started the gum must listen and hold information about created directories, process and anything that is created during the replica execution. It's impossible to execute anything or create a playpen at the gum before this method is called.

Throws:
java.rmi.RemoteException - if some RMI error occurs during this method invocation.

stopReplica

void stopReplica()
                 throws java.rmi.RemoteException
Tells the user agent to kill any executing tasks and also clean the environment to a next execution. This is done by cleaning any playpen created. Any invalidation or shutdown must invoke this method to assure that the gum is clean.

Throws:
java.rmi.RemoteException - If some RMI error occurs during this method invocation.