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: */
017: package org.apache.cocoon.components.cron;
018:
019: import java.util.Date;
020: import java.util.Map;
021: import java.util.NoSuchElementException;
022:
023: import org.apache.avalon.framework.CascadingException;
024: import org.apache.avalon.framework.parameters.Parameters;
025:
026: /**
027: * This component schedules jobs.
028: *
029: * @author <a href="mailto:giacomo@apache.org">Giacomo Pati</a>
030: * @version CVS $Id: JobScheduler.java 433543 2006-08-22 06:22:54Z crossley $
031: *
032: * @since 2.1.1
033: */
034: public interface JobScheduler {
035: /** The role of a JobScheduler */
036: String ROLE = JobScheduler.class.getName();
037:
038: /**
039: * Get the names of all scheduled jobs.
040: *
041: * @return state of execution successfullness
042: */
043: String[] getJobNames();
044:
045: /**
046: * Get the JobSchedulerEntry for a scheduled job
047: *
048: * @return the entry
049: */
050: JobSchedulerEntry getJobSchedulerEntry(String jobname);
051:
052: /**
053: * Schedule a time based job. Note that if a job with the same name has already beed added it is overwritten.
054: *
055: * @param name the name of the job
056: * @param jobrole The Avalon components role name of the job itself
057: * @param schedulingExpression the time specification using a scheduling expression
058: * @param canRunConcurrently whether this job can run even previous scheduled runs are still running
059: */
060: void addJob(String name, String jobrole,
061: String schedulingExpression, boolean canRunConcurrently)
062: throws CascadingException;
063:
064: /**
065: * Schedule a time based job. Note that if a job with the same name has already beed added it is overwritten.
066: *
067: * @param name the name of the job
068: * @param jobrole The Avalon components role name of the job itself
069: * @param schedulingExpression the time specification using a scheduling expression
070: * @param canRunConcurrently whether this job can run even previous scheduled runs are still running
071: * @param params Additional Parameters to setup CronJob
072: * @param objects A Map with additional object to setup CronJob
073: */
074: void addJob(String name, String jobrole,
075: String schedulingExpression, boolean canRunConcurrently,
076: Parameters params, Map objects) throws CascadingException;
077:
078: /**
079: * Schedule a time based job. Note that if a job with the same name has already beed added it is overwritten.
080: *
081: * @param name the name of the job
082: * @param job The job object itself. It must implement either CronJob, Runnable or might also be an implementation
083: * specific class (i.e. org.quartz.Job)
084: * @param schedulingExpression the time specification using a scheduling expression
085: * @param canRunConcurrently whether this job can run even previous scheduled runs are still running
086: */
087: void addJob(String name, Object job, String schedulingExpression,
088: boolean canRunConcurrently) throws CascadingException;
089:
090: /**
091: * Schedule a job. Note that if a job with the same name has already beed added it is overwritten.
092: *
093: * @param name the name of the job
094: * @param job The job object itself. It must implement either CronJob, Runnable or might also be an implementation
095: * specific class (i.e. org.quartz.Job)
096: * @param schedulingExpression the time specification using a scheduling expression
097: * @param canRunConcurrently whether this job can run even previous scheduled runs are still running
098: * @param params Additional Parameters to setup CronJob
099: * @param objects A Map with additional object to setup CronJob
100: */
101: void addJob(String name, Object job, String schedulingExpression,
102: boolean canRunConcurrently, Parameters params, Map objects)
103: throws CascadingException;
104:
105: /**
106: * Schedule a periodic job. The job is started the first time when the period has passed. Note that if a job with
107: * the same name has already beed added it is overwritten.
108: *
109: * @param name the name of the job
110: * @param jobrole The Avalon components role name of the job itself
111: * @param period Every period seconds this job is started
112: * @param canRunConcurrently whether this job can run even previous scheduled runs are still running
113: * @param params Additional Parameters to setup CronJob
114: * @param objects A Map with additional object to setup CronJob
115: */
116: void addPeriodicJob(String name, String jobrole, long period,
117: boolean canRunConcurrently, Parameters params, Map objects)
118: throws CascadingException;
119:
120: /**
121: * Schedule a periodic job. The job is started the first time when the period has passed. Note that if a job with
122: * the same name has already beed added it is overwritten.
123: *
124: * @param name the name of the job
125: * @param job The job object itself. It must implement either CronJob, Runnable or might also be an implementation
126: * specific class (i.e. org.quartz.Job)
127: * @param period Every period seconds this job is started
128: * @param canRunConcurrently whether this job can run even previous scheduled runs are still running
129: * @param params Additional Parameters to setup CronJob
130: * @param objects A Map with additional object to setup CronJob
131: */
132: void addPeriodicJob(String name, Object job, long period,
133: boolean canRunConcurrently, Parameters params, Map objects)
134: throws CascadingException;
135:
136: /**
137: * Fire a job once immediately
138: *
139: * @param jobrole The Avalon components role name of the job itself
140: *
141: * @return success state adding the job
142: */
143: boolean fireJob(String jobrole);
144:
145: /**
146: * Fire a CronJob once immediately
147: *
148: * @param job The job object itself. It must implement either CronJob, Runnable or might also be an implementation
149: * specific class (i.e. org.quartz.Job)
150: *
151: * @return whether the job has been successfully started
152: */
153: boolean fireJob(Object job);
154:
155: /**
156: * Fire a job once immediately
157: *
158: * @param jobrole The Avalon components role name of the job itself
159: * @param params Additional Parameters to setup CronJob
160: * @param objects A Map with additional object to setup CronJob
161: *
162: * @return whether the job has been successfully started
163: */
164: boolean fireJob(String jobrole, Parameters params, Map objects)
165: throws CascadingException;
166:
167: /**
168: * Fire a job once immediately
169: *
170: * @param job The job object itself. It must implement either CronJob, Runnable or might also be an implementation
171: * specific class (i.e. org.quartz.Job)
172: * @param params Additional Parameters to setup CronJob
173: * @param objects A Map with additional object to setup CronJob
174: *
175: * @return whether the job has been successfully started
176: */
177: boolean fireJob(Object job, Parameters params, Map objects)
178: throws CascadingException;
179:
180: /**
181: * Fire a job once at a specific date Note that if a job with the same name has already beed added it is
182: * overwritten.
183: *
184: * @param date The date this job should be scheduled
185: * @param name the name of the job
186: * @param jobrole The Avalon components role name of the job itself
187: */
188: void fireJobAt(Date date, String name, String jobrole)
189: throws CascadingException;
190:
191: /**
192: * Fire a job once at a specific date Note that if a job with the same name has already beed added it is
193: * overwritten.
194: *
195: * @param date The date this job should be scheduled
196: * @param name the name of the job
197: * @param jobrole The Avalon components role name of the job itself
198: * @param params Additional Parameters to setup CronJob
199: * @param objects A Map with additional object to setup CronJob
200: */
201: void fireJobAt(Date date, String name, String jobrole,
202: Parameters params, Map objects) throws CascadingException;
203:
204: /**
205: * Fire a job once at a specific date Note that if a job with the same name has already beed added it is
206: * overwritten.
207: *
208: * @param date The date this job should be scheduled
209: * @param name the name of the job
210: * @param job The job object itself. It must implement either CronJob, Runnable or might also be an implementation
211: * specific class (i.e. org.quartz.Job)
212: */
213: void fireJobAt(Date date, String name, Object job)
214: throws CascadingException;
215:
216: /**
217: * Fire a job once at a specific date Note that if a job with the same name has already beed added it is
218: * overwritten.
219: *
220: * @param date The date this job should be scheduled
221: * @param name the name of the job
222: * @param job The job object itself. It must implement either CronJob, Runnable or might also be an implementation
223: * specific class (i.e. org.quartz.Job)
224: * @param params Additional Parameters to setup CronJob
225: * @param objects A Map with additional object to setup CronJob
226: */
227: void fireJobAt(Date date, String name, Object job,
228: Parameters params, Map objects) throws CascadingException;
229:
230: /**
231: * Remove a scheduled job by name.
232: *
233: * @param name the name of the job
234: */
235: void removeJob(String name) throws NoSuchElementException;
236: }
|