Class Job
- All Implemented Interfaces:
AccessControlled
,Controlled
,Identifiable
,Nameable
,Ownable
,Removable
,Shareable
,Subtypable
,Transactional
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 jobexecute(ProgressReporter, String)
: Starts executing the job
start(String, String, JobAgent)
: Tell the core that job has startedsetProgress(int, String)
: Update the progress status of the jobdoneOk(String)
: Tell the core that the job finished successfullydoneError(String)
: Thell the core that the job finished with an error
- Version:
- 2.0
- Author:
- Nicklas
- Last modified
- $Date: 2024-02-02 11:56:01 +0100 (Fri, 02 Feb 2024) $
-
Nested Class Summary
Modifier and TypeClassDescriptionstatic enum
A rough estimate of the execution time of a job.private class
Wrapper for the signal transporter that intercepts the ABORT signal and changes the job's status to ABORTING.(package private) static class
Implements the ProgressReporter interface and stores the percentage completed for the current job.(package private) static class
Our own keyring containing the permissions signal handlers may need to update job status, eq.static enum
The status of a job.static enum
The type of job.Nested classes/interfaces inherited from interface net.sf.basedb.core.Transactional
Transactional.Action
-
Field Summary
Modifier and TypeFieldDescriptionstatic final int
The maximum allowed length of the external ID.static final int
The maximum allowed length of the server name.static final int
The maximum allowed length of the stack trace message.static final int
The maximum allowed length of the status message.private Job.JobSignalTransporter
static final Item
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
-
Method Summary
Modifier and TypeMethodDescriptionvoid
Reset the currently stored execution command to force a plug-in to restart from the beginning instead of at the stored breakpoint.configure
(GuiContext context) Start the configuration sequence for a job.(package private) void
continueLater
(String executeCommand, boolean isShuttingDown, Serializable state) 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
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
doneError
(String statusMessage, Collection<? extends Throwable> errors, Date endTime) Register the job as completed with an error.void
Register the job as successfully completed.void
Register the job as successfully completed.execute
(ProgressReporter progress, String server) Start the execution sequence for a job.execute
(ProgressReporter progress, String server, String node, JobAgentSettings settings) Start the execution sequence for a job.execute
(ProgressReporter progress, String server, JobAgentSettings settings) int
The ID of the project that should be made the active project while running this job.static Job
Get aJob
item when you know the id.Get the date and time the job was registered in the database.(package private) JobData
getData()
Get theBasicData
object that holds all data for this item.getEnded()
Get the date and time the job ended.Get the estimated execution time of the job.The command to send to the plug-in when starting to execute it.Get the experiment this job is a part of.Get the external ID of a job running on an external server.Get the subtype of the item.Get the job agent this job should run on, is running on or was running on.Get the type of job, ie. if it is a job executed by a plugin or not.Get the gui-context that was active when this job was created.static Job
getNew
(DbControl dc, PluginDefinition plugin, PluginConfiguration config, Experiment experiment) Create a newJob
item.getNode()
Get the name of the node where the job is executing.getParameterInfo
(String name) Get extra information about a parameter.Get the names of all parameters for the job.<T> T
getParameterValue
(String name) Get the value of a named parameter.Get the configuration parameters as aParameterValues
object.<T> List<T>
getParameterValues
(String name) Get the values of a named parameter.(package private) ParameterValuesImpl
Get a write-protected ParameterValuesImpl object.int
Get the version number of the configuration parameters used for this job.int
An estimate of the percentage of the work currently completed by an executing job.Get thePluginConfiguration
defining the plugin this job should execute.Get thePluginConfiguration
defining the plugin this job should execute.Get the version of the plugin used to execute this job at the time the job was executed or registered.int
Get the priority of the job.getProgressReporter
(ProgressReporter chained) Get a progress reporter that reports progress by updating the information in the database.getQuery()
Get a query configured to retrieve jobs.boolean
If the job should flagged for deletion after it's done successfully.Get the date and time the job was scheduled to the job queue.boolean
If a message should be sent to the owner once the job has finished or not.Get the name of the server where the job is executing.Utility method for getting both the server and node as a single string (for display purposes).Create and initialise a signal transporter object that can be used to send signal to the plug-in running this job.Get the stack trace in case the job ended with an errorGet the date and time the job was started.Get the status of the job.Get a message about the current status of the job.getType()
Get the type of item represented by the object.Get the transformation and raw bioassays using this job.boolean
Checks if this job has saved information about the context that was active when this job was created.boolean
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
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) Serializable
loadState
(ClassLoader loader) Load the saved state from the cache.(package private) void
onAfterCommit
(Transactional.Action action) If theSignal.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.(package private) void
pause
(String message, String executeCommand, Serializable state) This method is used to indicate that a job has been paused, either by manual interaction or by some other trigger.(package private) void
Remove the saved state from the cache.boolean
Request that the underlying job updates the status information about itself.void
retry
(boolean useLatestConfiguration, boolean clearDryRun) Retry a job which finished with an error or a successful dry-run job.(package private) void
saveState
(Serializable state) Save the job state to the static cache.private void
Send a message to the owner of the job when the job has finished(package private) void
setExperiment
(Experiment experiment) Set the experiment this job is part of.void
setExternalId
(String externalId) Set the external ID.void
setItemSubtype
(ItemSubtype subtype) Set the subtype on the item.void
setJobAgent
(JobAgent agent) Set the job agent this job should run on.void
setParameterValue
(String name, String label, String description, ParameterType<?> parameterType, Object value) Set the value of a configuration parameter.void
setParameterValue
(String name, ParameterType<?> parameterType, Object value) 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.void
setParameterValues
(String name, 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
setPluginVersion
(String pluginVersion) Set the version of the plugin that executes the job.void
setPrepared
(String server, JobAgent agent) Set the job's status toJob.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
setRemoveJobWhenFinished
(boolean removeJobWhenFinished) Set if the job should be deleted after it has finished successfully.void
setScheduled
(String server, JobAgent agent) Set the job's status toJob.Status.WAITING
.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
Register the job as started.void
Register the job as started.void
Methods inherited from class net.sf.basedb.core.CommonItem
getDescription, getName, getRemovedBy, isRemoved, setDescription, setName, setRemoved
Methods inherited from class net.sf.basedb.core.SharedItem
getItemKey, getProjectKey, isShared, setItemKey, setProjectKey
Methods inherited from class net.sf.basedb.core.OwnedItem
getOwner, isOwner, setOwner, takeOwnership
Methods inherited from class net.sf.basedb.core.BasicItem
addAnnotatableParents, addUsingItems, addUsingItems, breakCircularReferences, checkBatchAnnotatableUsage, checkPermission, equals, getBasicData, getDbControl, getId, getPermissions, getPluginPermissions, getSessionControl, getVersion, hashCode, hasPermission, isDetached, isInDatabase, onAfterInsert, onRollback, setDbControl, setProjectDefaults, toString, validate
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface net.sf.basedb.core.AccessControlled
checkPermission, getPermissions, hasPermission
Methods inherited from interface net.sf.basedb.core.Identifiable
getId, getVersion
Methods inherited from interface net.sf.basedb.core.Ownable
getOwner, isOwner, setOwner, takeOwnership
-
Field Details
-
TYPE
The type of item represented by this class. -
signalTransporter
-
MAX_EXTERNAL_ID_LENGTH
public static final int MAX_EXTERNAL_ID_LENGTHThe maximum allowed length of the external ID.- Since:
- 3.3
- See Also:
-
MAX_STATUS_MESSAGE_LENGTH
public static final int MAX_STATUS_MESSAGE_LENGTHThe maximum allowed length of the status message.- See Also:
-
MAX_STACK_TRACE_LENGTH
public static final int MAX_STACK_TRACE_LENGTHThe maximum allowed length of the stack trace message.- See Also:
-
MAX_SERVER_LENGTH
public static final int MAX_SERVER_LENGTHThe maximum allowed length of the server name.- See Also:
-
-
Constructor Details
-
Job
Job(JobData jobData)
-
-
Method Details
-
getNew
public static Job getNew(DbControl dc, PluginDefinition plugin, PluginConfiguration config, Experiment experiment) throws InvalidDataException, BaseException Create a newJob
item.- Parameters:
dc
- TheDbControl
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 programexperiment
- 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 nullBaseException
- If there is an error- Since:
- 2.7
-
getById
public static Job getById(DbControl dc, int id) throws ItemNotFoundException, PermissionDeniedException, BaseException Get aJob
item when you know the id.- Parameters:
dc
- TheDbControl
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 foundPermissionDeniedException
- If the logged in user doesn't have read permission to the itemBaseException
- If there is another error
-
getQuery
Get a query configured to retrieve jobs.- Returns:
- An
ItemQuery
object
-
getData
JobData getData()Description copied from class:BasicItem
Get theBasicData
object that holds all data for this item.- Overrides:
getData
in classCommonItem
-
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 theItem
enumeration.- Specified by:
getType
in interfaceIdentifiable
- Returns:
- A value indicating the type of item
-
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
- Overrides:
isUsed
in classBasicItem
- Returns:
- TRUE if this item is used, FALSE otherwise
- Throws:
BaseException
- If not able to tell if item is used or not.- See Also:
-
getUsingItems
Get the transformation and raw bioassays using this job.- Overrides:
getUsingItems
in classBasicItem
- Returns:
- A set containing proxies for the items, or an empty set if no items are using this item
- Since:
- 2.2
- See Also:
-
onBeforeCommit
Set's the project id to the currently active project.- Overrides:
onBeforeCommit
in classSharedItem
- Throws:
NotLoggedInException
- If no user is logged inBaseException
- If there is another error- See Also:
-
onAfterCommit
If theSignal.ABORT
signal is waiting to be sent send it.- Overrides:
onAfterCommit
in classBasicItem
- Since:
- 2.6.1
- See Also:
-
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 classSharedItem
- Parameters:
granted
- Permissions that have been granted by the subclassdenied
- Permissions that have been denied by the subclass
-
getExternalId
Get the external ID of a job running on an external server.- Since:
- 3.3
-
setExternalId
Set the external ID.- Since:
- 3.3
-
getJobType
Get the type of job, ie. if it is a job executed by a plugin or not. -
getItemSubtype
Description copied from interface:Subtypable
Get the subtype of the item.- Specified by:
getItemSubtype
in interfaceSubtypable
- Returns:
- A subtype of null if not set
- Since:
- 3.10
- See Also:
-
setItemSubtype
Description copied from interface:Subtypable
Set the subtype on the item.- Specified by:
setItemSubtype
in interfaceSubtypable
- Parameters:
subtype
- A subtype or null- Since:
- 3.10
- See Also:
-
getPluginDefinition
Get thePluginConfiguration
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 configurationBaseException
- If there is another error
-
setPluginDefinition
Set the plugin configuration of this job.- Throws:
PermissionDeniedException
- If the logged in user doesn't have use permission for the plugin configuration
-
getPluginConfiguration
Get thePluginConfiguration
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 configurationBaseException
- 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
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
Set the experiment this job is part of. Once an experiment has been set, it can't be changed.- Since:
- 2.4
-
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
-
setPluginVersion
Set the version of the plugin that executes the job. NOTE! This is automatically called for jobs that are executed by plug-ins but should be called excplicitely for other types of jobs- Since:
- 3.3.2
-
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
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
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
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
Get a message about the current status of the job. -
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
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'tWAITING
orUNCONFIGURED
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
Get the date and time the job was registered in the database.- Returns:
- A 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
Get the date and time the job was started.- Returns:
- A date, or null if the job hasn't started
- See Also:
-
getServer
Get the name of the server where the job is executing. -
getNode
Get the name of the node where the job is executing. If this value is used it typically means that the server is some kind of master controller for multiple nodes in a cluster.- Since:
- 3.10
-
getServerAndNode
Utility method for getting both the server and node as a single string (for display purposes). If either value is null, only the non-null value is returned. Otherwise the node name is appended to the server name and enclosed in [...].- Since:
- 3.10
-
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:
-
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
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
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 thePermission.SELECT_JOBAGENT
permission- Since:
- 2.8
-
setSignalTransporter
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 classinitParams
- Initialisation parameters that will be passed toSignalTransporter.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
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 untilDbControl.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.
Note 4! If the signal transporter is a
ExtensionSignalTransporter
the extension point is "net.sf.basedb.core.signal.job". The client context is populated with aSessionControl
and the current item is thisJob
. The information in the job should be considered read-only, if the signal handler wants to update information it must create a newDbControl
from the session control and re-load the job.- Returns:
- An initialised signal transporter object, or null if no signal transporter has been registered
- Since:
- 2.6
-
requestStatusUpdate
public boolean requestStatusUpdate()Request that the underlying job updates the status information about itself. This method is intended to be used for external jobs that are not BASE plug-ins (which can report progress through the plug-in API). This method sends aSignal.STATUS
signal to theSignalTransporter
that has been registered for the job. If there is no signal transporter this method does nothing. The signal transporter should deliver the signal as quickly as possible and then return. The actual progress update may take place at a later time when it is convenient to do so for the job.- Returns:
- TRUE if a
Signal.STATUS
could be sent, FALSE if not - Since:
- 3.3
-
getEnded
Get the date and time the job ended.- Returns:
- A date, or null if the job hasn't ended
-
getExecuteCommand
The command to send to the plug-in when starting to execute it. If null, a default values is used. See Request.COMMAND_EXECUTE. This is usually only used when automatically restarting a failed job.- Since:
- 3.11
-
clearExecuteCommand
public void clearExecuteCommand()Reset the currently stored execution command to force a plug-in to restart from the beginning instead of at the stored breakpoint.- Since:
- 3.11
-
setScheduled
Set the job's status toJob.Status.WAITING
. This status is used to signal that a job has been fully configured and is ready for execution.- Parameters:
server
- Name of the server which this job will executed onagent
- 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:
- 3.3
-
setPrepared
Set the job's status toJob.Status.PREPARED
. This status is used to signal that a job is about to be executed, but the actual execution 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 onagent
- 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, 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 messageserver
- The name of the server where the job is startedagent
- 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 permissionInvalidDataException
- If the status message is too long- Since:
- 2.8
-
start
public void start(String statusMessage, String server, JobAgent agent, Date startTime) throws PermissionDeniedException, InvalidDataException - Throws:
PermissionDeniedException
InvalidDataException
- Since:
- 3.3
- See Also:
-
start
public void start(String statusMessage, String server, String node, JobAgent agent, Date startTime) 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 messageserver
- The name of the server where the job is startednode
- The name of the node in a cluster that is actually running the jobagent
- The job agent that is going to execute the job or null if it is executed by something else, eg. the internal job queuestartTime
- The actual start time for the job or null to use the current system time- Throws:
PermissionDeniedException
- If the logged in user doesn't have write permissionInvalidDataException
- If the status message is too long- Since:
- 3.10
-
getProgressReporter
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 theJob.Status.WAITING
,Job.Status.EXECUTING
,Job.Status.PREPARED
orJob.Status.ABORTING
status. -1 can be used as a special value to indicate that it is not known how far the job has progressed.- Parameters:
percentComplete
- The number of percent completedstatusMessage
- A message- Throws:
PermissionDeniedException
- If the logged in user doesn't have write permission of the job isn't in correct statusInvalidDataException
- If the status message is too long or the percentage value isn't between -1 and 100
-
doneOk
Register the job as successfully completed.- Parameters:
statusMessage
- A message- Throws:
PermissionDeniedException
- If the logged in user doesn't have write permissionInvalidDataException
- If the status message is too long
-
doneOk
public void doneOk(String statusMessage, Date endTime) throws PermissionDeniedException, InvalidDataException Register the job as successfully completed.- Parameters:
statusMessage
- A messageendTime
- The actual end time for the job or null to use the current system time- Throws:
PermissionDeniedException
- If the logged in user doesn't have write permissionInvalidDataException
- If the status message is too long- Since:
- 3.3
-
doneError
Register the job as completed with an error.- Parameters:
statusMessage
- A message- Throws:
PermissionDeniedException
- If the logged in user doesn't have write permissionInvalidDataException
- If the status message is too long
-
doneError
Register the job as completed with an error.- Parameters:
statusMessage
- A short message describing the errorerrors
- A list of one or more errors that caused the job to fail, the complete stack trace for those errors are stored in thegetStackTrace()
property- Throws:
PermissionDeniedException
- If the logged in user doesn't have write permissionInvalidDataException
- If the status message is too long
-
doneError
Register the job as completed with an error.- Parameters:
statusMessage
- A short message describing the errorerrors
- A list of one or more errors that caused the job to fail, the complete stack trace for those errors are stored in thegetStackTrace()
propertyendTime
- The actual end time for the job or null to use the current system time- Throws:
PermissionDeniedException
- If the logged in user doesn't have write permissionInvalidDataException
- If the status message is too long- Since:
- 3.3
-
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 createdclearDryRun
- 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
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 givenRequest.COMMAND_EXECUTE
is usedisShuttingDown
- 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, 3.11
-
pause
This method is used to indicate that a job has been paused, either by manual interaction or by some other trigger. The job can be restarted again by manual interaction.This method will reset the job status to PAUSED. The execute command parameter can be set to allow the plug-in to know where to resume if it is restarted. The state parameter can be any information that the plug-in need to be able to restore itself to a similar state as before the pause.
- Parameters:
executeCommand
- The command to send the next time the job is started, if not givenRequest.COMMAND_EXECUTE
is usedstate
- The state information will be saved and made available to the plug-in when the job is resumed- Since:
- 3.11
-
saveState
Save the job state to the static cache. -
loadState
Load the saved state from the cache.- Since:
- 3.11
-
removeState
void removeState()Remove the saved state from the cache. -
configure
public PluginConfigurationRequest configure(GuiContext context) throws PermissionDeniedException, BaseException Start the configuration sequence for a job. Do not callDbControl.commit()
until the configuration sequence is done. SeePluginRequest
for more information. This method changes the status of the job toJob.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 permissionBaseException
- If there is another error
-
execute
public PluginExecutionRequest execute(ProgressReporter progress, String server) throws PermissionDeniedException, InvalidDataException, BaseException Start the execution sequence for a job. CallDbControl.commit()
before callingPluginRequest.invoke()
. SeePluginRequest
for more information.- Parameters:
progress
- TheProgressReporter
where the plugin can report its progress. Ifnull
Job.ProgressReporterImpl
is usedserver
- 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 theJob.Status.WAITING
statusInvalidDataException
- If the server name is too longBaseException
- If there is another error
-
execute
public PluginExecutionRequest execute(ProgressReporter progress, String server, JobAgentSettings settings) throws PermissionDeniedException, InvalidDataException, BaseException -
execute
public PluginExecutionRequest execute(ProgressReporter progress, String server, String node, JobAgentSettings settings) throws PermissionDeniedException, InvalidDataException, BaseException Start the execution sequence for a job. CallDbControl.commit()
before callingPluginRequest.invoke()
. SeePluginRequest
for more information.- Parameters:
progress
- TheProgressReporter
where the plugin can report its progress. Ifnull
Job.ProgressReporterImpl
is usedserver
- The name of the server executing the pluginnode
- The name of the node in a cluster that is actually running the jobsettings
- 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 theJob.Status.WAITING
statusInvalidDataException
- If the server name is too longBaseException
- If there is another error- Since:
- 3.10
-
getParameterValues
Get the configuration parameters as aParameterValues
object. The parameters are write protected.- Returns:
- A ParameterValues object
- Since:
- 3.3
- See Also:
-
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
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 forBaseException
- If there is another error
-
getParameterValues
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 forBaseException
- If there is another error
-
getParameterInfo
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 forBaseException
- 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 toJob.Status.WAITING
.- Parameters:
name
- The name of the parameterparameterType
- The type of the parametervalue
- The value of the parameter- Throws:
PermissionDeniedException
- If the logged in user doesn't have write permission or if the job is executingInvalidDataException
- If name is null or the new value doesn't validate against the parameter typeBaseException
- 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 toJob.Status.WAITING
.- Parameters:
name
- The name of the parameterlabel
- The label of the parameter (optional)description
- A description of the parameter (optional)parameterType
- The type of the parametervalue
- The value of the parameter- Throws:
PermissionDeniedException
- If the logged in user doesn't have write permission or if the job is executingInvalidDataException
- If name is null or the new value doesn't validate against the parameter typeBaseException
- 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 toJob.Status.WAITING
.- Parameters:
name
- The name of the parameterparameterType
- The type of the parametervalues
- A list containing the values- Throws:
PermissionDeniedException
- If the logged in user doesn't have write permission or if the job is executingInvalidDataException
- If name is null or the new value doesn't validate against the parameter typeBaseException
- 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 toJob.Status.WAITING
.- Parameters:
name
- The name of the parameterlabel
- The label of the parameter (optional)description
- A description of the parameter (optional)parameterType
- The type of the parametervalues
- A list containing the values- Throws:
PermissionDeniedException
- If the logged in user doesn't have write permission or if the job is executingInvalidDataException
- If name is null or the new value doesn't validate against the parameter typeBaseException
- 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 nullPermissionDeniedException
- If the logged in user doesn't have write permission for this configurationBaseException
- 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 parameterlabel
- The label of the parameter (optional)description
- A description of the parameter (optional)parameterType
- The type of the parametervalues
- A list containing the new values, null or empty to remove the configuration valuesvalidate
- If validation byParameterType.validate(String, List)
is needed or not- Throws:
PermissionDeniedException
- If the logged in user doesn't have write permissionInvalidDataException
- If name is null or the new value doesn't validate against the parameter typeBaseException
- If there is another error
-
getParameterValuesImpl
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
-