org.gridlab.gat.resources
Class SoftwareDescription

java.lang.Object
  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