org.quartz.spi.JobStore Maven / Gradle / Ivy
The newest version!
/*
* Copyright 2001-2009 Terracotta, Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may not
* use this file except in compliance with the License. You may obtain a copy
* of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
* License for the specific language governing permissions and limitations
* under the License.
*
*/
package org.quartz.spi;
import java.util.Collection;
import java.util.List;
import java.util.Map;
import java.util.Set;
import org.quartz.Calendar;
import org.quartz.Job;
import org.quartz.JobDetail;
import org.quartz.JobKey;
import org.quartz.JobPersistenceException;
import org.quartz.ObjectAlreadyExistsException;
import org.quartz.SchedulerConfigException;
import org.quartz.SchedulerException;
import org.quartz.Trigger;
import org.quartz.TriggerKey;
import org.quartz.Trigger.CompletedExecutionInstruction;
import org.quartz.Trigger.TriggerState;
import org.quartz.impl.matchers.GroupMatcher;
/**
*
* The interface to be implemented by classes that want to provide a {@link org.quartz.Job}
* and {@link org.quartz.Trigger} storage mechanism for the
* {@link org.quartz.core.QuartzScheduler}'s use.
*
*
*
* Storage of Job s and Trigger s should be keyed
* on the combination of their name and group for uniqueness.
*
*
* @see org.quartz.core.QuartzScheduler
* @see org.quartz.Trigger
* @see org.quartz.Job
* @see org.quartz.JobDetail
* @see org.quartz.JobDataMap
* @see org.quartz.Calendar
*
* @author James House
* @author Eric Mueller
*/
public interface JobStore {
/*
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*
* Interface.
*
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*/
/**
* Called by the QuartzScheduler before the JobStore is
* used, in order to give the it a chance to initialize.
*/
void initialize(ClassLoadHelper loadHelper, SchedulerSignaler signaler)
throws SchedulerConfigException;
/**
* Called by the QuartzScheduler to inform the JobStore that
* the scheduler has started.
*/
void schedulerStarted() throws SchedulerException ;
/**
* Called by the QuartzScheduler to inform the JobStore that
* the scheduler has been paused.
*/
void schedulerPaused();
/**
* Called by the QuartzScheduler to inform the JobStore that
* the scheduler has resumed after being paused.
*/
void schedulerResumed();
/**
* Called by the QuartzScheduler to inform the JobStore that
* it should free up all of it's resources because the scheduler is
* shutting down.
*/
void shutdown();
boolean supportsPersistence();
/**
* How long (in milliseconds) the JobStore implementation
* estimates that it will take to release a trigger and acquire a new one.
*/
long getEstimatedTimeToReleaseAndAcquireTrigger();
/**
* Whether or not the JobStore implementation is clustered.
*/
boolean isClustered();
/////////////////////////////////////////////////////////////////////////////
//
// Job & Trigger Storage methods
//
/////////////////////////////////////////////////////////////////////////////
/**
* Store the given {@link org.quartz.JobDetail} and {@link org.quartz.Trigger}.
*
* @param newJob
* The JobDetail to be stored.
* @param newTrigger
* The Trigger to be stored.
* @throws ObjectAlreadyExistsException
* if a Job with the same name/group already
* exists.
*/
void storeJobAndTrigger(JobDetail newJob, OperableTrigger newTrigger)
throws ObjectAlreadyExistsException, JobPersistenceException;
/**
* Store the given {@link org.quartz.JobDetail}.
*
* @param newJob
* The JobDetail to be stored.
* @param replaceExisting
* If true, any Job existing in the
* JobStore with the same name & group should be
* over-written.
* @throws ObjectAlreadyExistsException
* if a Job with the same name/group already
* exists, and replaceExisting is set to false.
*/
void storeJob(JobDetail newJob, boolean replaceExisting)
throws ObjectAlreadyExistsException, JobPersistenceException;
public void storeJobsAndTriggers(Map> triggersAndJobs, boolean replace)
throws ObjectAlreadyExistsException, JobPersistenceException;
/**
* Remove (delete) the {@link org.quartz.Job} with the given
* key, and any {@link org.quartz.Trigger} s that reference
* it.
*
*
* If removal of the Job results in an empty group, the
* group should be removed from the JobStore's list of
* known group names.
*
*
* @return true if a Job with the given name &
* group was found and removed from the store.
*/
boolean removeJob(JobKey jobKey)
throws JobPersistenceException;
public boolean removeJobs(List jobKeys)
throws JobPersistenceException;
/**
* Retrieve the {@link org.quartz.JobDetail} for the given
* {@link org.quartz.Job}.
*
* @return The desired Job, or null if there is no match.
*/
JobDetail retrieveJob(JobKey jobKey)
throws JobPersistenceException;
/**
* Store the given {@link org.quartz.Trigger}.
*
* @param newTrigger
* The Trigger to be stored.
* @param replaceExisting
* If true, any Trigger existing in
* the JobStore with the same name & group should
* be over-written.
* @throws ObjectAlreadyExistsException
* if a Trigger with the same name/group already
* exists, and replaceExisting is set to false.
*
* @see #pauseTriggers(org.quartz.impl.matchers.GroupMatcher)
*/
void storeTrigger(OperableTrigger newTrigger, boolean replaceExisting)
throws ObjectAlreadyExistsException, JobPersistenceException;
/**
* Remove (delete) the {@link org.quartz.Trigger} with the
* given key.
*
*
* If removal of the Trigger results in an empty group, the
* group should be removed from the JobStore's list of
* known group names.
*
*
*
* If removal of the Trigger results in an 'orphaned' Job
* that is not 'durable', then the Job should be deleted
* also.
*
*
* @return true if a Trigger with the given
* name & group was found and removed from the store.
*/
boolean removeTrigger(TriggerKey triggerKey) throws JobPersistenceException;
public boolean removeTriggers(List triggerKeys)
throws JobPersistenceException;
/**
* Remove (delete) the {@link org.quartz.Trigger} with the
* given key, and store the new given one - which must be associated
* with the same job.
*
* @param newTrigger
* The new Trigger to be stored.
*
* @return true if a Trigger with the given
* name & group was found and removed from the store.
*/
boolean replaceTrigger(TriggerKey triggerKey, OperableTrigger newTrigger)
throws JobPersistenceException;
/**
* Retrieve the given {@link org.quartz.Trigger}.
*
* @return The desired Trigger, or null if there is no
* match.
*/
OperableTrigger retrieveTrigger(TriggerKey triggerKey) throws JobPersistenceException;
/**
* Determine whether a {@link Job} with the given identifier already
* exists within the scheduler.
*
* @param jobKey the identifier to check for
* @return true if a Job exists with the given identifier
* @throws SchedulerException
*/
boolean checkExists(JobKey jobKey) throws JobPersistenceException;
/**
* Determine whether a {@link Trigger} with the given identifier already
* exists within the scheduler.
*
* @param triggerKey the identifier to check for
* @return true if a Trigger exists with the given identifier
* @throws SchedulerException
*/
boolean checkExists(TriggerKey triggerKey) throws JobPersistenceException;
/**
* Clear (delete!) all scheduling data - all {@link Job}s, {@link Trigger}s
* {@link Calendar}s.
*
* @throws JobPersistenceException
*/
void clearAllSchedulingData() throws JobPersistenceException;
/**
* Store the given {@link org.quartz.Calendar}.
*
* @param calendar
* The Calendar to be stored.
* @param replaceExisting
* If true, any Calendar existing
* in the JobStore with the same name & group
* should be over-written.
* @param updateTriggers
* If true, any Triggers existing
* in the JobStore that reference an existing
* Calendar with the same name with have their next fire time
* re-computed with the new Calendar.
* @throws ObjectAlreadyExistsException
* if a Calendar with the same name already
* exists, and replaceExisting is set to false.
*/
void storeCalendar(String name, Calendar calendar, boolean replaceExisting, boolean updateTriggers)
throws ObjectAlreadyExistsException, JobPersistenceException;
/**
* Remove (delete) the {@link org.quartz.Calendar} with the
* given name.
*
*
* If removal of the Calendar would result in
* Triggers pointing to non-existent calendars, then a
* JobPersistenceException will be thrown.
* *
* @param calName The name of the Calendar to be removed.
* @return true if a Calendar with the given name
* was found and removed from the store.
*/
boolean removeCalendar(String calName)
throws JobPersistenceException;
/**
* Retrieve the given {@link org.quartz.Trigger}.
*
* @param calName
* The name of the Calendar to be retrieved.
* @return The desired Calendar, or null if there is no
* match.
*/
Calendar retrieveCalendar(String calName)
throws JobPersistenceException;
/////////////////////////////////////////////////////////////////////////////
//
// Informational methods
//
/////////////////////////////////////////////////////////////////////////////
/**
* Get the number of {@link org.quartz.Job} s that are
* stored in the JobsStore.
*/
int getNumberOfJobs()
throws JobPersistenceException;
/**
* Get the number of {@link org.quartz.Trigger} s that are
* stored in the JobsStore.
*/
int getNumberOfTriggers()
throws JobPersistenceException;
/**
* Get the number of {@link org.quartz.Calendar} s that are
* stored in the JobsStore.
*/
int getNumberOfCalendars()
throws JobPersistenceException;
/**
* Get the keys of all of the {@link org.quartz.Job} s that
* have the given group name.
*
*
* If there are no jobs in the given group name, the result should be
* an empty collection (not null).
*
*/
Set getJobKeys(GroupMatcher matcher)
throws JobPersistenceException;
/**
* Get the names of all of the {@link org.quartz.Trigger} s
* that have the given group name.
*
*
* If there are no triggers in the given group name, the result should be a
* zero-length array (not null).
*
*/
Set getTriggerKeys(GroupMatcher matcher)
throws JobPersistenceException;
/**
* Get the names of all of the {@link org.quartz.Job}
* groups.
*
*
* If there are no known group names, the result should be a zero-length
* array (not null).
*
*/
List getJobGroupNames()
throws JobPersistenceException;
/**
* Get the names of all of the {@link org.quartz.Trigger}
* groups.
*
*
* If there are no known group names, the result should be a zero-length
* array (not null).
*
*/
List getTriggerGroupNames()
throws JobPersistenceException;
/**
* Get the names of all of the {@link org.quartz.Calendar} s
* in the JobStore.
*
*
* If there are no Calendars in the given group name, the result should be
* a zero-length array (not null).
*
*/
List getCalendarNames()
throws JobPersistenceException;
/**
* Get all of the Triggers that are associated to the given Job.
*
*
* If there are no matches, a zero-length array should be returned.
*
*/
List getTriggersForJob(JobKey jobKey) throws JobPersistenceException;
/**
* Get the current state of the identified {@link Trigger}.
*
* @see Trigger.TriggerState
*/
TriggerState getTriggerState(TriggerKey triggerKey) throws JobPersistenceException;
/////////////////////////////////////////////////////////////////////////////
//
// Trigger State manipulation methods
//
/////////////////////////////////////////////////////////////////////////////
/**
* Pause the {@link org.quartz.Trigger} with the given key.
*
* @see #resumeTrigger(TriggerKey)
*/
void pauseTrigger(TriggerKey triggerKey) throws JobPersistenceException;
/**
* Pause all of the {@link org.quartz.Trigger}s in the
* given group.
*
*
*
* The JobStore should "remember" that the group is paused, and impose the
* pause on any new triggers that are added to the group while the group is
* paused.
*
*
* @see #resumeTriggerGroup(String)
*/
Collection pauseTriggers(GroupMatcher matcher) throws JobPersistenceException;
/**
* Pause the {@link org.quartz.Job} with the given name - by
* pausing all of its current Triggers.
*
* @see #resumeJob(JobKey)
*/
void pauseJob(JobKey jobKey) throws JobPersistenceException;
/**
* Pause all of the {@link org.quartz.Job}s in the given
* group - by pausing all of their Triggers.
*
*
* The JobStore should "remember" that the group is paused, and impose the
* pause on any new jobs that are added to the group while the group is
* paused.
*
*
* @see #resumeJobGroup(String)
*/
Collection pauseJobs(GroupMatcher groupMatcher)
throws JobPersistenceException;
/**
* Resume (un-pause) the {@link org.quartz.Trigger} with the
* given key.
*
*
* If the Trigger missed one or more fire-times, then the
* Trigger's misfire instruction will be applied.
*
*
* @see #pauseTrigger(TriggerKey)
*/
void resumeTrigger(TriggerKey triggerKey) throws JobPersistenceException;
/**
* Resume (un-pause) all of the {@link org.quartz.Trigger}s
* in the given group.
*
*
* If any Trigger missed one or more fire-times, then the
* Trigger's misfire instruction will be applied.
*
*
* @see #pauseTriggers(String)
*/
Collection resumeTriggers(GroupMatcher matcher)
throws JobPersistenceException;
Set getPausedTriggerGroups()
throws JobPersistenceException;
/**
* Resume (un-pause) the {@link org.quartz.Job} with the
* given key.
*
*
* If any of the Job'sTrigger s missed one
* or more fire-times, then the Trigger's misfire
* instruction will be applied.
*
*
* @see #pauseJob(JobKey)
*/
void resumeJob(JobKey jobKey) throws JobPersistenceException;
/**
* Resume (un-pause) all of the {@link org.quartz.Job}s in
* the given group.
*
*
* If any of the Job s had Trigger s that
* missed one or more fire-times, then the Trigger's
* misfire instruction will be applied.
*
*
* @see #pauseJobGroup(String)
*/
Collection resumeJobs(GroupMatcher matcher)
throws JobPersistenceException;
/**
* Pause all triggers - equivalent of calling pauseTriggerGroup(group)
* on every group.
*
*
* When resumeAll() is called (to un-pause), trigger misfire
* instructions WILL be applied.
*
*
* @see #resumeAll()
* @see #pauseTriggers(String)
*/
void pauseAll() throws JobPersistenceException;
/**
* Resume (un-pause) all triggers - equivalent of calling resumeTriggerGroup(group)
* on every group.
*
*
* If any Trigger missed one or more fire-times, then the
* Trigger's misfire instruction will be applied.
*
*
* @see #pauseAll()
*/
void resumeAll()
throws JobPersistenceException;
/////////////////////////////////////////////////////////////////////////////
//
// Trigger-Firing methods
//
/////////////////////////////////////////////////////////////////////////////
/**
* Get a handle to the next trigger to be fired, and mark it as 'reserved'
* by the calling scheduler.
*
* @param noLaterThan If > 0, the JobStore should only return a Trigger
* that will fire no later than the time represented in this value as
* milliseconds.
* @see #releaseAcquiredTrigger(Trigger)
*/
List acquireNextTriggers(long noLaterThan, int maxCount, long timeWindow)
throws JobPersistenceException;
/**
* Inform the JobStore that the scheduler no longer plans to
* fire the given Trigger, that it had previously acquired
* (reserved).
*/
void releaseAcquiredTrigger(OperableTrigger trigger);
/**
* Inform the JobStore that the scheduler is now firing the
* given Trigger (executing its associated Job),
* that it had previously acquired (reserved).
*
* @return may return null if all the triggers or their calendars no longer exist, or
* if the trigger was not successfully put into the 'executing'
* state. Preference is to return an empty list if none of the triggers
* could be fired.
*/
List triggersFired(List triggers) throws JobPersistenceException;
/**
* Inform the JobStore that the scheduler has completed the
* firing of the given Trigger (and the execution of its
* associated Job completed, threw an exception, or was vetoed),
* and that the {@link org.quartz.JobDataMap}
* in the given JobDetail should be updated if the Job
* is stateful.
*/
void triggeredJobComplete(OperableTrigger trigger, JobDetail jobDetail, CompletedExecutionInstruction triggerInstCode);
/**
* Inform the JobStore of the Scheduler instance's Id,
* prior to initialize being invoked.
*
* @since 1.7
*/
void setInstanceId(String schedInstId);
/**
* Inform the JobStore of the Scheduler instance's name,
* prior to initialize being invoked.
*
* @since 1.7
*/
void setInstanceName(String schedName);
/**
* Tells the JobStore the pool size used to execute jobs
* @param poolSize amount of threads allocated for job execution
* @since 2.0
*/
void setThreadPoolSize(int poolSize);
}