001: /*
002: ItsNat Java Web Application Framework
003: Copyright (C) 2007 Innowhere Software Services S.L., Spanish Company
004: Author: Jose Maria Arranz Santamaria
005:
006: This program is free software: you can redistribute it and/or modify
007: it under the terms of the GNU Affero General Public License as published by
008: the Free Software Foundation, either version 3 of the License, or
009: (at your option) any later version. See the GNU Affero General Public
010: License for more details. See the copy of the GNU Affero General Public License
011: included in this program. If not, see <http://www.gnu.org/licenses/>.
012: */
013:
014: package org.itsnat.core;
015:
016: import org.itsnat.core.event.TimerHandle;
017: import java.util.Date;
018: import org.itsnat.core.event.ParamTransport;
019: import org.w3c.dom.events.EventListener;
020: import org.w3c.dom.events.EventTarget;
021:
022: /**
023: * Utility interface to manage scheduled remote tasks (timer tasks).
024: * An ItsNat scheduled or timer task is a task executed following a time based schedule,
025: * when the task must be executed the client sends an event received
026: * by a user defined listener (the task to execute).
027: *
028: * <p>The ItsNatTimer features and API are inspired in <code>java.util.Timer</code>
029: * but the main differences are that timer events are sent by the client
030: * and the server does not use any special thread to schedule the event sequence.</p>
031: *
032: * <p>Note: big documentation parts of this interface are copied from
033: * <code>java.util.Timer</code>.</p>
034: *
035: * @author Jose Maria Arranz Santamaria
036: */
037: public interface ItsNatTimer {
038: /**
039: * Returns the parent document this object belongs to.
040: *
041: * @return the parent document.
042: */
043: public ItsNatDocument getItsNatDocument();
044:
045: /**
046: * Terminates this timer manager, discarding any currently scheduled tasks.
047: * Does not interfere with a currently executing task (if it exists).
048: * Once a timer has been terminated no more tasks may be scheduled on it.
049: *
050: * <p>Note that calling this method from within the
051: * <code>EventListener.handleEvent(Event)</code>
052: * method of a timer task that was invoked by this timer absolutely guarantees that
053: * the ongoing task execution is the last task execution that will ever
054: * be performed by this timer.
055: *
056: * <p>This method may be called repeatedly; the second and subsequent
057: * calls have no effect.</p>
058: */
059: public void cancel();
060:
061: /**
062: * Schedules the specified task (the <code>EventListener</code> object) for execution at the specified time. If
063: * the time is in the past, the task is scheduled for immediate execution.
064: *
065: * <p>When the scheduled task is fully finished or cancelled is automatically unregistered.</p>
066: *
067: *
068: * @param target optional target element usually useful along with {@link org.itsnat.core.event.ParamTransport} objects. May be null.
069: * @param task task to be scheduled. It receives timer events.
070: * @param time time at which task is to be executed.
071: * @param syncMode synchronization mode.
072: * @param extraParams optional client to server data transport and synchronization rules. May be null.
073: * @param preSendCode custom JavaScript code to execute before an event of this listener type is fired. May be null.
074: * @param ajaxTimeout the timeout of asynchronous AJAX events sent by the timer. If negative no timeout is defined.
075: * @return a timer handle, this object represents the scheduled task.
076: */
077: public TimerHandle schedule(EventTarget target, EventListener task,
078: Date time, int syncMode, ParamTransport[] extraParams,
079: String preSendCode, long ajaxTimeout);
080:
081: /**
082: * Schedules the specified task (the <code>EventListener</code> object) for execution at the specified time. If
083: * the time is in the past, the task is scheduled for immediate execution.
084: *
085: * <p>The default synchronous mode is used.</p>
086: *
087: * <p>Current implementation does the following:</p>
088: * <blockquote><pre>
089: * int syncMode = getItsNatDocument().getDefaultSyncMode();
090: * long ajaxTimeout = getItsNatDocument().getAJAXTimeout();
091: * return schedule(target,task,time,syncMode,null,null,ajaxTimeout);
092: * </pre></blockquote>
093: *
094: *
095: * @param target optional target element usually useful along with {@link org.itsnat.core.event.ParamTransport} objects. May be null.
096: * @param task task to be scheduled. It receives timer events.
097: * @param time time at which task is to be executed.
098: * @return a timer handle, this object represents the scheduled task.
099: * @see #schedule(EventTarget,EventListener,Date,int,ParamTransport[],String,long)
100: */
101: public TimerHandle schedule(EventTarget target, EventListener task,
102: Date time);
103:
104: /**
105: * Schedules the specified task for repeated <i>fixed-delay execution</i>,
106: * beginning at the specified time. Subsequent executions take place at
107: * approximately regular intervals, separated by the specified period.
108: *
109: * <p>In fixed-delay execution, each execution is scheduled relative to
110: * the actual execution time of the previous execution. If an execution
111: * is delayed for any reason, subsequent executions will be delayed as well.
112: * In the long run, the frequency of execution will generally be slightly
113: * lower than the reciprocal of the specified period.
114: *
115: * <p>Fixed-delay execution is appropriate for recurring activities
116: * that require "smoothness." In other words, it is appropriate for
117: * activities where it is more important to keep the frequency accurate
118: * in the short run than in the long run. This includes most animation
119: * tasks, such as blinking a cursor at regular intervals. It also includes
120: * tasks wherein regular activity is performed in response to human
121: * input, such as automatically repeating a character as long as a key
122: * is held down.
123: *
124: * <p>When the scheduled task is fully finished or cancelled is automatically unregistered.</p>
125: *
126: *
127: * @param target optional target element usually useful along with {@link org.itsnat.core.event.ParamTransport} objects. May be null.
128: * @param task task to be scheduled.
129: * @param firstTime first time at which task is to be executed.
130: * @param period time in milliseconds between successive task executions.
131: * @param syncMode synchronization mode.
132: * @param extraParams optional client to server data transport and synchronization rules. May be null.
133: * @param preSendCode custom JavaScript code to execute before an event of this listener type is fired. May be null.
134: * @param ajaxTimeout the timeout of asynchronous AJAX events sent by the timer. If negative no timeout is defined.
135: * @return a timer handle, this object represents the scheduled task.
136: */
137: public TimerHandle schedule(EventTarget target, EventListener task,
138: Date firstTime, long period, int syncMode,
139: ParamTransport[] extraParams, String preSendCode,
140: long ajaxTimeout);
141:
142: /**
143: * Schedules the specified task for repeated <i>fixed-delay execution</i>,
144: * beginning at the specified time. Subsequent executions take place at
145: * approximately regular intervals, separated by the specified period.
146: *
147: * <p>The default synchronous mode is used.</p>
148: *
149: * <p>Current implementation does the following:</p>
150: * <blockquote><pre>
151: * int syncMode = getItsNatDocument().getDefaultSyncMode();
152: * long ajaxTimeout = getItsNatDocument().getAJAXTimeout();
153: * return schedule(target,task,firstTime,period,syncMode,null,null,ajaxTimeout);
154: * </pre></blockquote>
155: *
156: *
157: * @param target optional target element usually useful along with {@link org.itsnat.core.event.ParamTransport} objects. May be null.
158: * @param task task to be scheduled.
159: * @param firstTime first time at which task is to be executed.
160: * @param period time in milliseconds between successive task executions.
161: * @return a timer handle, this object represents the scheduled task.
162: * @see #schedule(org.w3c.dom.events.EventTarget,org.w3c.dom.events.EventListener,Date,long,int,org.itsnat.core.event.ParamTransport[],String,long)
163: */
164: public TimerHandle schedule(EventTarget target, EventListener task,
165: Date firstTime, long period);
166:
167: /**
168: * Schedules the specified task for execution after the specified delay.
169: *
170: *
171: * @param target optional target element usually useful along with {@link org.itsnat.core.event.ParamTransport} objects. May be null.
172: * @param task task to be scheduled.
173: * @param delay delay in milliseconds before task is to be executed.
174: * @param syncMode synchronization mode.
175: * @param extraParams optional client to server data transport and synchronization rules. May be null.
176: * @param preSendCode custom JavaScript code to execute before an event of this listener type is fired. May be null.
177: * @param ajaxTimeout the timeout of asynchronous AJAX events sent by the timer. If negative no timeout is defined.
178: * @return a timer handle, this object represents the scheduled task.
179: */
180: public TimerHandle schedule(EventTarget target, EventListener task,
181: long delay, int syncMode, ParamTransport[] extraParams,
182: String preSendCode, long ajaxTimeout);
183:
184: /**
185: * Schedules the specified task for execution after the specified delay.
186: *
187: * <p>The default synchronous mode is used.</p>
188: *
189: * <p>Current implementation does the following:</p>
190: * <blockquote><pre>
191: * int syncMode = getItsNatDocument().getDefaultSyncMode();
192: * long ajaxTimeout = getItsNatDocument().getAJAXTimeout();
193: * return schedule(target,task,delay,syncMode,null,null,ajaxTimeout);
194: * </pre></blockquote>
195: *
196: *
197: * @param target optional target element usually useful along with {@link org.itsnat.core.event.ParamTransport} objects. May be null.
198: * @param task task to be scheduled.
199: * @param delay delay in milliseconds before task is to be executed.
200: * @return a timer handle, this object represents the scheduled task.
201: * @see #schedule(org.w3c.dom.events.EventTarget,org.w3c.dom.events.EventListener,long,int,org.itsnat.core.event.ParamTransport[],String,long)
202: */
203: public TimerHandle schedule(EventTarget target, EventListener task,
204: long delay);
205:
206: /**
207: * Schedules the specified task for repeated <i>fixed-delay execution</i>,
208: * beginning after the specified delay. Subsequent executions take place
209: * at approximately regular intervals separated by the specified period.
210: *
211: * <p>In fixed-delay execution, each execution is scheduled relative to
212: * the actual execution time of the previous execution. If an execution
213: * is delayed for any reason, subsequent executions will be delayed as well.
214: * In the long run, the frequency of execution will generally be slightly
215: * lower than the reciprocal of the specified period.
216: *
217: * <p>Fixed-delay execution is appropriate for recurring activities
218: * that require "smoothness." In other words, it is appropriate for
219: * activities where it is more important to keep the frequency accurate
220: * in the short run than in the long run. This includes most animation
221: * tasks, such as blinking a cursor at regular intervals. It also includes
222: * tasks wherein regular activity is performed in response to human
223: * input, such as automatically repeating a character as long as a key
224: * is held down.
225: *
226: * <p>When the scheduled task is fully finished or cancelled is automatically unregistered.</p>
227: *
228: *
229: * @param target optional target element usually useful along with {@link org.itsnat.core.event.ParamTransport} objects. May be null.
230: * @param task task to be scheduled.
231: * @param delay delay in milliseconds before task is to be executed.
232: * @param period time in milliseconds between successive task executions.
233: * @param syncMode synchronization mode.
234: * @param extraParams optional client to server data transport and synchronization rules. May be null.
235: * @param preSendCode custom JavaScript code to execute before an event of this listener type is fired. May be null.
236: * @param ajaxTimeout the timeout of asynchronous AJAX events sent by the timer. If negative no timeout is defined.
237: * @return a timer handle, this object represents the scheduled task.
238: */
239: public TimerHandle schedule(EventTarget target, EventListener task,
240: long delay, long period, int syncMode,
241: ParamTransport[] extraParams, String preSendCode,
242: long ajaxTimeout);
243:
244: /**
245: * Schedules the specified task for repeated <i>fixed-delay execution</i>,
246: * beginning after the specified delay. Subsequent executions take place
247: * at approximately regular intervals separated by the specified period.
248: *
249: * <p>The default synchronous mode is used.</p>
250: *
251: * <p>Current implementation does the following:</p>
252: * <blockquote><pre>
253: * int syncMode = getItsNatDocument().getDefaultSyncMode();
254: * long ajaxTimeout = getItsNatDocument().getAJAXTimeout();
255: * return schedule(target,task,delay,period,syncMode,null,null,ajaxTimeout);
256: * </pre></blockquote>
257: *
258: *
259: * @param target optional target element usually useful along with {@link org.itsnat.core.event.ParamTransport} objects. May be null.
260: * @param task task to be scheduled.
261: * @param delay delay in milliseconds before task is to be executed.
262: * @param period time in milliseconds between successive task executions.
263: * @return a timer handle, this object represents the scheduled task.
264: */
265: public TimerHandle schedule(EventTarget target, EventListener task,
266: long delay, long period);
267:
268: /**
269: * Schedules the specified task for repeated <i>fixed-rate execution</i>,
270: * beginning at the specified time. Subsequent executions take place at
271: * approximately regular intervals, separated by the specified period.
272: *
273: * <p>In fixed-rate execution, each execution is scheduled relative to the
274: * scheduled execution time of the initial execution. If an execution is
275: * delayed for any reason, two or more executions will occur in rapid succession to
276: * "catch up." In the long run, the frequency of execution will be
277: * exactly the reciprocal of the specified period.
278: *
279: * <p>Fixed-rate execution is appropriate for recurring activities that
280: * are sensitive to <i>absolute</i> time, such as ringing a chime every
281: * hour on the hour, or running scheduled maintenance every day at a
282: * particular time. It is also appropriate for recurring activities
283: * where the total time to perform a fixed number of executions is
284: * important, such as a countdown timer that ticks once every second for
285: * ten seconds. Finally, fixed-rate execution is appropriate for
286: * scheduling multiple repeating timer tasks that must remain synchronized
287: * with respect to one another.
288: *
289: * <p>When the scheduled task is fully finished or cancelled is automatically unregistered.</p>
290: *
291: *
292: * @param target optional target element usually useful along with {@link org.itsnat.core.event.ParamTransport} objects. May be null.
293: * @param task task to be scheduled.
294: * @param firstTime First time at which task is to be executed.
295: * @param period time in milliseconds between successive task executions.
296: * @param syncMode synchronization mode.
297: * @param extraParams optional client to server data transport and synchronization rules. May be null.
298: * @param preSendCode custom JavaScript code to execute before an event of this listener type is fired. May be null.
299: * @param ajaxTimeout the timeout of asynchronous AJAX events sent by the timer. If negative no timeout is defined.
300: * @return a timer handle, this object represents the scheduled task.
301: */
302: public TimerHandle scheduleAtFixedRate(EventTarget target,
303: EventListener task, Date firstTime, long period,
304: int syncMode, ParamTransport[] extraParams,
305: String preSendCode, long ajaxTimeout);
306:
307: /**
308: * Schedules the specified task for repeated <i>fixed-rate execution</i>,
309: * beginning at the specified time. Subsequent executions take place at
310: * approximately regular intervals, separated by the specified period.
311: *
312: * <p>The default synchronous mode is used.</p>
313: *
314: * <p>Current implementation does the following:</p>
315: * <blockquote><pre>
316: * int syncMode = getItsNatDocument().getDefaultSyncMode();
317: * long ajaxTimeout = getItsNatDocument().getAJAXTimeout();
318: * return scheduleAtFixedRate(target,task,firstTime,period,syncMode,null,null,ajaxTimeout);
319: * </pre></blockquote>
320: *
321: *
322: * @param target optional target element usually useful along with {@link org.itsnat.core.event.ParamTransport} objects. May be null.
323: * @param task task to be scheduled.
324: * @param firstTime First time at which task is to be executed.
325: * @param period time in milliseconds between successive task executions.
326: * @return a timer handle, this object represents the scheduled task.
327: */
328: public TimerHandle scheduleAtFixedRate(EventTarget target,
329: EventListener task, Date firstTime, long period);
330:
331: /**
332: * Schedules the specified task for repeated <i>fixed-rate execution</i>,
333: * beginning after the specified delay. Subsequent executions take place
334: * at approximately regular intervals, separated by the specified period.
335: *
336: * <p>In fixed-rate execution, each execution is scheduled relative to the
337: * scheduled execution time of the initial execution. If an execution is
338: * delayed for any reason, two or more executions will occur in rapid succession to
339: * "catch up." In the long run, the frequency of execution will be
340: * exactly the reciprocal of the specified period.
341: *
342: * <p>Fixed-rate execution is appropriate for recurring activities that
343: * are sensitive to <i>absolute</i> time, such as ringing a chime every
344: * hour on the hour, or running scheduled maintenance every day at a
345: * particular time. It is also appropriate for recurring activities
346: * where the total time to perform a fixed number of executions is
347: * important, such as a countdown timer that ticks once every second for
348: * ten seconds. Finally, fixed-rate execution is appropriate for
349: * scheduling multiple repeating timer tasks that must remain synchronized
350: * with respect to one another.
351: *
352: * <p>When the scheduled task is fully finished or cancelled is automatically unregistered.</p>
353: *
354: * @param task task to be scheduled.
355: * @param delay delay in milliseconds before task is to be executed.
356: * @param period time in milliseconds between successive task executions.
357: * @param syncMode synchronization mode.
358: * @param extraParams optional client to server data transport and synchronization rules. May be null.
359: * @param preSendCode custom JavaScript code to execute before an event of this listener type is fired. May be null.
360: * @param ajaxTimeout the timeout of asynchronous AJAX events sent by the timer. If negative no timeout is defined.
361: * @return a timer handle, this object represents the scheduled task.
362: */
363: public TimerHandle scheduleAtFixedRate(EventTarget target,
364: EventListener task, long delay, long period, int syncMode,
365: ParamTransport[] extraParams, String preSendCode,
366: long ajaxTimeout);
367:
368: /**
369: * Schedules the specified task for repeated <i>fixed-rate execution</i>,
370: * beginning after the specified delay. Subsequent executions take place
371: * at approximately regular intervals, separated by the specified period.
372: *
373: * <p>The default synchronous mode is used.</p>
374: *
375: * <p>Current implementation does the following:</p>
376: * <blockquote><pre>
377: int syncMode = getItsNatDocument().getDefaultSyncMode();
378: long ajaxTimeout = getItsNatDocument().getAJAXTimeout();
379: return scheduleAtFixedRate(target,task,delay,period,syncMode,null,null,ajaxTimeout);
380: * </pre></blockquote>
381: *
382: * @param task task to be scheduled.
383: * @param delay delay in milliseconds before task is to be executed.
384: * @param period time in milliseconds between successive task executions.
385: * @return a timer handle, this object represents the scheduled task.
386: */
387: public TimerHandle scheduleAtFixedRate(EventTarget target,
388: EventListener task, long delay, long period);
389: }
|