001 package sale;
002
003 import sale.events.*;
004 import java.io.Serializable;
005
006 /**
007 * An object that is to be able to do the time management for your application has to implement this interface.
008 *
009 * <p>It is intended and therefore strongly recommended, that for higher flexibility implementations
010 * of this interface use an object implementing the {@link Time Time} interface to hold the current time and
011 * delegate most of the functionality to that object.</p>
012 *
013 * @author Stephan Gambke
014 * @version 2.0 11/06/1999
015 * @since v2.0
016 */
017 public interface Timer extends Serializable {
018
019 /**
020 * Set the current time.
021 *
022 * <p>This method should call the equivalent method of the {@link Time Time} object and fire a
023 * <code>timeSet</code> event.</p>
024 *
025 * <p>Of course, <code>IllegalArgumentException</code>s thrown by the {@link Time Time} object must be
026 * forwarded to the calling method.</p>
027 *
028 * @override Always
029 *
030 * @param oTime the time to be set
031 *
032 * @exception IllegalArgumentException if the time does not meet the time object's class or format
033 * requirements
034 *
035 * @see sale.events.TimerListener#onTimeSet
036 */
037 public void setTime(Object oTime) throws IllegalArgumentException;
038
039 /**
040 * Get the current time.
041 *
042 * <p>This method should call the equivalent method of the {@link Time Time} object.</p>
043 *
044 * @override Always
045 *
046 * @return an Object representing the current time
047 */
048 public Object getTime();
049
050 /**
051 * Set the interval to be used by {@link #goAhead goAhead()}.
052 *
053 * <p>An <code>IllegalArgumentException</code> is not yet thrown because the new interval is only stored.</p>
054 *
055 * <p>This method should fire an <code>intervalSet</code> event.</p>
056 *
057 * @override Always
058 *
059 * @param oInterval the interval to be set
060 *
061 * @see sale.events.TimerListener#onIntervalSet
062 */
063 public void setInterval(Object oInterval);
064
065 /**
066 * Get the current interval for calls to {@link #goAhead goAhead()}.
067 *
068 * @override Always
069 *
070 * @return an Object representing the interval
071 */
072 public Object getInterval();
073
074 /**
075 * Adds a listener for {@link TimerEvent TimerEvents} fired by this timer.
076 *
077 * @override Always
078 *
079 * @param tlListener the listener to be added
080 *
081 * @see sale.events.TimerListener
082 */
083 public void addTimerListener(TimerListener tlListener);
084
085 /**
086 * Removes a listener for {@link TimerEvent TimerEvents}.
087 *
088 * @override Always
089 *
090 * @param tlListener the listener to be removed
091 *
092 * @see sale.events.TimerListener
093 */
094 public void removeTimerListener(TimerListener tlListener);
095
096 /**
097 * Increases the current time by an interval.
098 *
099 * <p>This method should call the equivalent method at the {@link Time Time} object passing the interval
100 * set by through {@link #setInterval setInterval()}. If no interval has been set yet, the {@link Time Time}
101 * object's {@link Time#getDefaultInterval getDefaultInterval()} method can be used to get a valid default.</p>
102 *
103 * <p>Additionally, a <code>goneAhead</code> event should be fired.</p>
104 *
105 * <p>This method forwards <code>IllegalArgumentExceptions</code> thrown by the Time object's
106 * {@link Time#goAhead goAhead()} method to the calling method.</p>
107 *
108 * @override Always
109 *
110 * @exception IllegalArgumentException if the interval does not meet the time object's class or format
111 * requirements
112 *
113 * @see sale.events.TimerListener#onGoneAhead
114 */
115 public void goAhead() throws IllegalArgumentException;
116
117 /**
118 * Create and return a fresh time stamp.
119 *
120 * <p>This method should call the {@link Time Time} object's {@link Time#getTimeStamp getTimeStamp()}
121 * method passing a <code>long</code> value representing the number of the time stamp in this time period.
122 *
123 * @override Always
124 */
125 public Comparable getTimeStamp();
126 }