Allow scheduling of jobs. Jobs can be executed periodically or a single time, can be written as scripts or Java classes

Description

API

/**
     * Return the trigger state of the given {@link com.xpn.xwiki.plugin.scheduler.SchedulerPlugin#XWIKI_JOB_CLASS}
     * XObject job. Possible values are : None (the trigger does not exists yet, or has been
     * deleted), Normal, Blocked, Complete, Error and Paused
     *
     * @param object the XObject job to give the state of
     * @return a String representing this state
     */
    public String getStatus(Object object);

    /**
     * Return the trigger state as a ${@link JobState}, that holds both the integer trigger's inner
     * value of the state and a String as a human readable representation of that state
     */
    public JobState getJobStatus(BaseObject object)
        throws SchedulerException, SchedulerPluginException;

    public JobState getJobStatus(Object object) throws SchedulerException, SchedulerPluginException;

    /**
     * This function allow to retrieve a com.xpn.xwiki.objects.BaseObject from a
     * com.xpn.xwiki.api.Object without that the current user needs programming rights (as in
     * com.xpn.xwiki.api.Object#getXWikiObject(). The function is used internally by this api class
     * and allows wiki users to call methods from the scheduler without having programming right.
     * The programming right is only needed at script execution time.
     *
     * @return object the unwrapped version of the passed api object
     */
    private BaseObject retrieveBaseObject(Object object) throws SchedulerPluginException;

    /**
     * Schedule the given XObject to be executed according to its parameters. Errors are returned in
     * the context map. Scheduling can be called for example: <code> #if($xwiki.scheduler.scheduleJob($job)!=true)
     * #error($context.get("error") #else #info("Job scheduled") #end </code> Where $job is an
     * XObject, instance of the {@link SchedulerPlugin#XWIKI_JOB_CLASS} XClass
     *
     * @param object the XObject to be scheduled, an instance of the XClass XWiki.SchedulerJobClass
     * @return true on success, false on failure
     */
    public boolean scheduleJob(Object object);

    public boolean scheduleJob(BaseObject object);

    /**
     * Schedule all {@link com.xpn.xwiki.plugin.scheduler.SchedulerPlugin#XWIKI_JOB_CLASS} XObjects
     * stored inside the given Wiki document, according to each XObject own parameters.
     *
     * @param document the document holding the XObjects Jobs to be scheduled
     * @return true on success, false on failure.
     */
    public boolean scheduleJobs(Document document);

    /**
     * Pause the given XObject job by pausing all of its current triggers. Can be called the same
     * way as {@link #scheduleJob}
     *
     * @param object the wrapped XObject Job to be paused
     * @return true on success, false on failure.
     */
    public boolean pauseJob(Object object);

    public boolean pauseJob(BaseObject object);

    /**
     * Resume a XObject job that is in a {@link JobState#STATE_PAUSED} state. Can be called the same
     * way as {@link #scheduleJob}
     *
     * @param object the wrapped XObject Job to be paused
     * @return true on success, false on failure.
     */
    public boolean resumeJob(Object object);

    public boolean resumeJob(BaseObject object);

    /**
     * Unschedule a XObject job by deleting it from the jobs table. Can be called the same way as
     * {@link #scheduleJob}
     *
     * @param object the wrapped XObject Job to be paused
     * @return true on success, false on failure.
     */
    public boolean unscheduleJob(Object object);

    public boolean unscheduleJob(BaseObject object);

    /**
     * Give, for a XObject job in a {@JobState#STATE_NORMAL} state, the next date at which the job
     * will be executed, according to its cron expression. Errors are returned in the context map.
     * Can be called for example: <code> #set($firetime = $xwiki.scheduler.getNextFireTime($job))
     * #if (!$firetime || $firetime=="") #error($context.get("error") #else #info("Fire time :
     * $firetime") #end </code> Where $job is an XObject, instance of the {@link
     * SchedulerPlugin#XWIKI_JOB_CLASS} XClass
     *
     * @param object the wrapped XObject for which to give the fire date
     * @return the date the job will be executed
     */
    public Date getNextFireTime(Object object);

    public Date getNextFireTime(BaseObject object);

Example

Check the Scheduler Application for examples of how to use the Scheduler plugin API.

Tips & tricks

• Avoid the same job running twice in the same time

Clustering

The Scheduler feature is not cluster-aware and thus each node of XWiki runs its own scheduler and thus the same scheduler jobs will execute on all nodes. The workaround is to disable the Scheduler plugin on all nodes except on one:

• XWiki <17.5.0, <17.4.1 remove com.xpn.xwiki.plugin.scheduler.SchedulerPlugin from the xwiki.plugins configuration value in xwiki.cfg
• XWiki 17.5.0+, 17.4.1+ scheduler.enabled=false in the xwiki.properties configuration file

Note that this creates a SPOF and if the node containing the active Scheduler is down, the scheduled jobs won't execute.

You can follow the progress on this limitation on XWIKI-6235.

Prerequisites & Installation Instructions

To use, add the com.xpn.xwiki.plugin.scheduler.SchedulerPlugin plugin definition to the xwiki.plugins property in your xwiki.cfg file (this definition is already there if you use XWiki Enterprise 1.2 Milestone 2 or above) and copy the Quartz JAR to your WEB-INF/lib directory.