org.soaplab.services.cmdline
Interface Parameter

public interface Parameter

An interface defining a paramter of a Soaplab2 job, usualy a command-line parameter. Once given input data and a reference to a particular job, the instances implementing this interface are able to produce command-line arguments (by methods createArg and createNamedArg), environment variables (by method createEnv) and IO elements (by method createIO) with this input data, wrapped/created as defined by service metadata. Usually, however, only some of these methods return non-empty results (for example, a single parameter is usually either used as a command-line argument, or as an environment variable, but rarely as both in the same time).

There is a strong recommendation to implement this interface as a sub-class of org.soaplab.services.cmdline.BaseParameter. Or, at least, to include the same constructor:

 public YourParameter (ParamDef paramDef)
 

Version:

$Id: Parameter.java,v 1.10 2007/10/22 17:56:18 marsenger Exp $

Author:

Martin Senger

Method Summary

java.lang.String[]	createArg(java.util.Map<java.lang.String,java.lang.Object> inputs, Job job) Return an array that can be directly used on the command-line.
java.util.Properties	createEnv(java.util.Map<java.lang.String,java.lang.Object> inputs, Job job) Return properties that represent an "environment" of the analysis that is going to be started.
org.soaplab.services.IOData[]	createIO(java.util.Map<java.lang.String,java.lang.Object> inputs, Job job) Create an array of data containers that kept (usually local) data whose references are mentioned on the command-line - for that see method createArg(java.util.Map, org.soaplab.services.Job), or are not mentioned anywhere (e.g.
NamedValues	createNamedArg(java.util.Map<java.lang.String,java.lang.Object> inputs, Job job) Return a structure similar to the arguments for a command-line (as returned by createArg) but slightly more general.
ParamDef	getDefinition() Return a definition of this parameter.
void	validate(java.util.Map<java.lang.String,java.lang.Object> inputs, Job job, java.lang.Object testedValue) Verify value (or values, if they are repetitive) of this parameter.

Method Detail

getDefinition

ParamDef getDefinition()

Return a definition of this parameter.

createArg

java.lang.String[] createArg(java.util.Map<java.lang.String,java.lang.Object> inputs,
                             Job job)
                             throws org.soaplab.services.cmdline.ParameterException

Return an array that can be directly used on the command-line.

Parameters:

inputs - are the end-user's input data (which will become parts of the returned command-line arguments). It may contain more data than just for this parameter.

job - whose arguments are being created

Returns:

command-line arguments, separated as they should be on the analysis's command-line; the returned value may be empty, but not null

Throws:

ParameterException - if there are not-valid (or missing) data for this parameter in the given 'inputs'

createEnv

java.util.Properties createEnv(java.util.Map<java.lang.String,java.lang.Object> inputs,
                               Job job)
                               throws org.soaplab.services.cmdline.ParameterException

Return properties that represent an "environment" of the analysis that is going to be started. These properties are (usually) taken from those parameters that have defined an option "envar" in their metadata.

The property keys are usually not prefixed by the '-' character (as often are the command-line arguments).

It is left to the 'user' of the parameters (which is, for example, a class implementing the Job interface) how to use the returned value. Obvious choice is to use it for setting environment variables. But some classes may use it to set Java System proprties instead, etc.

Parameters:

inputs - are the end-user's input data (which will become parts of the returned environment). It may contain more data than just for this parameter.

job - whose environment variables are being created

Returns:

properties that will used as environment variables, or Java properties, or otherwise (it depends on implementation); the returned value may be empty, but not null

Throws:

ParameterException - if there are not-valid (or missing) data for this parameter in the given 'inputs'

createIO

org.soaplab.services.IOData[] createIO(java.util.Map<java.lang.String,java.lang.Object> inputs,
                                       Job job)
                                       throws org.soaplab.services.cmdline.ParameterException

Create an array of data containers that kept (usually local) data whose references are mentioned on the command-line - for that see method createArg(java.util.Map, org.soaplab.services.Job), or are not mentioned anywhere (e.g. data given to an analysis tool on its standard input).

For example, if an analysis tool expects an input file name on its command-line (let's say prefixed by the -infile), the createArg(java.util.Map, org.soaplab.services.Job) method would return this command-line: *

-infile 12avd5467dfh-tmp

and this method would return a data container that makes sure that the input data are stored in the local file 12avd5467dfh-tmp.

Parameters:

inputs - are the end-user's input data (which will become parts of the returned containers). It may contain more data than just for this parameter.

job - whose data containers are being created

Returns:

data containers; the returned value may be empty, but not null

Throws:

ParameterException - if there are not-valid (or missing) data for this parameter in the given 'inputs', or if there were IO problems when localizing 'inputs'

validate

void validate(java.util.Map<java.lang.String,java.lang.Object> inputs,
              Job job,
              java.lang.Object testedValue)
              throws org.soaplab.services.cmdline.ParameterException

Verify value (or values, if they are repetitive) of this parameter. It is recommended to start validation by calling super.validate(...) first.

Parameters:

inputs - are the end-user's input data - they are passed here all of them because they might be needed for some inter-parameters value validation

job - whose input is being validated

testedValue - is the value that should be validated. A value with the same name often appears also in 'inputs' (sent by a user) - but if not than it indicates that the 'testedValue' is a default value taken from the metadata definition (which may have some impact on the validation procedure). It may be also null - in which case try to find it first in the 'inputs'.

Throws:

ParameterException - is validation failed

createNamedArg

NamedValues createNamedArg(java.util.Map<java.lang.String,java.lang.Object> inputs,
                           Job job)
                           throws org.soaplab.services.cmdline.ParameterException

Return a structure similar to the arguments for a command-line (as returned by createArg) but slightly more general. It can be used for jobs that do not create command lines but still need to get user data in a structured way. A typical example are Gowlab jobs. More details are in the class NamedValues.

Parameters:

inputs - are the end-user's input data (which will become parts of the returned structure). It may contain more data than just for this parameter.

job - whose arguments are being created

Returns:

a list of user values, labelled by this parameter ID and possibly by a tag (qualifier); the returned value may be empty, but not null

Throws:

ParameterException - if there are not-valid (or missing) data for this parameter in the given 'inputs'