org.gridlab.gat.resources
Class SoftwareDescription

java.lang.Object
  extended by org.gridlab.gat.resources.SoftwareDescription
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
JavaSoftwareDescription

public class SoftwareDescription
extends Object
implements Serializable

An instance of this class is a description of a piece of software (component) which is to be submitted as a job. It currently takes a table describing this piece of software's attributes to any underlying job submission system.

The following attributes are defined in the specification and should be recognized by ResourceBroker adaptors.

Minimum set of supported name/value pairs
Name Type Description
directory String working directory
count (deprecated use JobDescription.setProcessCount(int)) Integer/String number of executables to run
host.count (deprecated use JobDescription.setResourceCount(int)) Integer/String number of hosts to distribute on
time.max Long/String The maximum walltime or cputime for a single execution of the executable. The units is in minutes.
walltime.max Long/String the maximum walltime in minutes
cputime.max Long/String the maximum cputime in minutes
job.type String single|multiple|mpi|condor|...
project String project to use, for accounting purposes
dry.run String if set, don't submit but return success
memory.min String minimal required memory in MB
memory.max String maximal required memory in MB
save.state Boolean/String keep job data persistent for restart
restart String restart job with given ID

Author:
rob
See Also:
Serialized Form

Field Summary
static String CPUTIME_MAX
          Indicates the maximum cputime for a single execution of the executable.
static String DIRECTORY
          Indicates the working directory.
static String DRY_RUN
          If set, don't submit but return success.
static String HOST_COUNT
          Indicates the number of hosts to distribute on.
static String JOB_QUEUE
          Indicates a job queue: FORK, SGE, PBS, ...
static String JOB_TYPE
          Indicates the job type: single|multiple|mpi|condor|...
static String MEMORY_MAX
          Indicates the minimal required memory in MB.
static String MEMORY_MIN
          Indicates the minimal required memory in MB.
static String PROJECT
          Indicates the project to use, for accounting purposes.
static String RESTART
          Indicates the job id of a to-be-restarted job.
static String SANDBOX_DELETE
          Boolean attribute that indicates if the sandbox is to be deleted after the run.
static String SANDBOX_POSTSTAGE_STDERR
          Boolean attribute that indicates if the stderr file should be poststaged when the job is finished.
static String SANDBOX_POSTSTAGE_STDOUT
          Boolean attribute that indicates if the stdout file should be poststaged when the job is finished.
static String SANDBOX_PRESTAGE_STDIN
          Boolean attribute that indicates if the stdin file should be prestaged before the job is submitted.
static String SANDBOX_ROOT
          When set, defines a path to the root where sandbox directories are created.
static String SANDBOX_USEROOT
          Boolean attribute that indicates that the directory specified with the SANDBOX_ROOT attribute should itself be used as a sandbox (instead of creating the sandbox in this directory).
static String SAVE_STATE
          Indicates that the job data must be kept persistent for restart.
static String STOP_ON_EXIT
          Boolean attribute that indicates if the job needs to be terminated when GAT exits.
static String TIME_MAX
          Indicates the maximum walltime or cputime for a single execution of the executable.
static String WALLTIME_MAX
          Indicates the maximum walltime for a single execution of the executable.
 
Constructor Summary
SoftwareDescription()
          Create a SoftwareDescription, which describes the application you want to run.
SoftwareDescription(Map<String,Object> attributes)
          Create a SoftwareDescription, which describes the application you want to run.
SoftwareDescription(String jsdlString)
          To be implemented.
 
Method Summary
 void addAttribute(String key, Object value)
          Add an attribute to the existing attribute set.
 void addDeletedFile(File file)
          Adds a File to the set of Files that should be deleted after the run.
 void addPostStagedFile(File src)
          Add a single post stage file.
 void addPostStagedFile(File src, File dest)
          Add a single post stage file that should be post staged to the given destination.
 void addPreStagedFile(File src)
          Add a single pre stage file.
 void addPreStagedFile(File src, File dest)
          Add a single pre stage file that should be pre staged to the given destination.
 void addWipedFile(File file)
          Adds a File to the set of Files that should be wiped after the run.
 Object clone()
           
 boolean deletePostStaged()
          Returns whether the Files in the post stage file set should be deleted after the post staging.
 boolean deletePreStaged()
          Returns whether the Files in the pre stage file set should be deleted after the post staging.
 void enableStreamingStderr(boolean enabled)
          Enable or disable streaming standard error.
 void enableStreamingStdin(boolean enabled)
          Enable or disable streaming standard input.
 void enableStreamingStdout(boolean enabled)
          Enable or disable streaming standard output.
 boolean equals(Object o)
          Tests this SoftwareDescription for equality with the passed Object.
 String[] getArguments()
          Returns the arguments of the executable.
 Map<String,Object> getAttributes()
          Gets the attributes of this SoftwareDescription.
 boolean getBooleanAttribute(String name, boolean defaultVal)
          Returns the boolean value of an attribute.
 List<File> getDeletedFiles()
          Returns a List of the Files that should be deleted after the run.
 Map<String,Object> getEnvironment()
          Returns the environment of the executable.
 String getExecutable()
          Returns the path to the executable.
 int getIntAttribute(String name, int defaultVal)
          Returns the int value of an attribute.
 String getJSDL()
          to be implemented.
 long getLongAttribute(String name, long defaultVal)
          Returns the long value of an attribute.
 Object getObjectAttribute(String name)
          Returns the Object value of an attribute.
 Map<File,File> getPostStaged()
          Returns the post stage file set.
 Map<File,File> getPreStaged()
          Returns the pre staged file set.
 File getStderr()
          Returns the stderr File.
 File getStdin()
          Returns the stdin File.
 File getStdout()
          Returns the stdout File.
 String getStringAttribute(String name, String defaultVal)
          Returns the String value of an attribute.
 List<File> getWipedFiles()
          Returns a List of the Files that should be wiped and deleted after the run.
 int hashCode()
          Returns the hashcode of this SoftwareDescription
 Object removeAttribute(String key)
          Remove an attribute from the attribute set.
 void setArguments(String... arguments)
          Sets the arguments of the executable.
 void setAttributes(Map<String,Object> attributes)
          Set the attributes to the attributes specified in the Map.
 void setDeletePostStaged(boolean deletePostStaged)
          Sets the value which is used to determine whether the Files in the post stage file set should be deleted after the post staging.
 void setDeletePreStaged(boolean deletePreStaged)
          Sets the value which is used to determine whether the Files in the pre stage file set should be deleted after the post staging.
 void setEnvironment(Map<String,Object> environment)
          Sets the environment of the executable.
 void setExecutable(String executable)
          Sets the path to the executable.
 void setPostStaged(File... files)
          Sets the post staged file set.
 void setPreStaged(File... files)
          Sets the pre staged file set.
 void setStderr(File stderr)
          Sets the stderr File.
 void setStdin(File stdin)
          Sets the File where stdin is redirected from.
 void setStdout(File stdout)
          Sets the stdout File.
 void setWipePostStaged(boolean wipePostStaged)
          Sets the value which is used to determine whether the Files in the post stage file set should be wiped after the post staging.
 void setWipePreStaged(boolean wipePreStaged)
          Sets the value which is used to determine whether the Files in the pre stage file set should be wiped after the post staging.
 boolean streamingStderrEnabled()
          Returns whether streaming standard error is enabled.
 boolean streamingStdinEnabled()
          Returns whether streaming standard input is enabled.
 boolean streamingStdoutEnabled()
          Returns whether streaming standard output is enabled.
 String toString()
           
 void toWrapper(GATContext context, String wrapperFileName, String exitValueFileName)
          Do not use this method.
 boolean wipePostStaged()
          Returns whether the Files in the post stage file set should be wiped after the post staging.
 boolean wipePreStaged()
          Returns whether the Files in the pre stage file set should be wiped after the post staging.
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

DIRECTORY

public static final String DIRECTORY
Indicates the working directory.

See Also:
Constant Field Values

HOST_COUNT

public static final String HOST_COUNT
Indicates the number of hosts to distribute on.

See Also:
Constant Field Values

TIME_MAX

public static final String TIME_MAX
Indicates the maximum walltime or cputime for a single execution of the executable. The units is in minutes.

See Also:
Constant Field Values

WALLTIME_MAX

public static final String WALLTIME_MAX
Indicates the maximum walltime for a single execution of the executable. The units is in minutes.

See Also:
Constant Field Values

CPUTIME_MAX

public static final String CPUTIME_MAX
Indicates the maximum cputime for a single execution of the executable. The units is in minutes.

See Also:
Constant Field Values

JOB_TYPE

public static final String JOB_TYPE
Indicates the job type: single|multiple|mpi|condor|...

See Also:
Constant Field Values

JOB_QUEUE

public static final String JOB_QUEUE
Indicates a job queue: FORK, SGE, PBS, ...

See Also:
Constant Field Values

PROJECT

public static final String PROJECT
Indicates the project to use, for accounting purposes.

See Also:
Constant Field Values

DRY_RUN

public static final String DRY_RUN
If set, don't submit but return success.

See Also:
Constant Field Values

MEMORY_MIN

public static final String MEMORY_MIN
Indicates the minimal required memory in MB.

See Also:
Constant Field Values

MEMORY_MAX

public static final String MEMORY_MAX
Indicates the minimal required memory in MB.

See Also:
Constant Field Values

SAVE_STATE

public static final String SAVE_STATE
Indicates that the job data must be kept persistent for restart.

See Also:
Constant Field Values

RESTART

public static final String RESTART
Indicates the job id of a to-be-restarted job.

See Also:
Constant Field Values

STOP_ON_EXIT

public static final String STOP_ON_EXIT
Boolean attribute that indicates if the job needs to be terminated when GAT exits. Default is true.

See Also:
Constant Field Values

SANDBOX_ROOT

public static final String SANDBOX_ROOT
When set, defines a path to the root where sandbox directories are created. Default is adaptor-dependent.

See Also:
Constant Field Values

SANDBOX_USEROOT

public static final String SANDBOX_USEROOT
Boolean attribute that indicates that the directory specified with the SANDBOX_ROOT attribute should itself be used as a sandbox (instead of creating the sandbox in this directory).

See Also:
Constant Field Values

SANDBOX_DELETE

public static final String SANDBOX_DELETE
Boolean attribute that indicates if the sandbox is to be deleted after the run. Default is true.

See Also:
Constant Field Values

SANDBOX_PRESTAGE_STDIN

public static final String SANDBOX_PRESTAGE_STDIN
Boolean attribute that indicates if the stdin file should be prestaged before the job is submitted. The default is adaptor-dependent.

See Also:
Constant Field Values

SANDBOX_POSTSTAGE_STDOUT

public static final String SANDBOX_POSTSTAGE_STDOUT
Boolean attribute that indicates if the stdout file should be poststaged when the job is finished. The default is adaptor-dependent.

See Also:
Constant Field Values

SANDBOX_POSTSTAGE_STDERR

public static final String SANDBOX_POSTSTAGE_STDERR
Boolean attribute that indicates if the stderr file should be poststaged when the job is finished. The default is adaptor-dependent.

See Also:
Constant Field Values
Constructor Detail

SoftwareDescription

public SoftwareDescription()
Create a SoftwareDescription, which describes the application you want to run.


SoftwareDescription

public SoftwareDescription(String jsdlString)
To be implemented.

Parameters:
jsdlString -

SoftwareDescription

public SoftwareDescription(Map<String,Object> attributes)
Create a SoftwareDescription, which describes the application you want to run.

Parameters:
attributes - See the comment above for a list of known attributes.
Method Detail

equals

public boolean equals(Object o)
Tests this SoftwareDescription for equality with the passed Object. SoftwareDescriptions are equal if they have equivalent entries in the description table.

Overrides:
equals in class Object
See Also:
Object.equals(java.lang.Object)

hashCode

public int hashCode()
Returns the hashcode of this SoftwareDescription

Overrides:
hashCode in class Object
Returns:
the hashcode of this SoftwareDescription
See Also:
Object.hashCode()

getArguments

public String[] getArguments()
Returns the arguments of the executable. For the following commandline "/bin/cat hello world > out" it will return a String[]{"hello", "world", ">", "out"}

Returns:
Returns the commandline arguments.

setArguments

public void setArguments(String... arguments)
Sets the arguments of the executable. For the following commandline "/bin/cat hello world" the String[]{"hello", "world"} contains the arguments.

Parameters:
arguments - The commandline arguments to set.

getAttributes

public Map<String,Object> getAttributes()
Gets the attributes of this SoftwareDescription. This method converts the well known attributes as listed in the table of SoftwareDescription to their specific type (which means that if an value can be a String or an Integer, it's cast to the non String type).

Returns:
the attributes.

setAttributes

public void setAttributes(Map<String,Object> attributes)
Set the attributes to the attributes specified in the Map. This will create a set of attributes only containing the attributes from the Map. Use addAttribute to add attributes to an existing set of attributes.

Parameters:
attributes - The attributes to set. See the comment above for a list of known attributes. Note that some adaptors may also support other attributes.

addAttribute

public void addAttribute(String key,
                         Object value)
Add an attribute to the existing attribute set. See the comment above for a list of known attributes. Note that some adaptors may also support other attributes.

Parameters:
key - the key of the attribute
value - the value of the attribute

removeAttribute

public Object removeAttribute(String key)
Remove an attribute from the attribute set.

Parameters:
key - the key of the attribute
Returns:
the value belonging to this key

getEnvironment

public Map<String,Object> getEnvironment()
Returns the environment of the executable. The environment of the executable consists of a Map of environment variables with their values (for instance the key, value pair "JAVA_HOME", "/path/to/java").

Returns:
the environment

setEnvironment

public void setEnvironment(Map<String,Object> environment)
Sets the environment of the executable. The environment of the executable consists of a Map of environment variables with their values (for instance the key, value pair "JAVA_HOME", "/path/to/java").

Parameters:
environment - The environment to set.

getExecutable

public String getExecutable()
Returns the path to the executable. For the following commandline "/bin/cat hello world > out" it will return a String "/bin/cat".

Returns:
the path to the executable.

setExecutable

public void setExecutable(String executable)
Sets the path to the executable. For the following commandline "/bin/cat hello world > out" the String "/bin/cat" should be provided.

Parameters:
executable - The path to the executable.

getPreStaged

public Map<File,File> getPreStaged()
Returns the pre staged file set. This a Map with the source Files as keys and the destination Files as values. This method returns the files that should be pre staged regardless of whether they are already pre staged or not.

Returns:
the pre staged file set.

setPreStaged

public void setPreStaged(File... files)
Sets the pre staged file set. Any former pre staged files added to the pre staged file set are no longer part of the pre staged file set. More Files can be added using the addPreStagedFile methods. See these methods for a table stating at which locations the Files will end up after the pre staging.

Parameters:
files - An array of files that should be pre staged.

addPreStagedFile

public void addPreStagedFile(File src)
Add a single pre stage file. This is similar to addPreStagedFile(src, null).

Parameters:
src - the file that should be pre staged.

addPreStagedFile

public void addPreStagedFile(File src,
                             File dest)
Add a single pre stage file that should be pre staged to the given destination. The table below shows where the pre stage files will end up after pre staging.

where do the pre staged files end up
source file destination file location after pre staging
path/to/file null sandbox/file
path/to/file other/path/to/file sandbox/other/path/to/file
path/to/file /other/path/to/file /other/path/to/file
/path/to/file null sandbox/file
/path/to/file other/path/to/file sandbox/other/path/to/file
/path/to/file /other/path/to/file /other/path/to/file

Parameters:
src - the File that should be pre staged (may not be null)
dest - the File that should exist after the pre staging (may be null, see table).

getPostStaged

public Map<File,File> getPostStaged()
Returns the post stage file set. The key Files are the source files on the execution site, the values are the Files with the destination of the post staging. This method returns the files that should be post staged regardless of whether they are already post staged or not.

Returns:
the post stage file set

setPostStaged

public void setPostStaged(File... files)
Sets the post staged file set. Any former post staged files added to the post staged file set are no longer part of the post staged file set. More Files can be added using the addPostStagedFile methods. See these methods for a table stating at which locations the Files will end up after the post staging.

Parameters:
files - An array of files that should be pre staged.

addPostStagedFile

public void addPostStagedFile(File src)
Add a single post stage file. This is similar to addPostStagedFile(src, null).

Parameters:
src - the file that should be post staged.

addPostStagedFile

public void addPostStagedFile(File src,
                              File dest)
Add a single post stage file that should be post staged to the given destination. The table below shows where the post stage files will end up after post staging.

where do the post staged files end up
source file destination file location after post staging
path/to/file null cwd/file
path/to/file other/path/to/file cwd/other/path/to/file
path/to/file /other/path/to/file /other/path/to/file
/path/to/file null cwd/file
/path/to/file other/path/to/file cwd/other/path/to/file
/path/to/file /other/path/to/file /other/path/to/file

Parameters:
src - the File that should be post staged (may not be null)
dest - the File that should exist after the post staging (may be null, see table).

getDeletedFiles

public List<File> getDeletedFiles()
Returns a List of the Files that should be deleted after the run.

Returns:
the list of files to be deleted after the run. elements are of type File.

addDeletedFile

public void addDeletedFile(File file)
Adds a File to the set of Files that should be deleted after the run. Normally the ResourceBroker will delete the sandbox with all its contents after the run and it isn't necessary to specify Files using this method to be deleted. However, there are two cases where this method will be applicable.

First of all, Files outside the sandbox are not automatically deleted by the ResourceBroker. Those Files should be explicitly added to be deleted using this method.

Second, it's possible to specify that sandbox isn't deleted after the job run, using the attribute SANDBOX_DELETE set to "false". In the case that sandbox isn't deleted but some files inside the sandbox should be deleted, use this method.

Parameters:
file - the file to be deleted after the run.

getWipedFiles

public List<File> getWipedFiles()
Returns a List of the Files that should be wiped and deleted after the run.

Returns:
the list of files to be deleted after the run. elements are of type File.

addWipedFile

public void addWipedFile(File file)
Adds a File to the set of Files that should be wiped after the run. When a File gets deleted, it's possible that some data that was in the file remains on the disk. To be sure these data is also removed, the wiping of a File consists of first overwriting the File, in order to delete the contents of the File. And then deleting the File, in order to free up the disk space.

Parameters:
file - the file to be wiped (overwritten) and deleted after the run.

getStderr

public File getStderr()
Returns the stderr File.

Returns:
the stderr File

enableStreamingStderr

public void enableStreamingStderr(boolean enabled)
Enable or disable streaming standard error.

Parameters:
enabled - true if streaming standard error should be enabled, false otherwise.

streamingStderrEnabled

public boolean streamingStderrEnabled()
Returns whether streaming standard error is enabled.

Returns:
whether streaming standard error is enabled.

enableStreamingStdout

public void enableStreamingStdout(boolean enabled)
Enable or disable streaming standard output.

Parameters:
enabled - true if streaming standard output should be enabled, false otherwise.

streamingStdoutEnabled

public boolean streamingStdoutEnabled()
Returns whether streaming standard output is enabled.

Returns:
whether streaming standard output is enabled.

enableStreamingStdin

public void enableStreamingStdin(boolean enabled)
Enable or disable streaming standard input.

Parameters:
enabled - true if streaming standard input should be enabled, false otherwise.

streamingStdinEnabled

public boolean streamingStdinEnabled()
Returns whether streaming standard input is enabled.

Returns:
whether streaming standard input is enabled.

setStderr

public void setStderr(File stderr)
Sets the stderr File. Note that stderr will be redirected to either a File or a OutputStream. The last invocation of setStderr() determines whether the destination of the output.

Parameters:
stderr - The File where stderr is redirected to.

getStdin

public File getStdin()
Returns the stdin File.

Returns:
the stdin File.

setStdin

public void setStdin(File stdin)
Sets the File where stdin is redirected from.

Parameters:
stdin - The File where stdin is redirected from.

getStdout

public File getStdout()
Returns the stdout File.

Returns:
the stdout File.

setStdout

public void setStdout(File stdout)
Sets the stdout File. Note that stdout will be redirected to either a File or a OutputStream. The last invocation of setStdout() determines whether the destination of the output.

Parameters:
stdout - The File where stdout is redirected to.

toString

public String toString()
Overrides:
toString in class Object

deletePostStaged

public boolean deletePostStaged()
Returns whether the Files in the post stage file set should be deleted after the post staging.

Returns:
TRUE if post stage files will be deleted, FALSE if they won't be deleted.

setDeletePostStaged

public void setDeletePostStaged(boolean deletePostStaged)
Sets the value which is used to determine whether the Files in the post stage file set should be deleted after the post staging. (TRUE if the post stage files should be deleted, FALSE if they shouldn't be deleted).

Parameters:
deletePostStaged - delete the post stage Files after post staging.

deletePreStaged

public boolean deletePreStaged()
Returns whether the Files in the pre stage file set should be deleted after the post staging.

Returns:
TRUE if pre stage files will be deleted, FALSE if they won't be deleted.

setDeletePreStaged

public void setDeletePreStaged(boolean deletePreStaged)
Sets the value which is used to determine whether the Files in the pre stage file set should be deleted after the post staging. (TRUE if the pre stage files should be deleted, FALSE if they shouldn't be deleted).

Parameters:
deletePreStaged - delete the pre stage Files after post staging.

wipePostStaged

public boolean wipePostStaged()
Returns whether the Files in the post stage file set should be wiped after the post staging.

Returns:
TRUE if post stage files will be wiped, FALSE if they won't be wiped.

setWipePostStaged

public void setWipePostStaged(boolean wipePostStaged)
Sets the value which is used to determine whether the Files in the post stage file set should be wiped after the post staging. (TRUE if the post stage files should be wiped, FALSE if they shouldn't be wiped).

Parameters:
wipePostStaged - wipe the post stage Files after post staging.

wipePreStaged

public boolean wipePreStaged()
Returns whether the Files in the pre stage file set should be wiped after the post staging.

Returns:
TRUE if pre stage files will be wiped, FALSE if they won't be wiped.

setWipePreStaged

public void setWipePreStaged(boolean wipePreStaged)
Sets the value which is used to determine whether the Files in the pre stage file set should be wiped after the post staging. (TRUE if the pre stage files should be wiped, FALSE if they shouldn't be wiped).

Parameters:
wipePreStaged - wipe the pre stage Files after post staging.

getIntAttribute

public int getIntAttribute(String name,
                           int defaultVal)
Returns the int value of an attribute. If no value (or the value null) can be found for the given name, the defaultVal is returned. If there exist a value for the key, but this value cannot be parsed to an int, this method throws an Error.

Parameters:
name - the key of the attribute
defaultVal - the default value
Returns:
the int value of the attribute indicated by the name.

getLongAttribute

public long getLongAttribute(String name,
                             long defaultVal)
Returns the long value of an attribute. If no value (or the value null) can be found for the given name, the defaultVal is returned. If there exist a value for the key, but this value cannot be parsed to a long, this method throws an Error.

Parameters:
name - the key of the attribute
defaultVal - the default value
Returns:
the long value of the attribute indicated by the name.

getStringAttribute

public String getStringAttribute(String name,
                                 String defaultVal)
Returns the String value of an attribute. If no value (or the value null) can be found for the given name, the defaultVal is returned.

Parameters:
name - the key of the attribute
defaultVal - the default value
Returns:
the String value of the attribute indicated by the name.

getObjectAttribute

public Object getObjectAttribute(String name)
Returns the Object value of an attribute. If no value (or the value null) can be found for the given name, null is returned.

Parameters:
name - the key of the attribute
Returns:
the Object value of the attribute indicated by the name.

getBooleanAttribute

public boolean getBooleanAttribute(String name,
                                   boolean defaultVal)
Returns the boolean value of an attribute. If no value (or the value null) can be found for the given name, the defaultVal is returned. If there exist a value for the key, but this value cannot be parsed to a boolean, this method throws an Error.

Parameters:
name - the key of the attribute
defaultVal - the default value
Returns:
the boolean value of the attribute indicated by the name.

toWrapper

public void toWrapper(GATContext context,
                      String wrapperFileName,
                      String exitValueFileName)
               throws GATInvocationException
Do not use this method. This method is for internal use of JavaGAT. The attribute "globus.exitvalue.enable" can be set to "true" to make JavaGAT use the wrapper script.

It creates a wrapper script out of this SoftwareDescription in order to be able to retrieve the exit code of a Globus job, it stores the output value in a file.

Parameters:
context - the GATContext used to create the wrapper file
wrapperFileName - the wrapper file name
exitValueFileName - the file name where the exit value is written to
Throws:
GATInvocationException

clone

public Object clone()
Overrides:
clone in class Object

getJSDL

public String getJSDL()
to be implemented.

Returns:
the JSDL representation of this SoftwareDescription