Package net.sf.basedb.core

Class Job

java.lang.Object
net.sf.basedb.core.BasicItem
net.sf.basedb.core.OwnedItem
net.sf.basedb.core.SharedItem
net.sf.basedb.core.CommonItem
net.sf.basedb.core.Job
All Implemented Interfaces:
AccessControlled, Controlled, Identifiable, Nameable, Ownable, Removable, Shareable, Subtypable, Transactional
public class Job
extends CommonItem
implements Transactional, Subtypable
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: The following methods can only be used by jobs executed by an external program:
Version:
2.0
Author:
Nicklas
Last modified
$Date: 2022-12-20 13:44:36 +0100 (Tue, 20 Dec 2022) $

  • Field Details

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

      public static final int MAX_EXTERNAL_ID_LENGTH
      The maximum allowed length of the external ID.
      Since:
      3.3
      See Also:
      Constant Field Values

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

  • Method Details

    • 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 jobs.
      Returns:
      An ItemQuery object

    • getData

      JobData getData()
      Description copied from class: BasicItem
      Get the BasicData object that holds all data for this item.
      Overrides:
      getData in class CommonItem

    • 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

    • 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
      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
      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.Query)

    • onBeforeCommit

      void onBeforeCommit​(Transactional.Action action) throws NotLoggedInException, BaseException
      Set's the project id to the currently active project.
      Overrides:
      onBeforeCommit in class SharedItem
      Throws:
      NotLoggedInException - If no user is logged in
      BaseException - If there is another error
      See Also:
      Transactional, Developer documentation: Transactions, Developer documentation: 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
      Since:
      2.6.1
      See Also:
      Transactional, Developer documentation: Transactions, Developer documentation: 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 SharedItem
      Parameters:
      granted - Permissions that have been granted by the subclass
      denied - Permissions that have been denied by the subclass

    • getExternalId

      public String getExternalId()
      Get the external ID of a job running on an external server.
      Since:
      3.3

    • setExternalId

      public void setExternalId​(String externalId)
      Set the external ID.
      Since:
      3.3

    • getJobType

      public Job.Type getJobType()
      Get the type of job, ie. if it is a job executed by a plugin or not.

    • getItemSubtype

      public ItemSubtype getItemSubtype()
      Description copied from interface: Subtypable
      Get the subtype of the item.
      Specified by:
      getItemSubtype in interface Subtypable
      Returns:
      A subtype of null if not set
      Since:
      3.10
      See Also:
      SubtypableRelatedItems

    • setItemSubtype

      public void setItemSubtype​(ItemSubtype subtype)
      Description copied from interface: Subtypable
      Set the subtype on the item.
      Specified by:
      setItemSubtype in interface Subtypable
      Parameters:
      subtype - A subtype or null
      Since:
      3.10
      See Also:
      ItemSubtype.setOnItem(Subtypable)

    • 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

    • setPluginVersion

      public void setPluginVersion​(String pluginVersion)
      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

      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 or UNCONFIGURED
      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, JobAgent)

    • getServer

      public String getServer()
      Get the name of the server where the job is executing.

    • getNode

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

      public String 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:
      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.

      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 a SessionControl and the current item is this Job. The information in the job should be considered read-only, if the signal handler wants to update information it must create a new DbControl 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 a Signal.STATUS signal to the SignalTransporter 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

      public Date getEnded()
      Get the date and time the job ended.
      Returns:
      A date, or null if the job hasn't ended

    • getExecuteCommand

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

      public void setScheduled​(String server, JobAgent agent) throws PermissionDeniedException
      Set the job's status to Job.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 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:
      3.3

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

    • start

      public void start​(String statusMessage, String server, JobAgent agent, Date startTime) throws PermissionDeniedException, InvalidDataException
      Throws:
      PermissionDeniedException
      InvalidDataException
      Since:
      3.3
      See Also:
      start(String, String, String, JobAgent, Date)

    • 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 message
      server - The name of the server where the job is started
      node - The name of the node in a cluster that is actually running the job
      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
      startTime - 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 permission
      InvalidDataException - If the status message is too long
      Since:
      3.10

    • 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. -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 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 -1 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

    • doneOk

      public void doneOk​(String statusMessage, Date endTime) throws PermissionDeniedException, InvalidDataException
      Register the job as successfully completed.
      Parameters:
      statusMessage - A message
      endTime - 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 permission
      InvalidDataException - If the status message is too long
      Since:
      3.3

    • 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

    • doneError

      public void doneError​(String statusMessage, Collection<? extends Throwable> errors, Date endTime)
      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
      endTime - 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 permission
      InvalidDataException - 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 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, Serializable state)
      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, 3.11

    • pause

      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. 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 given Request.COMMAND_EXECUTE is used
      state - The state information will be saved and made available to the plug-in when the job is resumed
      Since:
      3.11

    • saveState

      void saveState​(Serializable state)
      Save the job state to the static cache.

    • loadState

      Serializable loadState​(ClassLoader loader)
      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 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
      Throws:
      PermissionDeniedException
      InvalidDataException
      BaseException
      See Also:
      execute(ProgressReporter, String, String, JobAgentSettings)

    • execute

      public PluginExecutionRequest execute​(ProgressReporter progress, String server, String node, 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
      node - The name of the node in a cluster that is actually running the job
      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
      Since:
      3.10

    • getParameterValues

      public ParameterValues getParameterValues()
      Get the configuration parameters as a ParameterValues object. The parameters are write protected.
      Returns:
      A ParameterValues object
      Since:
      3.3
      See Also:
      getParameterVersion()

    • 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 <T> T 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 <T> List<T> 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