Package com.redwood.scheduler.api.job

Interface UserJobContext

    • Method Detail

      • getOutputLogger

        JobLogger getOutputLogger()
        Get a Logger to log output messages to. Avoid mixing this with calls to the PrintWriter returned by getLogWriter.
        Returns:
        a logger.

      • getOutputWriter

        PrintWriter getOutputWriter()
        Get the PrintWriter to write output to.
        Returns:
        the PrintWriter.

      • getErrorLogger

        JobLogger getErrorLogger()
        Get a Logger to log error messages to. Avoid mixing this with calls to the PrintWriter returned by getLogWriter.
        Returns:
        a logger.

      • getErrorWriter

        PrintWriter getErrorWriter()
        Get the PrintWriter to write errors to.
        Returns:
        the PrintWriter.

      • operatorMessage

        void operatorMessage​(SchedulerSession session,
                     String message)
              throws com.redwood.scheduler.api.exception.SchedulerAPIPersistenceException
        Insert an operator message in the operator messages table Note that persist() will be called
        Parameters:
        session - the SchedulerSession
        message - the message to the operator
        Throws:
        com.redwood.scheduler.api.exception.SchedulerAPIPersistenceException - if the message could not be written

      • operatorMessage

        void operatorMessage​(String message)
              throws com.redwood.scheduler.api.exception.SchedulerAPIPersistenceException
        Insert an operator message in the operator messages table
        Parameters:
        message - the message to the operator
        Throws:
        com.redwood.scheduler.api.exception.SchedulerAPIPersistenceException - if the message could not be written

      • operatorMessage

        String operatorMessage​(SchedulerSession session,
                       String message,
                       String replyExpression)
                throws com.redwood.scheduler.api.exception.SchedulerAPIPersistenceException,
                       InterruptedException
        Insert an operator message in the operator messages table and wait until a reply is given. Note that persist() will be called
        Parameters:
        session - the SchedulerSession
        message - the message to the operator
        replyExpression - a regular expression to which the reply should match, or null for any reply
        Returns:
        the reply
        Throws:
        InterruptedException - if the thread is interrupted
        com.redwood.scheduler.api.exception.SchedulerAPIPersistenceException - if the message could not be written

      • operatorMessage

        String operatorMessage​(String message,
                       String replyExpression)
                throws com.redwood.scheduler.api.exception.SchedulerAPIPersistenceException,
                       InterruptedException
        Insert an operator message in the operator messages table and wait until a reply is given.
        Parameters:
        message - the message to the operator
        replyExpression - a regular expression to which the reply should match, or null for any reply
        Returns:
        the reply
        Throws:
        InterruptedException - if the thread is interrupted
        com.redwood.scheduler.api.exception.SchedulerAPIPersistenceException - if the message could not be written

      • waitForReply

        String waitForReply​(OperatorMessage om)
             throws com.redwood.scheduler.api.exception.SchedulerAPIPersistenceException,
                    InterruptedException
        Wait for a reply to an operator message raised by this job.
        Parameters:
        om - the operator message to wait for.
        Returns:
        the reply
        Throws:
        com.redwood.scheduler.api.exception.SchedulerAPIPersistenceException - if the job could not be set to Console
        InterruptedException - if the thread is interrupted

      • setReturnCode

        void setReturnCode​(Long newReturnCode)
        Set the job return code. This will be set regardless of the final state of the job (Completed or Error).
        Parameters:
        newReturnCode - the new value for return code. Set to null not to set a return code.

      • setReturnCode

        void setReturnCode​(long newReturnCode)
        Set the job return code. This will be set regardless of the final state of the job (Completed or Error).
        Parameters:
        newReturnCode - the new value for return code. Set to null not to set a return code.

      • waitForJob

        void waitForJob​(SchedulerSession session,
                Job job)
        Wait for another job to finish. This may be implemented by the dispatcher (ie. more efficient than a busy wait).
        Parameters:
        session - the session the jobs came from.
        job - the job to wait for.

      • waitForJobs

        void waitForJobs​(SchedulerSession session,
                 Job[] jobs)
        Wait for all the specified jobs to finish. This may be implemented by the dispatcher (ie. more efficient than a busy wait).
        Parameters:
        session - the session the jobs came from.
        jobs - the jobs to wait for.

      • waitForJobs

        void waitForJobs​(SchedulerSession session,
                 Job[] jobs,
                 JobStatus[] statuses,
                 long maxWait)
        Wait for jobs to reach the specified statuses, with a maximum wait time. This will always be implemented as a busy wait.
        Parameters:
        session - the session to use for waiting (to refresh objects).
        jobs - the jobs to wait for, must be from session.
        statuses - the statuses to wait for.
        maxWait - the maximum time (in milliseconds) to wait.

      • waitForAllChildren

        void waitForAllChildren​(SchedulerSession session)
        Wait for all children to finish. This may be implemented by the dispatcher (ie. more efficient than a busy wait).
        Parameters:
        session - the session the jobs came from.

      • setCompletionStrategy

        void setCompletionStrategy​(CompletionStrategyType newStrategy)
        Set the completion strategy for this job. The default completion strategy is to set the job into Completed or Error depending on the return code and whether the job throws an exception. Other completion strategies allow for an external entity to set the final status of the job, after the job's thread has finished. This call should be made at the end of the job.
        Parameters:
        newStrategy - the completion strategy to use.

      • setJobOutputParameter

        void setJobOutputParameter​(String name,
                           Object value)
        Set the current (in-memory) value of an output parameter. This value will be written to the database when the job completes.
        Parameters:
        name - the parameter name
        value - the value

      • getJobUniqueId

        Long getJobUniqueId()
        Get the Unique Id of the Job, this is not the same as the JobId.
        Returns:
        the Unique Id of the job.

      • getJobId

        Long getJobId()
        Get the Job Id of the Job.
        Returns:
        the Unique Id of the job.

      • addToCloseList

        boolean addToCloseList​(AutoCloseable o,
                       String name,
                       boolean log)
        Close the object when the job completes.
        Parameters:
        o - the object to close.
        name - the name of the object.
        log - should information about this object be logged by default.
        Returns:
        true if the object was added, false if it was not closable.

      • forceCloseListLogging

        void forceCloseListLogging()
        Force logging of all objects in close list.

      • getSystemId

        String getSystemId()
        Get the current system id.
        Returns:
        the current system id.

      • setMaxRetries

        @Deprecated
void setMaxRetries​(int newMaxRetries)
        Deprecated.
        This can be configured with the UnitOfWorkConfig and should not be used.
        Set the maximum number of retries for units of work.
        Parameters:
        newMaxRetries - the new maximum number of retries, must be > 1.

      • setMaxSpins

        @Deprecated
void setMaxSpins​(int newMaxSpins)
        Deprecated.
        This can be configured with the UnitOfWorkConfig and should not be used.
        Set the maximum number of spins for units of work.
        Parameters:
        newMaxSpins - the new maximum number of spins, must be > 1.

      • performUnitOfWork

        <T extends Exception> void performUnitOfWork​(SchedulerSessionUnitOfWork<T> uow)
                                      throws com.redwood.scheduler.api.exception.SchedulerAPIPersistenceException,
                                             T extends Exception
        Perform a unit of work, by calling it with a new session. If the initial call fails with a no rows updated exception, call it again with a new session. If it fails with any other exception, or fails too many times with no rows updated, throw the last exception thrown. Retries can be configured with setMaxRetries(int).
        Parameters:
        uow - the unit of work to perform. Generic in the type of Exception its performWork method it throws. See SchedulerSessionUnitOfWork for the problems with using a raw type here.
        Throws:
        com.redwood.scheduler.api.exception.SchedulerAPIPersistenceException - if the unit of work fails with a no rows updated exception maxretries times.
        T - if the unit of work throws an exception.
        T extends Exception

      • waitForAllChildJobsExternalCompletionStrategy

        void waitForAllChildJobsExternalCompletionStrategy()
        The current job will have its strategy set to external and will remain running until its child jobs finish. When the children are completed (or any other final state) the current job will finish (to completed if all children are completed or error for any other final state of a child). This method will return immediately. This call is only usable within RedwoodScript and must be the *last* statement of the script.

      • killJobWithParent

        void killJobWithParent​(Job job)
        When this method is called, the child jobs will be killed when the given parent job is killed (the default is not). Make sure to persist after to have the change applied.
        Parameters:
        job - The parent job to apply this to

      • becomeResilient

        void becomeResilient()
              throws com.redwood.scheduler.api.exception.SchedulerAPIPersistenceException
        When called, the current running Process (jcsJob) is fetched using a newly created session and set to CompletionStrategy Resilient. This session is then persisted using a UnitOfWork, meaning it will retry in case of failure due to a concurrent change to the Process. Because the persist happens in a session created in this method, callers need to refresh jcsJob *after* this call or will run into NoRowsUpdatedExceptions.
        Throws:
        com.redwood.scheduler.api.exception.SchedulerAPIPersistenceException - On failure of persist

      • becomeResilient

        @Deprecated
void becomeResilient​(SchedulerSession session)
              throws com.redwood.scheduler.api.exception.SchedulerAPIPersistenceException
        Deprecated.
        This method runs the the risk of the persist failing with a NoRowsUpdatedException in unexpected and non-reproducible ways when the job is also modified in another session. Use becomeResilient(), which doesn't take a session argument and persists using a UnitOfWork in its own session, instead.
        When called, it sets the current running Process (jcsJob) to CompletionStrategy Resilient, this uses passed-in session to persist.
        Parameters:
        session - the session to use.
        Throws:
        com.redwood.scheduler.api.exception.SchedulerAPIPersistenceException - On failure of persist

      • loopOverNextJobChainStep

        Iterable<Job> loopOverNextJobChainStep​(SchedulerSession session,
                                       RTXProducer producer,
                                       Predicate<RTXRow> filter,
                                       String jobDescription)
                                throws Exception
        Loop over the next step in the current job chain. The following preconditions must be true:
        • The current job is in a job chain, and must be the only job in its step.
        • The next step must have exactly one job in it.
        • The producer must return at least one row, after being filtered by filter.
        The process proceeds as follows:
        • Confirm the current job and the next step in the chain meet the preconditions.
        • The first row in the producer will be mapped onto the first job in the next step.
        • Additional jobs will be created based on the first job for subsequent rows from the producer.
        Column values from the RTXReader can be accessed from Expression Parameter mappings using the REL functions in the Loop package, eg. Loop.getString(String column), which will return the column value for the current row.
        Parameters:
        session - the session to use.
        producer - the reader to get data from.
        filter - a filter for the rows, returns true to process the current row, may change state from getThreadState().
        jobDescription - optional RTXRow REL Expression, if supplied will define the description of the looped jobs.
        Returns:
        the jobs in the next step.
        Throws:
        Exception - if an error occurs.

      • loopOverNextJobChainStep

        default Iterable<Job> loopOverNextJobChainStep​(SchedulerSession session,
                                               RTXProducer producer,
                                               Predicate<RTXRow> filter)
                                        throws Exception
        Loop over the next step in the current job chain. The following preconditions must be true:
        • The current job is in a job chain, and must be the only job in its step.
        • The next step must have exactly one job in it.
        • The producer must return at least one row, after being filtered by filter.
        The process proceeds as follows:
        • Confirm the current job and the next step in the chain meet the preconditions.
        • The first row in the producer will be mapped onto the first job in the next step.
        • Additional jobs will be created based on the first job for subsequent rows from the producer.
        Column values from the RTXReader can be accessed from Expression Parameter mappings using the REL functions in the Loop package, eg. Loop.getString(String column), which will return the column value for the current row.
        Parameters:
        session - the session to use.
        producer - the reader to get data from.
        filter - a filter for the rows, returns true to process the current row, may change state from getThreadState().
        Returns:
        the jobs in the next step.
        Throws:
        Exception - if an error occurs.

      • loopOverNextJobChainStep

        default Iterable<Job> loopOverNextJobChainStep​(SchedulerSession session,
                                               RTXProducer producer,
                                               String jobDescription)
                                        throws Exception
        Loop over the next step in the current job chain. The following preconditions must be true:
        • The current job is in a job chain, and must be the only job in its step.
        • The next step must have exactly one job in it.
        • The producer must return at least one row, after being filtered by filter.
        The process proceeds as follows:
        • Confirm the current job and the next step in the chain meet the preconditions.
        • The first row in the producer will be mapped onto the first job in the next step.
        • Additional jobs will be created based on the first job for subsequent rows from the producer.
        Column values from the RTXReader can be accessed from Expression Parameter mappings using the REL functions in the Loop package, eg. Loop.getString(String column), which will return the column value for the current row.
        Parameters:
        session - the session to use.
        producer - the reader to get data from.
        jobDescription - optional RTXRow REL Expression, if supplied will define the description of the looped jobs.
        Returns:
        the jobs in the next step.
        Throws:
        Exception - if an error occurs.

      • loopOverNextJobChainStep

        default Iterable<Job> loopOverNextJobChainStep​(SchedulerSession session,
                                               RTXProducer producer)
                                        throws Exception
        Loop over the next step in the current job chain. The following preconditions must be true:
        • The current job is in a job chain, and must be the only job in its step.
        • The next step must have exactly one job in it.
        • The producer must return at least one row, after being filtered by filter.
        The process proceeds as follows:
        • Confirm the current job and the next step in the chain meet the preconditions.
        • The first row in the producer will be mapped onto the first job in the next step.
        • Additional jobs will be created based on the first job for subsequent rows from the producer.
        Column values from the RTXReader can be accessed from Expression Parameter mappings using the REL functions in the Loop package, eg. Loop.getString(String column), which will return the column value for the current row.
        Parameters:
        session - the session to use.
        producer - the reader to get data from.
        Returns:
        the jobs in the next step.
        Throws:
        Exception - if an error occurs.

      • getThreadState

        Map<String,​Object> getThreadState()
        Get the ThreadState map shared between REL and RedwoodScript during the execution of this job.
        Returns:
        the map.