org.quartz.impl.jdbcjobstore.DriverDelegate Maven / Gradle / Ivy
/*
* 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.impl.jdbcjobstore;
import java.io.IOException;
import java.sql.Connection;
import java.sql.SQLException;
import java.util.List;
import java.util.Set;
import org.quartz.Calendar;
import org.quartz.Job;
import org.quartz.JobDataMap;
import org.quartz.JobDetail;
import org.quartz.JobKey;
import org.quartz.JobPersistenceException;
import org.quartz.Trigger;
import org.quartz.TriggerKey;
import org.quartz.impl.matchers.GroupMatcher;
import org.quartz.spi.ClassLoadHelper;
import org.quartz.spi.OperableTrigger;
import org.quartz.utils.Key;
/**
*
* This is the base interface for all driver delegate classes.
*
*
*
* This interface is very similar to the {@link
* org.quartz.spi.JobStore}
* interface except each method has an additional {@link java.sql.Connection}
* parameter.
*
*
*
* Unless a database driver has some extremely-DB-specific
* requirements, any DriverDelegate implementation classes should extend the
* {@link org.quartz.impl.jdbcjobstore.StdJDBCDelegate} class.
*
*
* @author Jeffrey Wescott
* @author James House
*/
public interface DriverDelegate {
/*
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*
* Interface.
*
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*/
void initialize(String initString) throws NoSuchDelegateException;
//---------------------------------------------------------------------------
// startup / recovery
//---------------------------------------------------------------------------
/**
*
* Update all triggers having one of the two given states, to the given new
* state.
*
*
* @param conn
* the DB Connection
* @param newState
* the new state for the triggers
* @param oldState1
* the first old state to update
* @param oldState2
* the second old state to update
* @return number of rows updated
*/
int updateTriggerStatesFromOtherStates(Connection conn,
String newState, String oldState1, String oldState2)
throws SQLException;
/**
*
* Get the names of all of the triggers that have misfired - according to
* the given timestamp.
*
*
* @param conn
* the DB Connection
* @return an array of {@link
* org.quartz.utils.Key} objects
*/
List selectMisfiredTriggers(Connection conn, long ts)
throws SQLException;
/**
*
* Get the names of all of the triggers in the given state that have
* misfired - according to the given timestamp.
*
*
* @param conn
* the DB Connection
* @return an array of {@link
* org.quartz.utils.Key} objects
*/
List selectMisfiredTriggersInState(Connection conn, String state,
long ts) throws SQLException;
/**
*
* Get the names of all of the triggers in the given states that have
* misfired - according to the given timestamp. No more than count will
* be returned.
*
*
* @param conn the DB Connection
* @param count the most misfired triggers to return, negative for all
* @param resultList Output parameter. A List of
* {@link org.quartz.utils.Key} objects. Must not be null.
*
* @return Whether there are more misfired triggers left to find beyond
* the given count.
*/
boolean hasMisfiredTriggersInState(Connection conn, String state1,
long ts, int count, List resultList) throws SQLException;
/**
*
* Get the number of triggers in the given state that have
* misfired - according to the given timestamp.
*
*
* @param conn the DB Connection
*/
int countMisfiredTriggersInState(
Connection conn, String state1, long ts) throws SQLException;
/**
*
* Get the names of all of the triggers in the given group and state that
* have misfired - according to the given timestamp.
*
*
* @param conn
* the DB Connection
* @return an array of {@link
* org.quartz.utils.Key} objects
*/
List selectMisfiredTriggersInGroupInState(Connection conn,
String groupName, String state, long ts) throws SQLException;
/**
*
* Select all of the triggers for jobs that are requesting recovery. The
* returned trigger objects will have unique "recoverXXX" trigger names and
* will be in the {@link
* org.quartz.Scheduler}.DEFAULT_RECOVERY_GROUP
* trigger group.
*
*
*
* In order to preserve the ordering of the triggers, the fire time will be
* set from the COL_FIRED_TIME column in the TABLE_FIRED_TRIGGERS
* table. The caller is responsible for calling computeFirstFireTime
* on each returned trigger. It is also up to the caller to insert the
* returned triggers to ensure that they are fired.
*
*
* @param conn
* the DB Connection
* @return an array of {@link org.quartz.Trigger} objects
*/
List selectTriggersForRecoveringJobs(Connection conn)
throws SQLException, IOException, ClassNotFoundException;
/**
*
* Delete all fired triggers.
*
*
* @param conn
* the DB Connection
* @return the number of rows deleted
*/
int deleteFiredTriggers(Connection conn) throws SQLException;
/**
*
* Delete all fired triggers of the given instance.
*
*
* @param conn
* the DB Connection
* @return the number of rows deleted
*/
int deleteFiredTriggers(Connection conn, String instanceId)
throws SQLException;
//---------------------------------------------------------------------------
// jobs
//---------------------------------------------------------------------------
/**
*
* Insert the job detail record.
*
*
* @param conn
* the DB Connection
* @param job
* the job to insert
* @return number of rows inserted
* @throws IOException
* if there were problems serializing the JobDataMap
*/
int insertJobDetail(Connection conn, JobDetail job)
throws IOException, SQLException;
/**
*
* Update the job detail record.
*
*
* @param conn
* the DB Connection
* @param job
* the job to update
* @return number of rows updated
* @throws IOException
* if there were problems serializing the JobDataMap
*/
int updateJobDetail(Connection conn, JobDetail job)
throws IOException, SQLException;
/**
*
* Get the names of all of the triggers associated with the given job.
*
*
* @param conn
* the DB Connection
*
* @return an array of {@link
* org.quartz.utils.Key} objects
*/
List selectTriggerKeysForJob(Connection conn, JobKey jobKey) throws SQLException;
/**
*
* Delete the job detail record for the given job.
*
*
* @param conn
* the DB Connection
*
* @return the number of rows deleted
*/
int deleteJobDetail(Connection conn, JobKey jobKey)
throws SQLException;
/**
*
* Check whether or not the given job disallows concurrent execution.
*
*
* @param conn
* the DB Connection
*
* @return true if the job exists and disallows concurrent execution, false otherwise
*/
boolean isJobNonConcurrent(Connection conn, JobKey jobKey) throws SQLException;
/**
*
* Check whether or not the given job exists.
*
*
* @param conn
* the DB Connection
*
* @return true if the job exists, false otherwise
*/
boolean jobExists(Connection conn, JobKey jobKey)
throws SQLException;
/**
*
* Update the job data map for the given job.
*
*
* @param conn
* the DB Connection
* @param job
* the job to update
* @return the number of rows updated
* @throws IOException
* if there were problems serializing the JobDataMap
*/
int updateJobData(Connection conn, JobDetail job)
throws IOException, SQLException;
/**
*
* Select the JobDetail object for a given job name / group name.
*
*
* @param conn
* the DB Connection
*
* @return the populated JobDetail object
* @throws ClassNotFoundException
* if a class found during deserialization cannot be found or if
* the job class could not be found
* @throws IOException
* if deserialization causes an error
*/
JobDetail selectJobDetail(Connection conn, JobKey jobKey,
ClassLoadHelper loadHelper)
throws ClassNotFoundException, IOException, SQLException;
/**
*
* Select the total number of jobs stored.
*
*
* @param conn
* the DB Connection
* @return the total number of jobs stored
*/
int selectNumJobs(Connection conn) throws SQLException;
/**
*
* Select all of the job group names that are stored.
*
*
* @param conn
* the DB Connection
* @return an array of String group names
*/
List selectJobGroups(Connection conn) throws SQLException;
/**
*
* Select all of the jobs contained in a given group.
*
*
* @param conn
* the DB Connection
* @param matcher
* the group matcher to evaluate against the known jobs
* @return an array of String job names
*/
Set selectJobsInGroup(Connection conn, GroupMatcher matcher)
throws SQLException;
//---------------------------------------------------------------------------
// triggers
//---------------------------------------------------------------------------
/**
*
* Insert the base trigger data.
*
*
* @param conn
* the DB Connection
* @param trigger
* the trigger to insert
* @param state
* the state that the trigger should be stored in
* @return the number of rows inserted
*/
int insertTrigger(Connection conn, OperableTrigger trigger, String state,
JobDetail jobDetail) throws SQLException, IOException;
/**
*
* Update the base trigger data.
*
*
* @param conn
* the DB Connection
* @param trigger
* the trigger to insert
* @param state
* the state that the trigger should be stored in
* @return the number of rows updated
*/
int updateTrigger(Connection conn, OperableTrigger trigger, String state,
JobDetail jobDetail) throws SQLException, IOException;
/**
*
* Check whether or not a trigger exists.
*
*
* @param conn
* the DB Connection
*
* @return the number of rows updated
*/
boolean triggerExists(Connection conn, TriggerKey triggerKey) throws SQLException;
/**
*
* Update the state for a given trigger.
*
*
* @param conn
* the DB Connection
*
* @param state
* the new state for the trigger
* @return the number of rows updated
*/
int updateTriggerState(Connection conn, TriggerKey triggerKey,
String state) throws SQLException;
/**
*
* Update the given trigger to the given new state, if it is in the given
* old state.
*
*
* @param conn
* the DB connection
*
* @param newState
* the new state for the trigger
* @param oldState
* the old state the trigger must be in
* @return int the number of rows updated
* @throws SQLException
*/
int updateTriggerStateFromOtherState(Connection conn,
TriggerKey triggerKey, String newState, String oldState) throws SQLException;
/**
*
* Update the given trigger to the given new state, if it is one of the
* given old states.
*
*
* @param conn
* the DB connection
*
* @param newState
* the new state for the trigger
* @param oldState1
* one of the old state the trigger must be in
* @param oldState2
* one of the old state the trigger must be in
* @param oldState3
* one of the old state the trigger must be in
* @return int the number of rows updated
* @throws SQLException
*/
int updateTriggerStateFromOtherStates(Connection conn,
TriggerKey triggerKey, String newState, String oldState1,
String oldState2, String oldState3)
throws SQLException;
/**
*
* Update all triggers in the given group to the given new state, if they
* are in one of the given old states.
*
*
* @param conn
* the DB connection
* @param matcher
* the group matcher to evaluate against the known triggers
* @param newState
* the new state for the trigger
* @param oldState1
* one of the old state the trigger must be in
* @param oldState2
* one of the old state the trigger must be in
* @param oldState3
* one of the old state the trigger must be in
* @return int the number of rows updated
* @throws SQLException
*/
int updateTriggerGroupStateFromOtherStates(Connection conn,
GroupMatcher matcher, String newState, String oldState1,
String oldState2, String oldState3) throws SQLException;
/**
*
* Update all of the triggers of the given group to the given new state, if
* they are in the given old state.
*
*
* @param conn
* the DB connection
* @param matcher
* the matcher to evaluate against the known triggers
* @param newState
* the new state for the trigger group
* @param oldState
* the old state the triggers must be in
* @return int the number of rows updated
* @throws SQLException
*/
int updateTriggerGroupStateFromOtherState(Connection conn,
GroupMatcher matcher, String newState, String oldState)
throws SQLException;
/**
*
* Update the states of all triggers associated with the given job.
*
*
* @param conn
* the DB Connection
*
* @param state
* the new state for the triggers
* @return the number of rows updated
*/
int updateTriggerStatesForJob(Connection conn, JobKey jobKey,
String state) throws SQLException;
/**
*
* Update the states of any triggers associated with the given job, that
* are the given current state.
*
*
* @param conn
* the DB Connection
*
* @param state
* the new state for the triggers
* @param oldState
* the old state of the triggers
* @return the number of rows updated
*/
int updateTriggerStatesForJobFromOtherState(Connection conn,
JobKey jobKey, String state, String oldState)
throws SQLException;
/**
*
* Delete the base trigger data for a trigger.
*
*
* @param conn
* the DB Connection
*
* @return the number of rows deleted
*/
int deleteTrigger(Connection conn, TriggerKey triggerKey) throws SQLException;
/**
*
* Select the number of triggers associated with a given job.
*
*
* @param conn
* the DB Connection
* @return the number of triggers for the given job
*/
int selectNumTriggersForJob(Connection conn, JobKey jobKey) throws SQLException;
/**
*
* Select the job to which the trigger is associated.
*
*
* @param conn
* the DB Connection
*
* @return the {@link org.quartz.JobDetail} object
* associated with the given trigger
*/
JobDetail selectJobForTrigger(Connection conn, ClassLoadHelper loadHelper,
TriggerKey triggerKey)
throws ClassNotFoundException, SQLException;
/**
*
* Select the triggers for a job
*
*
* @param conn
* the DB Connection
*
* @return an array of (@link org.quartz.Trigger) objects
* associated with a given job.
* @throws SQLException
* @throws JobPersistenceException
*/
List selectTriggersForJob(Connection conn, JobKey jobKey) throws SQLException, ClassNotFoundException,
IOException, JobPersistenceException;
/**
*
* Select the triggers for a calendar
*
*
* @param conn
* the DB Connection
* @param calName
* the name of the calendar
* @return an array of (@link org.quartz.Trigger) objects
* associated with the given calendar.
* @throws SQLException
* @throws JobPersistenceException
*/
List selectTriggersForCalendar(Connection conn, String calName)
throws SQLException, ClassNotFoundException, IOException, JobPersistenceException;
/**
*
* Select a trigger.
*
*
* @param conn
* the DB Connection
*
* @return the {@link org.quartz.Trigger} object
* @throws JobPersistenceException
*/
OperableTrigger selectTrigger(Connection conn, TriggerKey triggerKey) throws SQLException, ClassNotFoundException,
IOException, JobPersistenceException;
/**
*
* Select a trigger's JobDataMap.
*
*
* @param conn
* the DB Connection
* @param triggerName
* the name of the trigger
* @param groupName
* the group containing the trigger
* @return the {@link org.quartz.JobDataMap} of the Trigger,
* never null, but possibly empty.
*/
JobDataMap selectTriggerJobDataMap(Connection conn, String triggerName,
String groupName) throws SQLException, ClassNotFoundException,
IOException;
/**
*
* Select a trigger' state value.
*
*
* @param conn
* the DB Connection
*
* @return the {@link org.quartz.Trigger} object
*/
String selectTriggerState(Connection conn, TriggerKey triggerKey) throws SQLException;
/**
*
* Select a trigger' status (state & next fire time).
*
*
* @param conn
* the DB Connection
*
* @return a TriggerStatus object, or null
*/
TriggerStatus selectTriggerStatus(Connection conn,
TriggerKey triggerKey) throws SQLException;
/**
*
* Select the total number of triggers stored.
*
*
* @param conn
* the DB Connection
* @return the total number of triggers stored
*/
int selectNumTriggers(Connection conn) throws SQLException;
/**
*
* Select all of the trigger group names that are stored.
*
*
* @param conn
* the DB Connection
* @return an array of String group names
*/
List selectTriggerGroups(Connection conn) throws SQLException;
List selectTriggerGroups(Connection conn, GroupMatcher matcher) throws SQLException;
/**
*
* Select all of the triggers contained in a given group.
*
*
* @param conn
* the DB Connection
* @param matcher
* to evaluate against known triggers
* @return a Set of TriggerKeys
*/
Set selectTriggersInGroup(Connection conn, GroupMatcher matcher)
throws SQLException;
/**
*
* Select all of the triggers in a given state.
*
*
* @param conn
* the DB Connection
* @param state
* the state the triggers must be in
* @return an array of trigger Key s
*/
List selectTriggersInState(Connection conn, String state)
throws SQLException;
int insertPausedTriggerGroup(Connection conn, String groupName)
throws SQLException;
int deletePausedTriggerGroup(Connection conn, String groupName)
throws SQLException;
int deletePausedTriggerGroup(Connection conn, GroupMatcher matcher)
throws SQLException;
int deleteAllPausedTriggerGroups(Connection conn)
throws SQLException;
boolean isTriggerGroupPaused(Connection conn, String groupName)
throws SQLException;
Set selectPausedTriggerGroups(Connection conn)
throws SQLException;
boolean isExistingTriggerGroup(Connection conn, String groupName)
throws SQLException;
//---------------------------------------------------------------------------
// calendars
//---------------------------------------------------------------------------
/**
*
* Insert a new calendar.
*
*
* @param conn
* the DB Connection
* @param calendarName
* the name for the new calendar
* @param calendar
* the calendar
* @return the number of rows inserted
* @throws IOException
* if there were problems serializing the calendar
*/
int insertCalendar(Connection conn, String calendarName,
Calendar calendar) throws IOException, SQLException;
/**
*
* Update a calendar.
*
*
* @param conn
* the DB Connection
* @param calendarName
* the name for the new calendar
* @param calendar
* the calendar
* @return the number of rows updated
* @throws IOException
* if there were problems serializing the calendar
*/
int updateCalendar(Connection conn, String calendarName,
Calendar calendar) throws IOException, SQLException;
/**
*
* Check whether or not a calendar exists.
*
*
* @param conn
* the DB Connection
* @param calendarName
* the name of the calendar
* @return true if the trigger exists, false otherwise
*/
boolean calendarExists(Connection conn, String calendarName)
throws SQLException;
/**
*
* Select a calendar.
*
*
* @param conn
* the DB Connection
* @param calendarName
* the name of the calendar
* @return the Calendar
* @throws ClassNotFoundException
* if a class found during deserialization cannot be found be
* found
* @throws IOException
* if there were problems deserializing the calendar
*/
Calendar selectCalendar(Connection conn, String calendarName)
throws ClassNotFoundException, IOException, SQLException;
/**
*
* Check whether or not a calendar is referenced by any triggers.
*
*
* @param conn
* the DB Connection
* @param calendarName
* the name of the calendar
* @return true if any triggers reference the calendar, false otherwise
*/
boolean calendarIsReferenced(Connection conn, String calendarName)
throws SQLException;
/**
*
* Delete a calendar.
*
*
* @param conn
* the DB Connection
* @param calendarName
* the name of the trigger
* @return the number of rows deleted
*/
int deleteCalendar(Connection conn, String calendarName)
throws SQLException;
/**
*
* Select the total number of calendars stored.
*
*
* @param conn
* the DB Connection
* @return the total number of calendars stored
*/
int selectNumCalendars(Connection conn) throws SQLException;
/**
*
* Select all of the stored calendars.
*
*
* @param conn
* the DB Connection
* @return an array of String calendar names
*/
List selectCalendars(Connection conn) throws SQLException;
//---------------------------------------------------------------------------
// trigger firing
//---------------------------------------------------------------------------
/**
*
* Select the next time that a trigger will be fired.
*
*
* @param conn
* the DB Connection
* @return the next fire time, or 0 if no trigger will be fired
*
* @deprecated Does not account for misfires.
*/
long selectNextFireTime(Connection conn) throws SQLException;
/**
*
* Select the trigger that will be fired at the given fire time.
*
*
* @param conn
* the DB Connection
* @param fireTime
* the time that the trigger will be fired
* @return a {@link org.quartz.utils.Key} representing the
* trigger that will be fired at the given fire time, or null if no
* trigger will be fired at that time
*/
Key selectTriggerForFireTime(Connection conn, long fireTime)
throws SQLException;
/**
*
* Select the next trigger which will fire to fire between the two given timestamps
* in ascending order of fire time, and then descending by priority.
*
*
* @param conn
* the DB Connection
* @param noLaterThan
* highest value of getNextFireTime() of the triggers (exclusive)
* @param noEarlierThan
* highest value of getNextFireTime() of the triggers (inclusive)
*
* @return A (never null, possibly empty) list of the identifiers (Key objects) of the next triggers to be fired.
*
* @deprecated - This remained for compatibility reason. Use {@link #selectTriggerToAcquire(Connection, long, long, int)} instead.
*/
public List selectTriggerToAcquire(Connection conn, long noLaterThan, long noEarlierThan)
throws SQLException;
/**
*
* Select the next trigger which will fire to fire between the two given timestamps
* in ascending order of fire time, and then descending by priority.
*
*
* @param conn
* the DB Connection
* @param noLaterThan
* highest value of getNextFireTime() of the triggers (exclusive)
* @param noEarlierThan
* highest value of getNextFireTime() of the triggers (inclusive)
* @param maxCount
* maximum number of trigger keys allow to acquired in the returning list.
*
* @return A (never null, possibly empty) list of the identifiers (Key objects) of the next triggers to be fired.
*/
public List selectTriggerToAcquire(Connection conn, long noLaterThan, long noEarlierThan, int maxCount)
throws SQLException;
/**
*
* Insert a fired trigger.
*
*
* @param conn
* the DB Connection
* @param trigger
* the trigger
* @param state
* the state that the trigger should be stored in
* @return the number of rows inserted
*/
int insertFiredTrigger(Connection conn, OperableTrigger trigger,
String state, JobDetail jobDetail) throws SQLException;
/**
*
* Update a fired trigger record. Will update the fields
* "firing instance", "fire time", and "state".
*
*
* @param conn
* the DB Connection
* @param trigger
* the trigger
* @param state
* the state that the trigger should be stored in
* @return the number of rows inserted
*/
int updateFiredTrigger(Connection conn, OperableTrigger trigger,
String state, JobDetail jobDetail) throws SQLException;
/**
*
* Select the states of all fired-trigger records for a given trigger, or
* trigger group if trigger name is null.
*
*
* @return a List of FiredTriggerRecord objects.
*/
List selectFiredTriggerRecords(Connection conn, String triggerName, String groupName) throws SQLException;
/**
*
* Select the states of all fired-trigger records for a given job, or job
* group if job name is null.
*
*
* @return a List of FiredTriggerRecord objects.
*/
List selectFiredTriggerRecordsByJob(Connection conn, String jobName, String groupName) throws SQLException;
/**
*
* Select the states of all fired-trigger records for a given scheduler
* instance.
*
*
* @return a List of FiredTriggerRecord objects.
*/
List selectInstancesFiredTriggerRecords(Connection conn,
String instanceName) throws SQLException;
/**
*
* Select the distinct instance names of all fired-trigger records.
*
*
*
* This is useful when trying to identify orphaned fired triggers (a
* fired trigger without a scheduler state record.)
*
*
* @return a Set of String objects.
*/
Set selectFiredTriggerInstanceNames(Connection conn)
throws SQLException;
/**
*
* Delete a fired trigger.
*
*
* @param conn
* the DB Connection
* @param entryId
* the fired trigger entry to delete
* @return the number of rows deleted
*/
int deleteFiredTrigger(Connection conn, String entryId)
throws SQLException;
/**
*
* Get the number instances of the identified job currently executing.
*
*
* @param conn
* the DB Connection
*
* @return the number instances of the identified job currently executing.
*/
int selectJobExecutionCount(Connection conn, JobKey jobKey) throws SQLException;
/**
*
* Insert a scheduler-instance state record.
*
*
* @param conn
* the DB Connection
* @return the number of inserted rows.
*/
int insertSchedulerState(Connection conn, String instanceId,
long checkInTime, long interval)
throws SQLException;
/**
*
* Delete a scheduler-instance state record.
*
*
* @param conn
* the DB Connection
* @return the number of deleted rows.
*/
int deleteSchedulerState(Connection conn, String instanceId)
throws SQLException;
/**
*
* Update a scheduler-instance state record.
*
*
* @param conn
* the DB Connection
* @return the number of updated rows.
*/
int updateSchedulerState(Connection conn, String instanceId, long checkInTime)
throws SQLException;
/**
*
* A List of all current SchedulerStateRecords.
*
*
*
* If instanceId is not null, then only the record for the identified
* instance will be returned.
*
*
* @param conn
* the DB Connection
*/
List selectSchedulerStateRecords(Connection conn, String instanceId)
throws SQLException;
/**
* Clear (delete!) all scheduling data - all {@link Job}s, {@link Trigger}s
* {@link Calendar}s.
*
* @throws JobPersistenceException
*/
void clearData(Connection conn)
throws SQLException;
}
// EOF