de.tum.binfo.jdrm
Class Session

java.lang.Object
  extended byde.tum.binfo.jdrm.Session
All Implemented Interfaces:
java.io.Serializable

public class Session
extends java.lang.Object
implements java.io.Serializable

Java Distributed Resource Management
Grid independent universal handler class for running arbitary java classes over a cluster system like Sun's Grid Engine.
Designed for fast and easy implementation and high computation needs.

Author:
Thorsten Schmidt
Features:
See Also:
Serialized Form

Field Summary
protected  java.lang.String classpath
           
protected  java.util.LinkedList entries
           
protected  java.lang.String jvmOptions
           
protected  int MINUTESTOWAIT
           
protected  java.lang.String nameOfSessionFile
           
protected  java.lang.String nameOfSessionFileFull
           
protected  java.lang.String pathDelimiter
           
protected  java.lang.String pathOfSessionFiles
           
protected  java.util.Random rnd
           
protected  boolean useClusterSystem
           
 
Constructor Summary
Session()
           
 
Method Summary
 java.lang.String about()
           
 boolean existJob(JobTemplate jt)
          Checks if a job has been submitted already.
 boolean existJob(java.lang.String yourUniqueName)
          Checks if a job has been submitted already.
 int[] getAllJobIds()
          Returns all job ids which are known to this session.
 java.lang.String getClasspath()
           
 JobTemplate getJobResultObj(int jobId)
          Returns the job object after it has been run.
 java.lang.String getJvmOptions()
           
 java.lang.String getPathOfSessionFiles()
           
 void init(java.lang.String sessionName, boolean useClusterSystem)
          Reads an existing session administration file or creates a new one.
protected  boolean isValidSessionName(java.lang.String str)
           
protected  boolean isValidSessionPath(java.lang.String str)
           
protected  java.lang.String makeInName(java.lang.String filename)
           
protected  java.lang.String makeOutName(java.lang.String filename)
           
protected  void readSessionFile()
           
 void setClasspath(java.lang.String string)
          Sets the classpath which will be used executing the job-objects.
 void setJvmOptions(java.lang.String string)
          Sets the options of the java virtual machine for executing a job.
 void setPathOfSessionFiles(java.lang.String string)
          Sets the path where the session administration file, job input and output object files are stored.
 int submitJob(JobTemplate jt)
          Submits any JobTemplate object and derived objects to our system.
protected  void subWaitForAllCluster()
           
 void waitForAll()
          Blocking routine which waits until all jobs have finished.
protected  void writeSessionFile()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

entries

protected java.util.LinkedList entries

pathOfSessionFiles

protected java.lang.String pathOfSessionFiles

nameOfSessionFile

protected java.lang.String nameOfSessionFile

nameOfSessionFileFull

protected java.lang.String nameOfSessionFileFull

pathDelimiter

protected java.lang.String pathDelimiter

useClusterSystem

protected boolean useClusterSystem

jvmOptions

protected java.lang.String jvmOptions

MINUTESTOWAIT

protected final int MINUTESTOWAIT
See Also:
Constant Field Values

rnd

protected java.util.Random rnd

classpath

protected java.lang.String classpath
Constructor Detail

Session

public Session()
Method Detail

isValidSessionName

protected boolean isValidSessionName(java.lang.String str)

isValidSessionPath

protected boolean isValidSessionPath(java.lang.String str)

about

public java.lang.String about()

init

public void init(java.lang.String sessionName,
                 boolean useClusterSystem)
          throws java.lang.Exception
Reads an existing session administration file or creates a new one.
Additionally it inits all necessary variables.

Structure of the session file:
jobId;unique-job-name(from user);filename-of-objfile;obj-hash

The session file (PathOfSessionFiles + sessioName + ".session") can be manually corrected, e.g. deletion of row results in a recreation, resubmit and therefore rerun of a job.

Parameters:
sessionName - : unique name of the session file,(=also prefix of all job object files). Note: the suffix .session will be added automatically
Throws:
java.lang.Exception

readSessionFile

protected void readSessionFile()

writeSessionFile

protected void writeSessionFile()
                         throws java.lang.Exception
Throws:
java.lang.Exception

existJob

public boolean existJob(JobTemplate jt)
                 throws java.lang.Exception
Checks if a job has been submitted already.

Algorithm:
Looks if the hashcode of your job-object is known in this session.
If the job has been submitted already there should be a in-object written to your file system.
If no in-object is found it checks if there is a out-object file. If both .in and .out objects are not existing it assumes that we need the output results and therefore returns false otherwise it returns true.

Returns:
boolean
Throws:
java.lang.Exception

existJob

public boolean existJob(java.lang.String yourUniqueName)
                 throws java.lang.Exception
Checks if a job has been submitted already.

Algorithm:
Looks if the uniqueName of your job-object is known in this session.
If the job has been submitted already there should be a in-object written to your file system.
If no in-object is found it checks if there is a out-object file. If both .in and .out objects are not existing it assumes that we need the output results, and therefore returns false otherwise it returns true.

Tip: It's recommended to use unique names for your jobs within your session. Then it's possible to check if the jobs have already been submitted before your actually need to generate the job instances. This may save time and memory resources.

Returns:
boolean
Throws:
java.lang.Exception

makeInName

protected java.lang.String makeInName(java.lang.String filename)

makeOutName

protected java.lang.String makeOutName(java.lang.String filename)

submitJob

public int submitJob(JobTemplate jt)
              throws java.lang.Exception
Submits any JobTemplate object and derived objects to our system.
Important:
For your programming logic it's completely regardless whether you are using a cluster system or a single machine!

Algorithm:
1) Saves JobTemplate object to a file
2) If (useClusterSystem)
{ submit to cluster and return the job-id from the cluster system}
else { generate unique job-id and return this job-id }
3) The job-admin data is stored in the .session file

Returns:
JobId: a job-Id you can use as your job-reference
Throws:
java.lang.Exception

subWaitForAllCluster

protected void subWaitForAllCluster()

waitForAll

public void waitForAll()
                throws java.lang.Exception
Blocking routine which waits until all jobs have finished.
The actual action dependes whether we are using a cluster system or a single machine.

Behavior using a single machine
All JobTemplate-Objects which are known to this session objects are sequentially processed.
If an output object already exists it continues with the next job, otherwise the job is loaded, executed and the resulting output objects stored to disk.

Behavior using a cluster system
Waits until all Job-Ids which are known to this session do not appear in the 'qtstat' output anymore or have an output object already.

in the qsub mode: For all jobs: found in qstat => wait else found out-obj => next, else => wait

Throws:
java.lang.Exception

getAllJobIds

public int[] getAllJobIds()
                   throws java.lang.Exception
Returns all job ids which are known to this session.

Returns:
int[]
Throws:
java.lang.Exception

getJobResultObj

public JobTemplate getJobResultObj(int jobId)
                            throws java.lang.Exception
Returns the job object after it has been run.
Then you can use the returned object like a common Java object instance and further use it.

Technical details:
'session.submitJob' writes the job-object in serialized form to the file system (suffix=.in) and cares about the submission process and administrative tasks.
Each job-object is then executed by the grid-system or by the 'session.waitForAll' method using the Executor-class.
The Executor class writes the job-object after the job.run method has finished as serialized object to the file system again (suffix=.out)
This method here looks up the out-object, reads it and returns it.

Returns:
JobTemplate: instance of your job. Must be casted to your derived class-type. Returns null if the job-id is not known in this session. (If the out-object file has been deleted or is not existing an exception is generated)
Throws:
java.lang.Exception

getClasspath

public java.lang.String getClasspath()
Returns:
classpath which is used executing the job-objects

setClasspath

public void setClasspath(java.lang.String string)
                  throws java.lang.Exception
Sets the classpath which will be used executing the job-objects.
It is important that all classes which the job-objects need can be found in the classpath and that these JDRM-classes are reachable through the classpath too.
Default is the class path of the process using this session class.
Note: It can only be changed before the session.init() method has been called.
Tip: Always use full paths!

Parameters:
string -
Throws:
java.lang.Exception

getPathOfSessionFiles

public java.lang.String getPathOfSessionFiles()
Returns:
path where the session administration file and job input and output object files are stores.

setPathOfSessionFiles

public void setPathOfSessionFiles(java.lang.String string)
                           throws java.lang.Exception
Sets the path where the session administration file, job input and output object files are stored.
Default ist the working directory of the process using this session class.
Note: It can only be changed before the session.init() method has been called.
Tip: Always use full paths!

Parameters:
string -
Throws:
java.lang.Exception

getJvmOptions

public java.lang.String getJvmOptions()
Returns:
String with the current options starting the Java virtual machine

setJvmOptions

public void setJvmOptions(java.lang.String string)
                   throws java.lang.Exception
Sets the options of the java virtual machine for executing a job.
It will used for the next qsub command which is generated by the submitJob-method.
The jvm-options of jobs already submitted will not be affected by this change
Default: -Xmx512m

Parameters:
string -
Throws:
java.lang.Exception


Copyright (c) 2004 Technische Universitaet Muenchen, Schmidt Thorsten