org.proteios.core
Class Job

java.lang.Object
  org.proteios.core.BasicItem<D>
      org.proteios.core.OwnedItem<JobData>
          org.proteios.core.Job

All Implemented Interfaces:

AccessControlled, Identifiable, Nameable, Ownable, Removable

public class Job
extends OwnedItem<JobData>
implements Nameable, Removable

This class represents the execution of a job. Normally a job is executed by a plugin, but it can also be executed by an external program. To find the type of the job check the getJobType() method. Many of the methods in this class only apply to jobs of one of the types. The following methods can only be used on jobs that are executed by a plugin:

• configure(GuiContext): Starts the configuration sequence of the job
• execute(ProgressReporter, String): Starts executing the job

The following methods can only be used by jobs executed by an external program:

• start(String, String): Tell the core that job has started
• setProgress(int, String): Update the progress status of the job
• doneOk(String): Tell the core that the job finished successfully
• doneError(String): Thell the core that the job finished with an error

Version:

2.0

Author:

Nicklas

Last modified

$Date: 2011-05-26 09:25:59 +0200 (Thu, 26 May 2011) $

Nested Class Summary

static class	Job.ExecutionTime A rough estimate of the execution time of a job.
static class	Job.Status The status of a job.
static class	Job.Type The type of job.

Field Summary

static int	MAX_SERVER_LENGTH The maximum allowed length of the server name.
static int	MAX_STATUS_MESSAGE_LENGTH The maximum allowed length of the status message.
static Item	TYPE The type of item represented by this class.

Fields inherited from interface org.proteios.core.Nameable

MAX_DESCRIPTION_LENGTH, MAX_NAME_LENGTH

Method Summary

boolean	abort() Handles aborted job command.
PluginConfigurationRequest	configure(GuiContext context) Start the configuration sequence for a job.
void	doneAborted(String statusMessage) Register the job as aborted.
void	doneError(String statusMessage) Register the job as completed with an error.
void	doneOk(String statusMessage) Register the job as successfully completed.
PluginExecutionRequest	execute(ProgressReporter progress, String server) Start the execution sequence for a job.
AbortableJobQueueReadOnlyInterface	getAbortableJobQueue() Get the abortable job queue used for the job.
int	getActiveProjectId() The ID of the project that should be made the active project while running this job.
Job	getBlocker()
static Job	getById(DbControl dc, int id) Get a Job item when you know the id.
Date	getCreated() Get the date and time the job was registered in the database.
String	getDescription() Get the description for the item.
Date	getEnded() Get the date and time the job ended.
Job.ExecutionTime	getEstimatedExecutionTime() Get the estimated execution time of the job.
Job.Type	getJobType() Get the type of job, ie. if it is a job executed by a plugin or not.
String	getName() Get the name of the item.
Set<String>	getParameterNames() Get the names of all parameters for the job.
List<?>	getParameterValues(String name) Get the values of a named parameter.
int	getPercentComplete() An estimate of the percentage of the work currently completed by an executing job.
PluginConfiguration	getPluginConfiguration() Get the PluginConfiguration defining the plugin this job should execute.
PluginDefinition	getPluginDefinition() Get the PluginConfiguration defining the plugin this job should execute.
PluginExecutionRequest	getPluginExecutionRequest() Get the PluginExecutionRequest for the job.
int	getPriority() Get the priority of the job.
static ItemQuery<Job>	getQuery() Get a query configured to retrieve
String	getServer() Get the name of the server where the job is executing.
Date	getStarted() Get the date and time the job was started.
Job.Status	getStatus() Get the status of the job.
String	getStatusMessage() Get a message about the current status of the job.
Thread	getThread() Get the Thread for the job.
Item	getType() Get the type of item represented by the object.
boolean	isRemoved() Check if the removed flag is set for this item.
boolean	isUsed() Return TRUE if the status is EXECUTING, FALSE otherwise.
boolean	jobCommandAborted() Check if the job command is aborted.
void	removeAbortedJobId(int jobId) Remove job id from the aborted job id list.
void	setBlocker(Job blocker)
void	setDescription(String description) Set the description for the item.
void	setEstimatedExecutionTime(Job.ExecutionTime executionTime) Set the estimated execution time of the job.
void	setName(String name) Set the name of the item.
void	setParameterValue(String name, ParameterType<?> parameterType, Object value) Set the value of a configuration parameter.
void	setParameterValues(String name, ParameterType<?> parameterType, List<?> values) Set the value of a configuration parameter.
void	setPriority(int priority) Set the priority of the job.
void	setProgress(int percentComplete, String statusMessage) Set the progress of the job.
void	setRemoved(boolean removed) Set the removed flag for this item.
void	start(String statusMessage, String server) Register the job as started.

Methods inherited from class org.proteios.core.OwnedItem

getOwner, setOwner

Methods inherited from class org.proteios.core.BasicItem

checkPermission, equals, getDbControl, getId, getPermissions, getSessionControl, getVersion, hashCode, hasPermission, isDetached, isInDatabase, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.proteios.core.Identifiable

getId, getVersion

Methods inherited from interface org.proteios.core.AccessControlled

checkPermission, hasPermission

Field Detail

TYPE

public static final Item TYPE

The type of item represented by this class.

See Also:

Item.JOB, getType()

MAX_STATUS_MESSAGE_LENGTH

public static final int MAX_STATUS_MESSAGE_LENGTH

The maximum allowed length of the status message.

See Also:

Constant Field Values

MAX_SERVER_LENGTH

public static final int MAX_SERVER_LENGTH

The maximum allowed length of the server name.

See Also:

Constant Field Values

Method Detail

getById

public static Job getById(DbControl dc,
                          int id)
                   throws ItemNotFoundException,
                          PermissionDeniedException,
                          BaseException

Get a Job item when you know the id.

Parameters:

dc - The DbControl which will be used for permission checking and database access.

id - The id of the item to load

Returns:

The Job item

Throws:

ItemNotFoundException - If an item with the specified id is not found

PermissionDeniedException - If the logged in user doesn't have read permission to the item

BaseException - If there is another error

getQuery

public static ItemQuery<Job> getQuery()

Get a query configured to retrieve

Returns:

An ItemQuery object

getAbortableJobQueue

public AbortableJobQueueReadOnlyInterface getAbortableJobQueue()

Get the abortable job queue used for the job.

Returns:

AbortableJobQueueReadOnlyInterface The abortable job queue used for the job.

getPluginExecutionRequest

public PluginExecutionRequest getPluginExecutionRequest()

Get the PluginExecutionRequest for the job.

Returns:

PluginExecutionRequest The PluginExecutionRequest used for the job.

getThread

public Thread getThread()

Get the Thread for the job. Returns null if the job is not executing.

Returns:

Thread The thread the job is running in.

getType

public Item getType()

Description copied from interface: Identifiable

Get the type of item represented by the object. The returned value is one of the values defined in the Item enumeration.

Specified by:

getType in interface Identifiable

Returns:

A value indicating the type of item

getName

public String getName()

Description copied from interface: Nameable

Get the name of the item.

Specified by:

getName in interface Nameable

Returns:

A String with the name of the item

setName

public void setName(String name)
             throws PermissionDeniedException,
                    InvalidDataException

Description copied from interface: Nameable

Set the name of the item. The name cannot be null and mustn't be longer than the value specified by the Nameable.MAX_NAME_LENGTH constant.

Specified by:

setName in interface Nameable

Parameters:

name - The new name for the item

Throws:

PermissionDeniedException - If the logged in user doesn't have write permission

InvalidDataException - If the name is null or longer than specified by the Nameable.MAX_NAME_LENGTH constant

getDescription

public String getDescription()

Description copied from interface: Nameable

Get the description for the item.

Specified by:

getDescription in interface Nameable

Returns:

A String with a description of the item

setDescription

public void setDescription(String description)
                    throws PermissionDeniedException,
                           InvalidDataException

Description copied from interface: Nameable

Set the description for the item. The description can be null but mustn't be longer than the value specified by the Nameable.MAX_DESCRIPTION_LENGTH constant.

Specified by:

setDescription in interface Nameable

Parameters:

description - The new description for the item

Throws:

PermissionDeniedException - If the logged in user doesn't have write permission

InvalidDataException - If the description longer than specified by the Nameable.MAX_DESCRIPTION_LENGTH constant

isRemoved

public boolean isRemoved()

Description copied from interface: Removable

Check if the removed flag is set for this item.

Specified by:

isRemoved in interface Removable

Returns:

TRUE if the item is flagged as removed, FALSE otherwise

setRemoved

public void setRemoved(boolean removed)
                throws PermissionDeniedException

Description copied from interface: Removable

Set the removed flag for this item.

Specified by:

setRemoved in interface Removable

Parameters:

removed - TRUE if the item should be flagged as removed, FALSE otherwise

Throws:

PermissionDeniedException - If the logged in user doesn't have Permission.DELETE permission for setting the flag to TRUE or Permission.WRITE permission for setting the flag to FALSE

isUsed

public boolean isUsed()
               throws BaseException

Return TRUE if the status is EXECUTING, FALSE otherwise.

Specified by:

isUsed in class BasicItem<JobData>

Returns:

TRUE if this item is used, FALSE otherwise

Throws:

BaseException

getJobType

public Job.Type getJobType()

Get the type of job, ie. if it is a job executed by a plugin or not.

getPluginDefinition

public PluginDefinition getPluginDefinition()
                                     throws PermissionDeniedException,
                                            BaseException

Get the PluginConfiguration defining the plugin this job should execute.

Returns:

The PluginConfiguration item, or null if this job isn't executed by a plugin

Throws:

PermissionDeniedException - If the logged in user doesn't have read permission for the plugin configuration

BaseException - If there is another error

getPluginConfiguration

public PluginConfiguration getPluginConfiguration()
                                           throws PermissionDeniedException,
                                                  BaseException

Get the PluginConfiguration defining the plugin this job should execute.

Returns:

The PluginConfiguration item, or null if this job isn't executed by a plugin

Throws:

PermissionDeniedException - If the logged in user doesn't have read permission for the plugin configuration

BaseException - If there is another error

getEstimatedExecutionTime

public Job.ExecutionTime getEstimatedExecutionTime()

Get the estimated execution time of the job. This value can be used by job queue managers to decide which job that should be executed at when.

Returns:

A ExecutionTime object

setEstimatedExecutionTime

public void setEstimatedExecutionTime(Job.ExecutionTime executionTime)

Set the estimated execution time of the job. This value can be used by job queue managers to decide which job that should be executed at when.

Parameters:

executionTime - ExecutionTime The execution time to set.

getStatus

public Job.Status getStatus()

Get the status of the job.

getStatusMessage

public String getStatusMessage()

Get a message about the current status of the job.

getPercentComplete

public int getPercentComplete()

An estimate of the percentage of the work currently completed by an executing job. The value is always 0 for a job that hasn't started executing, and 100 for a job that has finised (successfully or with an error).

getPriority

public int getPriority()

Get the priority of the job. The priority is a value between 1 and 10, with 1 as the highest priority.

setPriority

public void setPriority(int priority)
                 throws PermissionDeniedException,
                        InvalidDataException

Set the priority of the job. The priority is a value between 1 and 10, with 1 as the highest priority.

Throws:

PermissionDeniedException - If the logged in user doesn't have write permission or the job's status isn't WAITING

InvalidDataException - If the priority isn't between 1 and 10

getActiveProjectId

public int getActiveProjectId()

The ID of the project that should be made the active project while running this job. If the project can't be loaded the job should be executed without an active project.

Returns:

The ID of the active project, or 0 if no project should be active

getCreated

public Date getCreated()

Get the date and time the job was registered in the database.

Returns:

A date

getStarted

public Date getStarted()

Get the date and time the job was started.

Returns:

A date, or null if the job hasn't started

See Also:

start(String, String)

getServer

public String getServer()

Get the name of the server where the job is executing.

getEnded

public Date getEnded()

Get the date and time the job ended.

Returns:

A date, or null if the job hasn't ended

start

public void start(String statusMessage,
                  String server)
           throws PermissionDeniedException,
                  InvalidDataException

Register the job as started. Note! This method doesn't start the actual execution of the job. This method should be called by an job runner application to tell the core that the job runner has started to execute the job. This method can't be used for jobs that are executed by plugins.

Parameters:

statusMessage - A message

server - The name of the server where the job is started

Throws:

PermissionDeniedException - If the logged in user doesn't have write permission

InvalidDataException - If the status message is too long

setProgress

public void setProgress(int percentComplete,
                        String statusMessage)
                 throws PermissionDeniedException,
                        InvalidDataException

Set the progress of the job. The job must be in the Job.Status.EXECUTING status.

Parameters:

percentComplete - The number of percent completed

statusMessage - A message

Throws:

PermissionDeniedException - If the logged in user doesn't have write permission of the job isn't in the EXECUTING status

InvalidDataException - If the status message is too long or the percentage value isn't between 0 and 100

doneOk

public void doneOk(String statusMessage)
            throws PermissionDeniedException,
                   InvalidDataException

Register the job as successfully completed.

Parameters:

statusMessage - A message

Throws:

PermissionDeniedException - If the logged in user doesn't have write permission

InvalidDataException - If the status message is too long

doneError

public void doneError(String statusMessage)
               throws PermissionDeniedException,
                      InvalidDataException

Register the job as completed with an error.

Parameters:

statusMessage - A message

Throws:

PermissionDeniedException - If the logged in user doesn't have write permission

InvalidDataException - If the status message is too long

doneAborted

public void doneAborted(String statusMessage)
                 throws PermissionDeniedException,
                        InvalidDataException

Register the job as aborted.

Parameters:

statusMessage - A message

Throws:

PermissionDeniedException - If the logged in user doesn't have write permission

InvalidDataException - If the status message is too long

configure

public PluginConfigurationRequest configure(GuiContext context)
                                     throws PermissionDeniedException,
                                            BaseException

Start the configuration sequence for a job. Do not call DbControl.commit() until the configuration sequence is done. See PluginRequest for more information. This method changes the status of the job to Job.Status.WAITING.

Returns:

A PluginRequest object

Throws:

PermissionDeniedException - If the logged in user doesn't have write permission

BaseException - If there is another error

execute

public PluginExecutionRequest execute(ProgressReporter progress,
                                      String server)
                               throws PermissionDeniedException,
                                      InvalidDataException,
                                      BaseException

Start the execution sequence for a job. Call DbControl.commit() before calling PluginRequest.invoke().

Parameters:

progress - The ProgressReporter where the plugin can report its progress. If null ProgressReporterImpl is used

server - The name of the server executing the plugin

Returns:

A PluginRequest object

Throws:

PermissionDeniedException - If the logged in user doesn't have write permission or the job isn't in the Job.Status.WAITING status

InvalidDataException - If the server name is too long

BaseException - If there is another error

getParameterNames

public Set<String> getParameterNames()

Get the names of all parameters for the job.

Returns:

A Set containing the names of the parameters or an empty set if no parameters has been defined

getParameterValues

public List<?> getParameterValues(String name)
                           throws PermissionDeniedException,
                                  BaseException

Get the values of a named parameter.

Parameters:

name - The name of the parameter

Returns:

A list of objects containing the values, or null if the parameter doesn't exist

Throws:

PermissionDeniedException - If the parameter contain values that the logged in user doesn't have read permission for

BaseException - If there is another error

setParameterValue

public void setParameterValue(String name,
                              ParameterType<?> parameterType,
                              Object value)
                       throws InvalidDataException,
                              PermissionDeniedException,
                              BaseException

Set the value of a configuration parameter. This method can only be called if the job is executed by an external program, and isn't already executing. This method also sets the status of the job to Job.Status.WAITING.

Parameters:

name - The name of the parameter

parameterType - The type of the parameter

value - The value of the parameter

Throws:

PermissionDeniedException - If the logged in user doesn't have write permission or if the job is executing

InvalidDataException - If name is null or the new value doesn't validate against the parameter type

BaseException - If there is another error

setParameterValues

public void setParameterValues(String name,
                               ParameterType<?> parameterType,
                               List<?> values)
                        throws InvalidDataException,
                               PermissionDeniedException,
                               BaseException

Set the value of a configuration parameter. This method can only be called if the job is executed by an external program, and isn't already executing. This method also sets the status of the job to Job.Status.WAITING.

Parameters:

name - The name of the parameter

parameterType - The type of the parameter

values - A list containing the values

Throws:

PermissionDeniedException - If the logged in user doesn't have write permission or if the job is executing

InvalidDataException - If name is null or the new value doesn't validate against the parameter type

BaseException - If there is another error

getBlocker

public Job getBlocker()

setBlocker

public void setBlocker(Job blocker)

abort

public boolean abort()
              throws PermissionDeniedException

Handles aborted job command. Job with status WAITING is set to status ABORTED. Job with status EXECUTING where the plugin implements AbortablePluginInterface is set to status ABORTING, while other executing jobs are left unchanged.

Returns:

True if the job command could be aborted, else false;

Throws:

PermissionDeniedException - If the logged in user doesn't have write permission.

removeAbortedJobId

public void removeAbortedJobId(int jobId)

Remove job id from the aborted job id list.

Parameters:

jobId - int The job id to remove from the aborted job id list.

jobCommandAborted

public boolean jobCommandAborted()

Check if the job command is aborted.