org.ourgrid.peer.ebgum
Class GumProxy

java.lang.Object
  extended by java.rmi.server.RemoteObject
      extended by java.rmi.server.RemoteServer
          extended by java.rmi.server.UnicastRemoteObject
              extended by org.ourgrid.common.rmi.OurgridUnicastRemoteObject
                  extended by org.ourgrid.peer.ebgum.GumProxy
All Implemented Interfaces:
java.io.Serializable, java.rmi.Remote, Gum, InvalidatableProxy

public class GumProxy
extends OurgridUnicastRemoteObject
implements InvalidatableProxy, Gum

It will be the remote object to be contacted by GumClient. It represents a proxy to make possible remote connections between a GumClient and the EBGumFacade. The peer holds a proxy to every Mygrid-UserAgent connection, so we have an in-band connection between the two components.

See Also:
Serialized Form

Field Summary
static long serialVersionUID
          Serial identification of the class.
 
Fields inherited from class java.rmi.server.RemoteObject
ref
 
Constructor Summary
GumProxy(EBGum gridMachineFacade, EBPeerManagerFacade peerManagerFacade, long requestID)
          Default constructor
GumProxy(EBGum gridMachineFacade, EBPeerManagerFacade peerManagerFacade, long requestID, MGSecureClientSocketFactory secureClientSocketFactory, MGSecureServerSocketFactory secureServerSocketFactory, int securePort)
          Constructor with SecureSocketFactories.
 
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 invalidate()
          Makes this proxy invalid.
 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> envVars)
          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.
 
Methods inherited from class java.rmi.server.UnicastRemoteObject
clone, exportObject, exportObject, exportObject, unexportObject
 
Methods inherited from class java.rmi.server.RemoteServer
getClientHost, getLog, setLog
 
Methods inherited from class java.rmi.server.RemoteObject
equals, getRef, hashCode, toString, toStub
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

serialVersionUID

public static final long serialVersionUID
Serial identification of the class. It need to be changed only if the class interface is changed.

See Also:
Constant Field Values
Constructor Detail

GumProxy

public GumProxy(EBGum gridMachineFacade,
                EBPeerManagerFacade peerManagerFacade,
                long requestID)
         throws java.rmi.RemoteException
Default constructor

Parameters:
gridMachineFacade - the EBGum that this proxy will forward calls
peerManagerFacade - a reference to the peer manager, useful to report when a gum is lost
requestID -
Throws:
java.rmi.RemoteException

GumProxy

public GumProxy(EBGum gridMachineFacade,
                EBPeerManagerFacade peerManagerFacade,
                long requestID,
                MGSecureClientSocketFactory secureClientSocketFactory,
                MGSecureServerSocketFactory secureServerSocketFactory,
                int securePort)
         throws java.rmi.RemoteException
Constructor with SecureSocketFactories.

Parameters:
gridMachineFacade -
peerManagerFacade -
secureClientSocketFactory -
secureServerSocketFactory -
securePort -
Throws:
java.rmi.RemoteException
Method Detail

putFile

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

Specified by:
putFile in interface Gum
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.
See Also:
Gum.putFile(String, byte[], boolean)

getFile

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

Specified by:
getFile in interface Gum
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.
See Also:
Gum.getFile(String, long, int)

createPlaypen

public java.lang.String createPlaypen(int size)
                               throws java.rmi.RemoteException,
                                      UnableToCreatePlaypenException
Description copied from interface: Gum
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.

Specified by:
createPlaypen in interface Gum
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
See Also:
Gum.createPlaypen( int )

createStorageDirectory

public java.lang.String createStorageDirectory()
                                        throws java.rmi.RemoteException,
                                               UnableToCreateStorageException
Description copied from interface: Gum
Creates the storage directory. If it already exists, nothing is done.

Specified by:
createStorageDirectory in interface Gum
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
See Also:
Gum.createStorageDirectory()

getStorageDirectory

public java.lang.String getStorageDirectory()
                                     throws java.rmi.RemoteException
Description copied from interface: Gum
Returns the remote storage directory. If it does not exist, it should be created.

Specified by:
getStorageDirectory in interface Gum
Returns:
the path of the storage directory.
Throws:
java.rmi.RemoteException
See Also:
Gum.getStorageDirectory()

fileExists

public boolean fileExists(java.io.File file)
                   throws java.rmi.RemoteException
Description copied from interface: Gum
Check if the file denoted by file abstraction exists.

Specified by:
fileExists in interface Gum
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
See Also:
Gum.fileExists(File)

getRemoteFileLength

public long getRemoteFileLength(java.io.File remoteFile)
                         throws java.rmi.RemoteException,
                                java.io.IOException
Description copied from interface: Gum
Determines the remote file size in bytes.

Specified by:
getRemoteFileLength in interface Gum
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.
See Also:
Gum.getRemoteFileLength(File)

getRemoteFileLastModification

public long getRemoteFileLastModification(java.io.File remoteFile,
                                          boolean normalized)
                                   throws java.rmi.RemoteException,
                                          java.io.IOException
Description copied from interface: Gum
Gets the time when the last modification in the specified file has occurred.

Specified by:
getRemoteFileLastModification in interface Gum
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.
See Also:
Gum.getRemoteFileLastModification(File, boolean)

getRemoteFileDigest

public java.lang.String getRemoteFileDigest(java.io.File remoteFile)
                                     throws java.rmi.RemoteException,
                                            UnableToDigestFileException
Description copied from interface: Gum
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.

Specified by:
getRemoteFileDigest in interface Gum
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:
java.rmi.RemoteException - if some RMI error occurs during the method invocation
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.
See Also:
Gum.getRemoteFileDigest(java.io.File)

changeFilePermissions

public void changeFilePermissions(java.io.File file,
                                  int permissions)
                           throws java.rmi.RemoteException,
                                  java.io.IOException
Description copied from interface: Gum
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.

Specified by:
changeFilePermissions in interface Gum
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.
See Also:
Gum.changeFilePermissions(java.io.File, int)

remoteExecute

public ExecutorHandle remoteExecute(java.lang.String remoteDir,
                                    java.lang.String command,
                                    java.util.Map<java.lang.String,java.lang.String> envVars)
                             throws java.rmi.RemoteException,
                                    ExecutorException
Description copied from interface: Gum
Executes a remote task command in a specific directory on the grid machine.

Specified by:
remoteExecute in interface Gum
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.
envVars - 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
See Also:
Gum.remoteExecute(String, String, Map)

getResult

public ExecutorResult getResult(ExecutorHandle handle)
                         throws java.rmi.RemoteException,
                                ExecutorException
Description copied from interface: Gum
Gives access to the result of execution.

Specified by:
getResult in interface Gum
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
See Also:
Gum.getResult(ExecutorHandle)

invalidate

public void invalidate()
Makes this proxy invalid. First, it sets the proxy as invalid, then puts a invalidation event on every blocked event queue. Its Stops replica currently executing on the gum

Specified by:
invalidate in interface InvalidatableProxy

getStatus

public GumStatus getStatus()
Description copied from interface: Gum
Gets the status of the grid machine. It may assume one of five states: UP, READY, RUNNING, OWNER and DOWN, described above.

Specified by:
getStatus in interface Gum
Returns:
the status of this GridMachine.
See Also:
Gum.getStatus()

startReplica

public void startReplica()
                  throws java.rmi.RemoteException
Description copied from interface: Gum
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.

Specified by:
startReplica in interface Gum
Throws:
java.rmi.RemoteException - if some RMI error occurs during this method invocation.
See Also:
Gum.startReplica()

stopReplica

public void stopReplica()
                 throws java.rmi.RemoteException
Description copied from interface: Gum
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.

Specified by:
stopReplica in interface Gum
Throws:
java.rmi.RemoteException - If some RMI error occurs during this method invocation.
See Also:
Gum.stopReplica()