net.sf.basedb.core
Class Job

java.lang.Object
  net.sf.basedb.core.BasicItem<D>
      net.sf.basedb.core.OwnedItem<JobData>
          net.sf.basedb.core.Job

All Implemented Interfaces:

AccessControlled, Controlled, Identifiable, Nameable, Ownable, Removable, Transactional

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

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: 2010-10-28 08:20:24 +0200 (Thu, 28 Oct 2010) $

Nested Class Summary

static class	Job.ExecutionTime A rough estimate of the execution time of a job.
private class	Job.JobSignalTransporter Wrapper for the signal transporter that intercepts the ABORT signal and changes the job's status to ABORTING.
(package private) static class	Job.ProgressReporterImpl Implements the ProgressReporter interface and stores the percentage completed for the current job.
static class	Job.Status The status of a job.
static class	Job.Type The type of job.

Nested classes/interfaces inherited from interface net.sf.basedb.core.Transactional

Transactional.Action

Field Summary

static int	MAX_SERVER_LENGTH The maximum allowed length of the server name.
static int	MAX_STACK_TRACE_LENGTH The maximum allowed length of the stack trace message.
static int	MAX_STATUS_MESSAGE_LENGTH The maximum allowed length of the status message.
private Job.JobSignalTransporter	signalTransporter
static Item	TYPE The type of item represented by this class.

Fields inherited from interface net.sf.basedb.core.Nameable

MAX_DESCRIPTION_LENGTH, MAX_NAME_LENGTH

Constructor Summary

Job(JobData jobData)

Method Summary

PluginConfigurationRequest	configure(GuiContext context) Start the configuration sequence for a job.
(package private) void	continueLater(String executeCommand, boolean isShuttingDown) This method is used to indicate that a job had to be aborted due to a system shutdown.
void	copyParametersFrom(Job copyFrom) Copy all parameter values from another job.
void	doneError(String statusMessage) Register the job as completed with an error.
void	doneError(String statusMessage, Collection<? extends Throwable> errors) 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.
PluginExecutionRequest	execute(ProgressReporter progress, String server, JobAgentSettings settings) Start the execution sequence for a job.
int	getActiveProjectId() The ID of the project that should be made the active project while running this job.
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.
Experiment	getExperiment() Get the experiment this job is a part of.
JobAgent	getJobAgent() Get the job agent this job should run on, is running on or was running on.
Job.Type	getJobType() Get the type of job, ie. if it is a job executed by a plugin or not.
GuiContext	getLastGuiContext() Get the gui-context that was active when this job was created.
String	getName() Get the name of the item.
static Job	getNew(DbControl dc, PluginDefinition plugin, PluginConfiguration config) Deprecated. Use getNew(DbControl, PluginDefinition, PluginConfiguration, Experiment) instead
static Job	getNew(DbControl dc, PluginDefinition plugin, PluginConfiguration config, Experiment experiment) Create a new Job item.
ParameterInfo	getParameterInfo(String name) Get extra information about a parameter.
Set<String>	getParameterNames() Get the names of all parameters for the job.
Object	getParameterValue(String name) Get the value of a named parameter.
List<?>	getParameterValues(String name) Get the values of a named parameter.
(package private) ParameterValuesImpl	getParameterValuesImpl() Get a write-protected ParameterValuesImpl object.
int	getParameterVersion() Get the version number of the configuration parameters used for this job.
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.
String	getPluginVersion() Get the version of the plugin used to execute this job at the time the job was executed or registered.
int	getPriority() Get the priority of the job.
ProgressReporter	getProgressReporter(ProgressReporter chained) Get a progress reporter that reports progress by updating the information in the database.
static ItemQuery<Job>	getQuery() Get a query configured to retrieve
boolean	getRemoveJobWhenFinished() If the job should flagged for deletion after it's done successfully.
Date	getScheduled() Get the date and time the job was scheduled to the job queue.
boolean	getSendMessage() If a message should be sent to the owner once the job has finished or not.
String	getServer() Get the name of the server where the job is executing.
SignalTransporter	getSignalTransporter() Create and initialise a signal transporter object that can be used to send signal to the plug-in running this job.
String	getStackTrace() Get the stack trace in case the job ended with an error
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.
Item	getType() Get the type of item represented by the object.
Set<ItemProxy>	getUsingItems() Get the transformation and raw bioassays using this job.
boolean	hasContext() Checks if this job has saved information about the context that was active when this job was created.
boolean	hasSignalTransporter() Checks if a signal transporter has been registered for this job or not.
(package private) void	initPermissions(int granted, int denied) Grant read permission if the logged in user has read permission to the experiment the job belongs to.
boolean	isDryRun() Check if the job should be/was executed as a dry-run job.
boolean	isRemoved() Check if the removed flag is set for this item.
boolean	isUsed() Return TRUE if the status is EXECUTING or: a transformation is linked to this job a raw bioassay is linked to this job an array design is linked to this job FALSE otherwise.
(package private) void	onAfterCommit(Transactional.Action action) If the Signal.ABORT signal is waiting to be sent send it.
(package private) void	onBeforeCommit(Transactional.Action action) Set's the project id to the currently active project.
void	retry(boolean useLatestConfiguration) Deprecated. Use retry(boolean, boolean) instead
void	retry(boolean useLatestConfiguration, boolean clearDryRun) Retry a job which finished with an error or a successful dry-run job.
private void	sendMessage() Send a message to the owner of the job when the job has finished
void	setDescription(String description) Set the description for the item.
(package private) void	setExperiment(Experiment experiment) Set the experiment this job is part of.
void	setJobAgent(JobAgent agent) Set the job agent this job should run on.
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	setParameterValue(String name, String label, String description, 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	setParameterValues(String name, String label, String description, ParameterType<?> parameterType, List<?> values) Set the value of a configuration parameter.
(package private) void	setParameterValuesInternal(String name, String label, String description, ParameterType<?> parameterType, List<?> values, boolean validate) Set the values of a configuration parameter.
private void	setPluginConfiguration(PluginConfiguration pluginConfiguration) Set the plugin configuration of this job.
private void	setPluginDefinition(PluginDefinition plugin) Set the plugin configuration of this job.
void	setPrepared(String server) Deprecated. Use setPrepared(String, JobAgent) instead
void	setPrepared(String server, JobAgent agent) Set the job's status to Job.Status.PREPARED.
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	setRemoveJobWhenFinished(boolean removeJobWhenFinished) Set if the job should be deleted after it has finished successfully.
void	setSendMessage(boolean sendMessage) Set if a message should be sent to owner when the job finishes.
void	setSignalTransporter(Class<? extends SignalTransporter> clazz, String initParams) Set information needed to create a signal transporter object that can be used to send signals to the plug-in that is currently executing this job.
void	start(String statusMessage, String server) Deprecated. Use start(String, String, JobAgent) instead
void	start(String statusMessage, String server, JobAgent agent) Register the job as started.

Methods inherited from class net.sf.basedb.core.OwnedItem

getOwner, isOwner, setOwner, takeOwnership, toTransferable

Methods inherited from class net.sf.basedb.core.BasicItem

addUsingItems, addUsingItems, checkPermission, equals, getData, getDbControl, getId, getPermissions, getPluginPermissions, getSessionControl, getVersion, hashCode, hasPermission, isDetached, isInDatabase, onAfterInsert, onRollback, setDbControl, setProjectDefaults, toString, toTransferable, validate

Methods inherited from class java.lang.Object

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

Methods inherited from interface net.sf.basedb.core.Identifiable

getId, getVersion

Methods inherited from interface net.sf.basedb.core.AccessControlled

checkPermission, getPermissions, hasPermission

Field Detail

TYPE

public static final Item TYPE

The type of item represented by this class.

See Also:

Item.JOB, getType()

signalTransporter

private Job.JobSignalTransporter signalTransporter

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_STACK_TRACE_LENGTH

public static final int MAX_STACK_TRACE_LENGTH

The maximum allowed length of the stack trace 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

Constructor Detail

Job

Job(JobData jobData)

Method Detail

getNew

public static Job getNew(DbControl dc,
                         PluginDefinition plugin,
                         PluginConfiguration config)
                  throws InvalidDataException,
                         BaseException

Deprecated. Use getNew(DbControl, PluginDefinition, PluginConfiguration, Experiment) instead

Create a new job.

Throws:

InvalidDataException

BaseException

getNew

public static Job getNew(DbControl dc,
                         PluginDefinition plugin,
                         PluginConfiguration config,
                         Experiment experiment)
                  throws InvalidDataException,
                         BaseException

Create a new Job item.

Parameters:

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

plugin - The plugin this job should use.

config - The plugin configuration this job should use or null if the job is executed by an external program

experiment - The experiment the job is a part of, or null if the job is not part of an experiment

Returns:

The new Job item

Throws:

InvalidDataException - If the specified plugin requires a configuration but the config parameter is null

BaseException - If there is an error

Since:

2.7

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

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 or:

• a transformation is linked to this job
• a raw bioassay is linked to this job
• an array design is linked to this job

FALSE otherwise.

Overrides:

isUsed in class BasicItem<JobData>

Returns:

TRUE if this item is used, FALSE otherwise

Throws:

BaseException - If not able to tell if item is used or not.

See Also:

BasicItem.getUsingItems()

getUsingItems

public Set<ItemProxy> getUsingItems()

Get the transformation and raw bioassays using this job.

Overrides:

getUsingItems in class BasicItem<JobData>

Returns:

A set containing proxies for the items, or an empty set if no items are using this item

Since:

2.2

See Also:

BasicItem.addUsingItems(Set, Item, org.hibernate.Query)

onBeforeCommit

void onBeforeCommit(Transactional.Action action)
              throws NotLoggedInException,
                     BaseException

Set's the project id to the currently active project.

Overrides:

onBeforeCommit in class OwnedItem<JobData>

Throws:

NotLoggedInException - If no user is logged in

BaseException - If there is another error

See Also:

Transactional, Core API overview - Transaction handling, Coding rules and guidelines for item classes

onAfterCommit

void onAfterCommit(Transactional.Action action)

If the Signal.ABORT signal is waiting to be sent send it.

Overrides:

onAfterCommit in class BasicItem<JobData>

Since:

2.6.1

See Also:

Transactional, Core API overview - Transaction handling, Coding rules and guidelines for item classes

initPermissions

void initPermissions(int granted,
                     int denied)

Grant read permission if the logged in user has read permission to the experiment the job belongs to.

Overrides:

initPermissions in class OwnedItem<JobData>

Parameters:

granted - Permissions that have been granted by the subclass

denied - Permissions that have been denied by the subclass

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

setPluginDefinition

private void setPluginDefinition(PluginDefinition plugin)
                          throws PermissionDeniedException

Set the plugin configuration of this job.

Throws:

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

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

setPluginConfiguration

private void setPluginConfiguration(PluginConfiguration pluginConfiguration)
                             throws PermissionDeniedException

Set the plugin configuration of this job.

Throws:

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

getExperiment

public Experiment getExperiment()

Get the experiment this job is a part of.

Returns:

The Experiment item, or null if this job isn't part of an experiment

Since:

2.4

setExperiment

void setExperiment(Experiment experiment)

Set the experiment this job is part of. Once an experiment has been set, it can't be changed.

Since:

2.4

getPluginVersion

public String getPluginVersion()

Get the version of the plugin used to execute this job at the time the job was executed or registered.

Returns:

The version string, or null if not known

Since:

2.8

getParameterVersion

public int getParameterVersion()

Get the version number of the configuration parameters used for this job.

getSendMessage

public boolean getSendMessage()

If a message should be sent to the owner once the job has finished or not.

setSendMessage

public void setSendMessage(boolean sendMessage)
                    throws PermissionDeniedException

Set if a message should be sent to owner when the job finishes.

Parameters:

sendMessage - TRUE if a message should be sent, FALSE otherwise.

Throws:

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

getRemoveJobWhenFinished

public boolean getRemoveJobWhenFinished()

If the job should flagged for deletion after it's done successfully.

Returns:

TRUE if job is flagged to be removed, FALSE otherwise

setRemoveJobWhenFinished

public void setRemoveJobWhenFinished(boolean removeJobWhenFinished)

Set if the job should be deleted after it has finished successfully.

Parameters:

removeJobWhenFinished - TRUE if the job should be flagged for deletion when finished, FALSE otherwise.

Throws:

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

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

getStatus

public Job.Status getStatus()

Get the status of the job.

isDryRun

public boolean isDryRun()

Check if the job should be/was executed as a dry-run job. A dry-run job is a job that does all the things a normal job would do except committing the changes to the database. The dry-run job may output a log file with detailed information about what should have happened if it hadn't been a dry-run.

Since:

2.8

getStatusMessage

public String getStatusMessage()

Get a message about the current status of the job.

getStackTrace

public String getStackTrace()

Get the stack trace in case the job ended with an error

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). -1 indicates a job that is running but doesn't know the progress.

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.

Parameters:

priority - The priority to set.

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

getScheduled

public Date getScheduled()

Get the date and time the job was scheduled to the job queue.

Returns:

A date, or null if the job hasn't been scheduled

Since:

2.16

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.

hasContext

public boolean hasContext()

Checks if this job has saved information about the context that was active when this job was created. If context information is available it is possible to re-configure a failed job.

Returns:

TRUE if context information is available, FALSE otherwise

Since:

2.8

See Also:

configure(GuiContext), getLastGuiContext()

getLastGuiContext

public GuiContext getLastGuiContext()

Get the gui-context that was active when this job was created.

Returns:

The active context, or null if not known

Since:

2.8

getJobAgent

public JobAgent getJobAgent()

Get the job agent this job should run on, is running on or was running on.

Returns:

A job agent or null if not known

Since:

2.8

setJobAgent

public void setJobAgent(JobAgent agent)

Set the job agent this job should run on. If the job is already running or has ended, this call is ignored.

NOTE! This method doesn't check that the specified job agent has actually been configured to run the plug-in used by this job. Setting this parameter to an incorrect value may result in the job never being executed.

Parameters:

agent - The job agent, or null to let any job agent run the job

Throws:

PermissionDeniedException - If the logged in user doesn't have write permission on this job, or use permission on the job agent or is lacking the Permission.SELECT_JOBAGENT permission

Since:

2.8

setSignalTransporter

public void setSignalTransporter(Class<? extends SignalTransporter> clazz,
                                 String initParams)

Set information needed to create a signal transporter object that can be used to send signals to the plug-in that is currently executing this job.

Parameters:

clazz - The signal transporter class

initParams - Initialisation parameters that will be passed to SignalTransporter.init(String)

Throws:

PermissionDeniedException - If the user doesn't have write permission for the job

Since:

2.6

hasSignalTransporter

public boolean hasSignalTransporter()

Checks if a signal transporter has been registered for this job or not.

Returns:

TRUE if a signal transporter is registered, FALSE otherwise

Since:

2.6

getSignalTransporter

public SignalTransporter getSignalTransporter()

Create and initialise a signal transporter object that can be used to send signal to the plug-in running this job.

Note 1! Depending on the transport mechanism used, it is not certain that the created transporter can actually send the signal. For example, some transporters only work if the plug-in is running in the same virtual machine, while others supports sending signals to other JVM:s on the same or a different computer.

Note 2! The returned transporter will delay the Signal.ABORT signal until DbControl.commit() is called and will only send the signal if the transaction is completed succesfully. If the transaction fails or is rolled back the signal is not sent. Other signals are sent immediately.

Note 3! This method always returns the same transporter instance if it is called multiple times.

Returns:

An initialised signal transporter object, or null if no signal transporter has been registered

Throws:

PermissionDeniedException - If the user doesn't have write permission for the job

Since:

2.6

getEnded

public Date getEnded()

Get the date and time the job ended.

Returns:

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

setPrepared

public void setPrepared(String server)
                 throws PermissionDeniedException

Deprecated. Use setPrepared(String, JobAgent) instead

Throws:

PermissionDeniedException

setPrepared

public void setPrepared(String server,
                        JobAgent agent)
                 throws PermissionDeniedException

Set the job's status to Job.Status.PREPARED. This status is used to signal that a job is about to be executed, but the actual excecution hasn't started yet. This status prevents two job agents from trying to start the same job twice.

Parameters:

server - Name of the server which this job will executed on

agent - The job agent that is going to execute the job or null if it is executed by something else, eg. the internal job queue

Throws:

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

Since:

2.8

start

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

Deprecated. Use start(String, String, JobAgent) instead

Throws:

PermissionDeniedException

InvalidDataException

start

public void start(String statusMessage,
                  String server,
                  JobAgent agent)
           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

agent - The job agent that is going to execute the job or null if it is executed by something else, eg. the internal job queue

Throws:

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

InvalidDataException - If the status message is too long

Since:

2.8

getProgressReporter

public ProgressReporter getProgressReporter(ProgressReporter chained)

Get a progress reporter that reports progress by updating the information in the database.

Parameters:

chained - An optional chained progress reporter to which all updates will be forwarded

Returns:

A progress reporter object

Since:

2.4

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 or Job.Status.PREPARED 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

doneError

public void doneError(String statusMessage,
                      Collection<? extends Throwable> errors)

Register the job as completed with an error.

Parameters:

statusMessage - A short message describing the error

errors - A list of one or more errors that caused the job to fail, the complete stack trace for those errors are stored in the getStackTrace() property

Throws:

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

InvalidDataException - If the status message is too long

retry

public void retry(boolean useLatestConfiguration)
           throws PermissionDeniedException

Deprecated. Use retry(boolean, boolean) instead

Retry a job which finished with an error.

Parameters:

useLatestConfiguration - If the job should use the latest configuration parameters in case these has changed since the job was created

Throws:

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

retry

public void retry(boolean useLatestConfiguration,
                  boolean clearDryRun)
           throws PermissionDeniedException

Retry a job which finished with an error or a successful dry-run job.

Parameters:

useLatestConfiguration - If the job should use the latest configuration parameters in case these has changed since the job was created

clearDryRun - If the job was a dry-run job, clear the dry-run flag to indicate that it should be executed for real the next time

Throws:

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

continueLater

void continueLater(String executeCommand,
                   boolean isShuttingDown)

This method is used to indicate that a job had to be aborted due to a system shutdown. The job can be restarted one the system is up and running again.

This method will reset the job status to WAITING. The execute command parameter can be set to allow the plug-in to tell the difference between a first-time execution and resuming after a system shutdown.

Parameters:

executeCommand - The command to send the next time the job is started, if not given Request.COMMAND_EXECUTE is used

isShuttingDown - TRUE if the system is currently shutting down (which means that the 'scheduled' data is not reset to allow the job to be started first once the system is up and running)

Since:

2.16

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.

Parameters:

context - GUI context from where the configuration is called.

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(). See PluginRequest for more information.

Parameters:

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

server - The name of the server executing the plugin

Returns:

A Plugin.Request 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

execute

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

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

Parameters:

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

server - The name of the server executing the plugin

settings - The job agent settings to use or null to use default settings

Returns:

A Plugin.Request 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

getParameterValue

public Object getParameterValue(String name)
                         throws PermissionDeniedException,
                                BaseException

Get the value of a named parameter. If the parameter has mulitple values only the first is returned.

Parameters:

name - The name of the parameter

Returns:

The value as an object, 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

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

getParameterInfo

public ParameterInfo getParameterInfo(String name)
                               throws PermissionDeniedException,
                                      BaseException

Get extra information about a parameter. The information includes the label, description and values of the parameter.

Parameters:

name - The name of the parameter

Returns:

A ParameterInfo object or null if no parameter with the specified name exists

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 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

setParameterValue

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

Set the value of a configuration parameter. This method can only be called if the job isn't already executing. This method also sets the status of the job to Job.Status.WAITING.

Parameters:

name - The name of the parameter

label - The label of the parameter (optional)

description - A description of the parameter (optional)

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 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

setParameterValues

public void setParameterValues(String name,
                               String label,
                               String description,
                               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

label - The label of the parameter (optional)

description - A description of the parameter (optional)

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

copyParametersFrom

public void copyParametersFrom(Job copyFrom)
                        throws InvalidDataException,
                               PermissionDeniedException,
                               BaseException

Copy all parameter values from another job. Existing parameters with the same name will be overwritten.

Parameters:

copyFrom - The job to copy parameters from

Throws:

InvalidDataException - If the copyFrom parameter is null

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

BaseException - If there is another error

setParameterValuesInternal

void setParameterValuesInternal(String name,
                                String label,
                                String description,
                                ParameterType<?> parameterType,
                                List<?> values,
                                boolean validate)
                          throws InvalidDataException,
                                 PermissionDeniedException,
                                 BaseException

Set the values of a configuration parameter.

Parameters:

name - The name of the configuration parameter

label - The label of the parameter (optional)

description - A description of the parameter (optional)

parameterType - The type of the parameter

values - A list containing the new values, null or empty to remove the configuration values

validate - If validation by ParameterType.validate(String, List) is needed or not

Throws:

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

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

BaseException - If there is another error

getParameterValuesImpl

ParameterValuesImpl getParameterValuesImpl()
                                     throws BaseException

Get a write-protected ParameterValuesImpl object.

Throws:

BaseException

sendMessage

private void sendMessage()

Send a message to the owner of the job when the job has finished