org.soaplab.services
Interface Job

All Known Implementing Classes:

AbstractJob, CmdLineJob

public interface Job

An interface defining a job. A job represents an invocation of an analysis tool. The invocation can be synchronous (blocking) or asynchronous. The invocation itself was historically meant to be an execution of an analysis tool but actually it can also mean fetching contents of a remote web site and returning its (parsed) contents as a result of such "invocation", or other things (access to database, or whatever).

Version:

$Id: Job.java,v 1.9 2008/08/21 20:59:24 marsenger Exp $

Author:

Martin Senger

Method Summary

void	destroy() Destroy resources related to this job.
long	getCreated() Job created - returns number of seconds from the BOE.
long	getElapsed() Job time elapsed - returns number in milliseconds.
long	getEnded() Job ended - returns number of seconds from the BOE.
java.lang.String	getId() Get this job ID.
java.io.File	getJobDir() Create (unless it already exists) and return a new directory which will become a working directory for this job.
java.lang.String	getLastEvent() Get the last event.
MetadataAccessor	getMetadataAccessor() Get metadata accessor.
Reporter	getReporter() Get reporter.
java.util.Map<java.lang.String,java.lang.Object>	getResults() Return all (available) results.
java.util.Map<java.lang.String,java.lang.Object>	getResults(java.lang.String[] resultNames) Return all wanted (and available) results.
java.util.Map<java.lang.String,java.lang.String>[]	getResultsInfo()
long	getStarted() Job started - returns number of seconds from the BOE.
java.lang.String	getStatus() Get job status.
boolean	isDataReferenceSafe(java.lang.String dataRef, ParamDef paramDef) Check if the 'dataRef' (which is a file name or a URL) is safe for this job.
boolean	isRecreated() Checks if the job is re-created
void	run() Run it.
void	setId(java.lang.String jobId) Set this job ID.
void	setInputs(java.util.Map<java.lang.String,java.lang.Object> inputs) Set input data into this job.
void	setInputValue(java.lang.String inputName, java.lang.Object value) Set one input value.
void	setMetadataAccessor(MetadataAccessor metadataAccessor) Set metadata accessor.
void	setReporter(Reporter reporter) Set reporter.
void	setSharedAttributes(java.util.Map<java.lang.String,java.lang.Object> sharedAttributes) Shared attributes are any objects that are shared by more job instances.
void	terminate() Terminate this running job.
void	waitFor() Block and wait for completion.

Method Detail

getId

java.lang.String getId()

Get this job ID.

setId

void setId(java.lang.String jobId)

Set this job ID.

getReporter

Reporter getReporter()

Get reporter.

setReporter

void setReporter(Reporter reporter)

Set reporter.

getMetadataAccessor

MetadataAccessor getMetadataAccessor()

Get metadata accessor.

setMetadataAccessor

void setMetadataAccessor(MetadataAccessor metadataAccessor)

Set metadata accessor.

setInputs

void setInputs(java.util.Map<java.lang.String,java.lang.Object> inputs)
               throws SoaplabException

Set input data into this job.

Throws:

SoaplabException

setInputValue

void setInputValue(java.lang.String inputName,
                   java.lang.Object value)
                   throws SoaplabException

Set one input value. This is allowed only if this job was created initially with empty input set (in other words it is not allowed to add new inputs into already created one unless it was created empty).

Throws:

SoaplabException

run

void run()
         throws SoaplabException

Run it.

Throws:

SoaplabException

waitFor

void waitFor()
             throws SoaplabException

Block and wait for completion.

Throws:

SoaplabException

terminate

void terminate()
               throws SoaplabException

Terminate this running job.

Throws:

SoaplabException

getCreated

long getCreated()
                throws SoaplabException

Job created - returns number of seconds from the BOE.

Throws:

SoaplabException

getStarted

long getStarted()
                throws SoaplabException

Job started - returns number of seconds from the BOE.

Throws:

SoaplabException

getEnded

long getEnded()
              throws SoaplabException

Job ended - returns number of seconds from the BOE.

Throws:

SoaplabException

getElapsed

long getElapsed()
                throws SoaplabException

Job time elapsed - returns number in milliseconds. The implementation may choose to return a correct value of the elapsed time only after the job has been finished.

Throws:

SoaplabException

getStatus

java.lang.String getStatus()
                           throws SoaplabException

Get job status.

Throws:

SoaplabException

getLastEvent

java.lang.String getLastEvent()
                              throws SoaplabException

Get the last event.

Throws:

SoaplabException

getResults

java.util.Map<java.lang.String,java.lang.Object> getResults()
                                                            throws SoaplabException

Return all (available) results.

Throws:

SoaplabException

getResults

java.util.Map<java.lang.String,java.lang.Object> getResults(java.lang.String[] resultNames)
                                                            throws SoaplabException

Return all wanted (and available) results.

Throws:

SoaplabException

getResultsInfo

java.util.Map<java.lang.String,java.lang.String>[] getResultsInfo()
                                                                  throws SoaplabException

Throws:

SoaplabException

destroy

void destroy()

Destroy resources related to this job.

setSharedAttributes

void setSharedAttributes(java.util.Map<java.lang.String,java.lang.Object> sharedAttributes)

Shared attributes are any objects that are shared by more job instances. Usually, one service keeps this container and gives it to its jobs. It depends on jobs what they store here.

isDataReferenceSafe

boolean isDataReferenceSafe(java.lang.String dataRef,
                            ParamDef paramDef)

Check if the 'dataRef' (which is a file name or a URL) is safe for this job. It is a security measure not to allow users to explore server's file system (too much).

Parameters:

dataRef - is a data reference (file name, URL) to be checked

paramDef - is a metadata definition of the input parameter whose data reference is being checked; an implementation can use it, for example, if inputs have different policy what is safe and what not (but this AbstractJob class does not use it)

Returns:

true if the data reference is considered safe to use

isRecreated

boolean isRecreated()

Checks if the job is re-created

Returns:

true if the job was re-created

getJobDir

java.io.File getJobDir()
                       throws SoaplabException

Create (unless it already exists) and return a new directory which will become a working directory for this job.

Returns:

a File instance representing a directory

Throws:

SoaplabException - if the directory creation failed