001/** 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017package org.apache.activemq.broker.scheduler; 018 019import java.util.List; 020 021import org.apache.activemq.util.ByteSequence; 022 023public interface JobScheduler { 024 025 /** 026 * @return the name of the scheduler 027 * @throws Exception 028 */ 029 String getName() throws Exception; 030 031 /** 032 * Starts dispatch of scheduled Jobs to registered listeners. 033 * 034 * Any listener added after the start dispatch method can miss jobs so its 035 * important to register critical listeners before the start of job dispatching. 036 * 037 * @throws Exception 038 */ 039 void startDispatching() throws Exception; 040 041 /** 042 * Stops dispatching of scheduled Jobs to registered listeners. 043 * 044 * @throws Exception 045 */ 046 void stopDispatching() throws Exception; 047 048 /** 049 * Add a Job listener which will receive events related to scheduled jobs. 050 * 051 * @param listener 052 * The job listener to add. 053 * 054 * @throws Exception 055 */ 056 void addListener(JobListener listener) throws Exception; 057 058 /** 059 * remove a JobListener that was previously registered. If the given listener is not in 060 * the registry this method has no effect. 061 * 062 * @param listener 063 * The listener that should be removed from the listener registry. 064 * 065 * @throws Exception 066 */ 067 void removeListener(JobListener listener) throws Exception; 068 069 /** 070 * Add a job to be scheduled 071 * 072 * @param jobId 073 * a unique identifier for the job 074 * @param payload 075 * the message to be sent when the job is scheduled 076 * @param delay 077 * the time in milliseconds before the job will be run 078 * 079 * @throws Exception if an error occurs while scheduling the Job. 080 */ 081 void schedule(String jobId, ByteSequence payload, long delay) throws Exception; 082 083 /** 084 * Add a job to be scheduled 085 * 086 * @param jobId 087 * a unique identifier for the job 088 * @param payload 089 * the message to be sent when the job is scheduled 090 * @param cronEntry 091 * The cron entry to use to schedule this job. 092 * 093 * @throws Exception if an error occurs while scheduling the Job. 094 */ 095 void schedule(String jobId, ByteSequence payload, String cronEntry) throws Exception; 096 097 /** 098 * Add a job to be scheduled 099 * 100 * @param jobId 101 * a unique identifier for the job 102 * @param payload 103 * the message to be sent when the job is scheduled 104 * @param cronEntry 105 * cron entry 106 * @param delay 107 * time in ms to wait before scheduling 108 * @param period 109 * the time in milliseconds between successive executions of the Job 110 * @param repeat 111 * the number of times to execute the job - less than 0 will be repeated forever 112 * @throws Exception 113 */ 114 void schedule(String jobId, ByteSequence payload, String cronEntry, long delay, long period, int repeat) throws Exception; 115 116 /** 117 * remove all jobs scheduled to run at this time 118 * 119 * @param time 120 * The UTC time to use to remove a batch of scheduled Jobs. 121 * 122 * @throws Exception 123 */ 124 void remove(long time) throws Exception; 125 126 /** 127 * remove a job with the matching jobId 128 * 129 * @param jobId 130 * The unique Job Id to search for and remove from the scheduled set of jobs. 131 * 132 * @throws Exception if an error occurs while removing the Job. 133 */ 134 void remove(String jobId) throws Exception; 135 136 /** 137 * remove all the Jobs from the scheduler 138 * 139 * @throws Exception 140 */ 141 void removeAllJobs() throws Exception; 142 143 /** 144 * remove all the Jobs from the scheduler that are due between the start and finish times 145 * 146 * @param start 147 * time in milliseconds 148 * @param finish 149 * time in milliseconds 150 * @throws Exception 151 */ 152 void removeAllJobs(long start, long finish) throws Exception; 153 154 /** 155 * Get the next time jobs will be fired 156 * 157 * @return the time in milliseconds 158 * @throws Exception 159 */ 160 long getNextScheduleTime() throws Exception; 161 162 /** 163 * Get all the jobs scheduled to run next 164 * 165 * @return a list of jobs that will be scheduled next 166 * @throws Exception 167 */ 168 List<Job> getNextScheduleJobs() throws Exception; 169 170 /** 171 * Get all the outstanding Jobs 172 * 173 * @return a list of all jobs 174 * @throws Exception 175 */ 176 List<Job> getAllJobs() throws Exception; 177 178 /** 179 * Get all outstanding jobs due to run between start and finish 180 * 181 * @param start 182 * @param finish 183 * @return a list of jobs 184 * @throws Exception 185 */ 186 List<Job> getAllJobs(long start, long finish) throws Exception; 187 188}