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}