001: /*
002: * @(#)PTimer.java 1.17 06/10/10
003: *
004: * Copyright 1990-2006 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: *
026: */
027:
028: package com.sun.util;
029:
030: /**
031: * A class representing a timer.
032: *
033: * A timer is responsible for managing a set of timer events specified
034: * by timer specifications. When the timer event should be sent,
035: * the timer calls the timer specification's notifyListeners method.
036: * <h3>Compatibility</h3>
037: * The PTimer class is available on PersonalJava implementations,
038: * but is not available on J2SE platforms. It is optional on Personal
039: * Profile implementations, but has been deprecated. The <code>java.util.timer</code>
040: * class should be used instead, except in cases where PersonalJava
041: * compatibility is necessary.
042: *
043: * @since PersonalJava1.0
044: * @deprecated This class is kept for backwards compatiability with Personal Java.
045: The java.util.Timer class is the preferred way of implementing
046: timers under the Personal Profile.
047: */
048: public abstract class PTimer {
049: private static PTimer defaultTimer;
050:
051: /**
052: * Returns the default timer for the system.
053: * There may be one PTimer instance per virtual machine,
054: * one per applet, one per call to getTimer, or some other platform dependent
055: * implementation.
056: * @return A non-null PTimer object.
057: */
058: public static PTimer getTimer() {
059: if (defaultTimer != null) {
060: return defaultTimer;
061: }
062: synchronized (PTimer.class) {
063: if (defaultTimer == null) {
064: defaultTimer = new DefaultPTimer();
065: }
066: return defaultTimer;
067: }
068: }
069:
070: /**
071: * schedule event delivery according to the PTimerSpec
072: * @deprecated since Personal Java Spec 1.2,
073: * replaced by the new {@link #scheduleTimerSpec} method.
074: *
075: */
076: public abstract void schedule(PTimerSpec t);
077:
078: /**
079: * Begins monitoring a PTimerSpec. <p>When the timer
080: * specification should go off, the timer will call
081: * PTimerSpec.notifyListeners. </p>
082: *
083: * <p> Returns the real PTimerSpec that got scheduled. If you schedule a
084: * spec that implies a smaller granularity than this timer can provide,
085: * or a repeat timer spec that has a smaller repeating interval than
086: * this timer can provide, the timer should round to the closest value
087: * and return that value as a {@link PTimerSpec} object. An interested application
088: * can use accessor methods {@link #getMinRepeatInterval} and {@link #getGranularity} to
089: * obtain the Timer's best knowledge of the Timer's limitation on
090: * granularity and repeat interval. If you schedule an
091: * absolute specification that should have gone off already, it will
092: * go off immediately. If the scheduled specification can not be met
093: * at all, the exception {@link PTimerScheduleFailedException} should be
094: * thrown. </p>
095: *
096: * <p>You may schedule a timer specification with multiple timers.
097: * You may schedule a timer specification with the same timer
098: * multiple times (in which case it will go off multiple times). If
099: * you modify a timer specification after it has been scheduled
100: * with any timer, the results are unspecified.</p>
101: *
102: * @param t The timer specification to begin monitoring.
103: * @return The real PTimerSpec that was scheduled.
104: * @exception PTimerScheduleFailedException is thrown when the scheduled
105: * spec can not be met at all.
106: */
107: public abstract PTimerSpec scheduleTimerSpec(PTimerSpec t)
108: throws PTimerScheduleFailedException;
109:
110: /**
111: * Stop events from being delivered.
112: * Removes a timer specification from the set of monitored specifications.
113: * The descheduling happens as soon as practical, but may not happen immediately.
114: * If the timer specification has been scheduled multiple times with this
115: * timer, all the schedulings are cancelled.
116: * @ param t The timer specification to end monitoring.
117: */
118: public abstract void deschedule(PTimerSpec t);
119:
120: /**
121: * Report the minimum interval that this timer can repeat tasks.
122: * For example, it's perfectly reasonable for a Timer to specify that
123: * the minimum interval for a repeatedly performed task is 1000 msec in
124: * between every run. This is to avoid possible system overloading.
125: *
126: * @return The timer's best knowledge of minimum repeat interval
127: * in mili-seconds. Return -1 if this timer doesn't know its repeating
128: * interval limitation.
129: */
130: public abstract long getMinRepeatInterval();
131:
132: /**
133: * Report the granularity of this timer, i.e. the length of time between
134: * "tick"s of this timer.
135: *
136: * @return The timer's best knowledge of the granularity in
137: * mili-seconds. Return -1 if this timer doesn't know its granularity.
138: *
139: */
140: public abstract long getGranularity();
141: }
|