001: /*_############################################################################
002: _##
003: _## SNMP4J - CommonTimer.java
004: _##
005: _## Copyright (C) 2003-2008 Frank Fock and Jochen Katz (SNMP4J.org)
006: _##
007: _## Licensed under the Apache License, Version 2.0 (the "License");
008: _## you may not use this file except in compliance with the License.
009: _## You may obtain a copy of the License at
010: _##
011: _## http://www.apache.org/licenses/LICENSE-2.0
012: _##
013: _## Unless required by applicable law or agreed to in writing, software
014: _## distributed under the License is distributed on an "AS IS" BASIS,
015: _## WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
016: _## See the License for the specific language governing permissions and
017: _## limitations under the License.
018: _##
019: _##########################################################################*/
020:
021: package org.snmp4j.util;
022:
023: import java.util.TimerTask;
024: import java.util.Date;
025:
026: /**
027: * This <code>CommonTimer</code> defines the subset interface used from
028: * {@link java.util.Timer} by SNMP4J.
029: *
030: * @author Frank Fock
031: * @version 1.9
032: * @since 1.9
033: */
034: public interface CommonTimer {
035:
036: /**
037: * Schedules the specified task for execution after the specified delay.
038: *
039: * @param task task to be scheduled.
040: * @param delay delay in milliseconds before task is to be executed.
041: * @throws IllegalArgumentException if <tt>delay</tt> is negative, or
042: * <tt>delay + System.currentTimeMillis()</tt> is negative.
043: * @throws IllegalStateException if task was already scheduled or
044: * cancelled, or timer was cancelled.
045: */
046: void schedule(TimerTask task, long delay);
047:
048: /**
049: * Schedules the specified task for repeated <i>fixed-delay execution</i>,
050: * beginning at the specified time. Subsequent executions take place at
051: * approximately regular intervals, separated by the specified period.
052: *
053: * <p>In fixed-delay execution, each execution is scheduled relative to
054: * the actual execution time of the previous execution. If an execution
055: * is delayed for any reason (such as garbage collection or other
056: * background activity), subsequent executions will be delayed as well.
057: * In the long run, the frequency of execution will generally be slightly
058: * lower than the reciprocal of the specified period (assuming the system
059: * clock underlying <tt>Object.wait(long)</tt> is accurate).
060: *
061: * <p>Fixed-delay execution is appropriate for recurring activities
062: * that require "smoothness." In other words, it is appropriate for
063: * activities where it is more important to keep the frequency accurate
064: * in the short run than in the long run. This includes most animation
065: * tasks, such as blinking a cursor at regular intervals. It also includes
066: * tasks wherein regular activity is performed in response to human
067: * input, such as automatically repeating a character as long as a key
068: * is held down.
069: *
070: * @param task task to be scheduled.
071: * @param firstTime First time at which task is to be executed.
072: * @param period time in milliseconds between successive task executions.
073: * @throws IllegalArgumentException if <tt>time.getTime()</tt> is negative.
074: * @throws IllegalStateException if task was already scheduled or
075: * cancelled, timer was cancelled, or timer thread terminated.
076: */
077: void schedule(TimerTask task, Date firstTime, long period);
078:
079: /**
080: * Schedules the specified task for repeated <i>fixed-delay execution</i>,
081: * beginning after the specified delay. Subsequent executions take place
082: * at approximately regular intervals separated by the specified period.
083: *
084: * <p>In fixed-delay execution, each execution is scheduled relative to
085: * the actual execution time of the previous execution. If an execution
086: * is delayed for any reason (such as garbage collection or other
087: * background activity), subsequent executions will be delayed as well.
088: * In the long run, the frequency of execution will generally be slightly
089: * lower than the reciprocal of the specified period (assuming the system
090: * clock underlying <tt>Object.wait(long)</tt> is accurate).
091: *
092: * <p>Fixed-delay execution is appropriate for recurring activities
093: * that require "smoothness." In other words, it is appropriate for
094: * activities where it is more important to keep the frequency accurate
095: * in the short run than in the long run. This includes most animation
096: * tasks, such as blinking a cursor at regular intervals. It also includes
097: * tasks wherein regular activity is performed in response to human
098: * input, such as automatically repeating a character as long as a key
099: * is held down.
100: *
101: * @param task task to be scheduled.
102: * @param delay delay in milliseconds before task is to be executed.
103: * @param period time in milliseconds between successive task executions.
104: * @throws IllegalArgumentException if <tt>delay</tt> is negative, or
105: * <tt>delay + System.currentTimeMillis()</tt> is negative.
106: * @throws IllegalStateException if task was already scheduled or
107: * cancelled, timer was cancelled, or timer thread terminated.
108: */
109: void schedule(TimerTask task, long delay, long period);
110:
111: /**
112: * Terminates this timer, discarding any currently scheduled tasks.
113: * Does not interfere with a currently executing task (if it exists).
114: * Once a timer has been terminated, its execution thread terminates
115: * gracefully, and no more tasks may be scheduled on it.
116: *
117: * <p>Note that calling this method from within the run method of a
118: * timer task that was invoked by this timer absolutely guarantees that
119: * the ongoing task execution is the last task execution that will ever
120: * be performed by this timer.
121: *
122: * <p>This method may be called repeatedly; the second and subsequent
123: * calls have no effect.
124: */
125: public void cancel();
126:
127: }
|