Class Job

    • Field Detail

      • TYPE

        public static final Item TYPE
        The type of item represented by this class.
        See Also:
        Item.JOB, getType()
      • 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 Detail

    • Method Detail

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

        public static ItemQuery<Job> getQuery()
        Get a query configured to retrieve jobs.
        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
      • 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()
      • 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.
      • 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,
                          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
      • 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.
      • removeState

        void removeState()
        Remove the saved state from the cache.
      • 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,
                                      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,
                                       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
      • sendMessage

        private void sendMessage()
        Send a message to the owner of the job when the job has finished