001: /*
002: * @(#)PTimerSpec.java 1.14 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: import java.util.*;
031:
032: /**
033: * <p>A class representing a timer specification. A timer
034: * specification declares when a PTimerWentOffEvent should be sent. These
035: * events are sent to the listeners registered on the
036: * specification.</p>
037: *
038: * <li>Absolute
039: * If the PTimerSpec is Absolute, then events will be dispatched at a
040: * specified time. Otherwise the time value is relative to the time
041: * at which the event is scheduled.
042: * <li>Repeat
043: * If the PTimerSpec is repeating, events will be dispatched at
044: * intervals specified by the timevalue. It is meaningless to
045: * specify an Absolute event to repeat.
046: * <li>Regular
047: * If a PTimerSpec is Regular, the PTimer will attempt to notify
048: * its listener at the specified interval regardless of how much
049: * time the event processing takes. Otherwise, the specified time
050: * is the amount of time after all listeners have been called.
051: *
052: * <h3>Compatibility</h3>
053: * The PTimer and PTimerSpec classes are part of the Personal Java
054: * Specification and are not part of J2SE. They are deprecated in
055: * the Personal Profile as they have been replaced by the
056: * <code>java.util.timer</code> class.
057: *
058: * @since: PersonalJava1.0
059: */
060: public class PTimerSpec {
061: private boolean absolute;
062: private boolean repeat;
063: private boolean regular;
064: private long time;
065: // If a subclass provides overriding definitions of
066: // addPTimerWentOffListener
067: // removePTimerWentOffListener
068: // notifyListeners
069: // then it may use this field to store its implementation.
070: //
071: // In the default implementation, it either contains a single instance of
072: // a listener or it contains an instance of Vector, holding multiple listeners.
073: // This representation is subject to change.
074: protected Object listeners;
075:
076: /**
077: * Creates timer with the following properties:
078: * <li>absolute = true
079: * <li>repeat = false
080: * <li>regular = true
081: * <li>interval = 0
082: */
083: public PTimerSpec() {
084: setAbsolute(true);
085: setRepeat(false);
086: setRegular(true);
087: setTime(0);
088: }
089:
090: /**
091: * Specifies that the timer should send an event at an absolute time
092: * <p>
093: * When a timer event is set to be absolute, the time value is specified
094: * in milliseconds since since midnight, January 1, 1970. Otherwise, the
095: * delay time is scheduled relative to the current time.
096: */
097: public void setAbsolute(boolean absolute) {
098: this .absolute = absolute;
099: }
100:
101: /**
102: * Checks if this specification is absolute.
103: * @return the "Absolute" status of the PTimerSpec
104: */
105: public boolean isAbsolute() {
106: return absolute;
107: }
108:
109: /**
110: * Sets the repeat property of this PTimerSpec.
111: */
112: public void setRepeat(boolean repeat) {
113: this .repeat = repeat;
114: }
115:
116: /**
117: * Checks if this specification is repeating
118: * @return the "Repeat" status of the PTimerSpec
119: */
120: public boolean isRepeat() {
121: return repeat;
122: }
123:
124: /**
125: * Sets this specification to be regular or non-regular
126: */
127: public void setRegular(boolean regular) {
128: this .regular = regular;
129: }
130:
131: /**
132: * Retrieves the "Regular" property of the PTimerSpec.
133: */
134: public boolean isRegular() {
135: return regular;
136: }
137:
138: /**
139: * Sets when this specification should go off. For absolute
140: * specifications, this is a time in milliseconds since midnight,
141: * January 1, 1970 UTC. For delayed specifications, this is a
142: * delay time in milliseconds.
143: */
144: public void setTime(long time) {
145: this .time = time;
146: }
147:
148: /**
149: * Returns the absolute or delay time when this specification
150: * will go off.
151: */
152: public long getTime() {
153: return time;
154: }
155:
156: // listeners
157:
158: /**
159: * Adds a listener to this timer specification.
160: * @param l the listener to add
161: */
162: public void addPTimerWentOffListener(PTimerWentOffListener l) {
163: if (l == null) {
164: throw new NullPointerException();
165: }
166: synchronized (this ) {
167: if (listeners == null) {
168: listeners = l;
169: } else {
170: Vector v;
171: if (listeners instanceof Vector) {
172: v = (Vector) listeners;
173: } else {
174: v = new Vector(2);
175: v.addElement(listeners);
176: }
177: v.addElement(l);
178: listeners = v;
179: }
180: }
181: }
182:
183: /**
184: * Removes a listener to this timer specification. Silently does nothing
185: * if the listener was not listening on this specification.
186: * @param l the listener to remove
187: */
188: public void removePTimerWentOffListener(PTimerWentOffListener l) {
189: if (l == null) {
190: throw new NullPointerException();
191: }
192: synchronized (this ) {
193: if (listeners == null) {
194: return;
195: }
196: if (listeners instanceof Vector) {
197: Vector v = (Vector) listeners;
198: v.removeElement(l);
199: if (v.size() == 1) {
200: listeners = v.firstElement();
201: }
202: } else if (listeners == l) {
203: listeners = null;
204: }
205: }
206: }
207:
208: // convenience functions
209:
210: /**
211: * Sets the PTimerSpec for an absolute, non-repeating time specified by when.
212: * This is a convenience function equivalent to setAbsolute(true),
213: * setTime(when), setRepeat(false).
214: * @param when the absolute time for the specification to go off
215: */
216: public void setAbsoluteTime(long when) {
217: setAbsolute(true);
218: setTime(when);
219: setRepeat(false);
220: }
221:
222: /**
223: * Sets the PTimerSpec for non-repeating, relative time specified by delay.
224: * This is a convenience function equivalent to setAbsolute(false),
225: * setTime(delay), setRepeat(false).
226: * @param delay the relative time for the specification to go off
227: */
228: public void setDelayTime(long delay) {
229: setAbsolute(false);
230: setTime(delay);
231: setRepeat(false);
232: }
233:
234: // for the benefit of timer implementations
235:
236: /**
237: * Calls all listeners registered on this timer specification.
238: * This function is primarily for the benefit of those writing
239: * implementations of PTimers.
240: * @param source the PTimer that decided that this specification should go off
241: */
242: public void notifyListeners(PTimer source) {
243: Vector v = null;
244: PTimerWentOffListener singleton = null;
245: synchronized (this ) {
246: if (listeners instanceof Vector) {
247: v = (Vector) ((Vector) listeners).clone();
248: } else {
249: singleton = (PTimerWentOffListener) listeners;
250: }
251: }
252: if (v != null) {
253: Enumeration e = v.elements();
254: while (e.hasMoreElements()) {
255: PTimerWentOffListener l = (PTimerWentOffListener) e
256: .nextElement();
257: l.timerWentOff(new PTimerWentOffEvent(source, this ));
258: }
259: } else if (singleton != null) {
260: singleton
261: .timerWentOff(new PTimerWentOffEvent(source, this));
262: }
263: }
264: }
|