001 package sale;
002
003 import java.io.Serializable;
004
005 /**
006 * Interface used by implementations of the {@link Timer Timer} interface.
007 *
008 * <p>So, it is possible for a timer to deal with different time formats.</p>
009 *
010 * @author Stephan Gambke
011 * @version 2.0 11/06/1999
012 * @since v2.0
013 */
014 public interface Time extends Serializable {
015
016 /**
017 * Set the time.
018 *
019 * @override Always
020 *
021 * @param oTime the time to be set
022 *
023 * @exception IllegalArgumentException if the time does not meet the time object's class or format
024 * requirements
025 */
026 public void setTime(Object oTime) throws IllegalArgumentException;
027
028 /**
029 * Get the current time.
030 *
031 * <p>The returned object should have a useful {@link java.lang.Object#toString toString()} method, so that
032 * the time can be printed in a meaningful way.</p>
033 *
034 * @override Always
035 *
036 * @return an object representing the current time.
037 */
038 public Object getTime();
039
040 /**
041 * Increases the current time by the given interval.
042 *
043 * @override Always
044 *
045 * @param oInterval the interval
046 *
047 * @exception IllegalArgumentException if the interval does not meet the time object's class or format
048 * requirements
049 */
050 public void goAhead(Object oInterval) throws IllegalArgumentException;
051
052 /**
053 * Get the default interval to be used by timers.
054 *
055 * <p>This method is required for calls of {@link Timer#goAhead Timer.goAhead()} before the
056 * {@link Timer#setInterval Timer.setInterval()} method was called.</p>
057 *
058 * @override Always
059 *
060 * @return an object representing a valid interval for this Time object
061 */
062 public Object getDefaultInterval();
063
064 /**
065 * Create and return a time stamp.
066 *
067 * <p>The returned time stamps have to be in a natural order that is identical to the order of creation.
068 * A good idea would be a String consisting of the time in a correctly sortable format followed by a value
069 * representing the stamp number in this time interval.</p>
070 *
071 * <p>More formally two time stamps <i>a</i> and <i>b</i> must fulfil the following conditions:</p>
072 *
073 * <ul>
074 * <li><code><i>a</i>.compareTo (<i>b</i>) < 0</code> iff <i>a</i> was obtained before <i>b</i>.</li>
075 * <li><code><i>a</i>.compareTo (<i>b</i>) > 0</code> iff <i>a</i> was obtained after <i>b</i>.</li>
076 * <li><code><i>a</i>.compareTo (<i>b</i>) == 0</code> iff <i>a</i> was obtained at the same time as
077 * <i>b</i>, i.e. iff <code><i>a</i> == <i>b</i></code>.</li>
078 * </ul>
079 *
080 * @override Always
081 *
082 * @param lStampNumber the number of the stamp
083 *
084 * @return a time stamp that fulfills the above conditions.
085 */
086 public Comparable<String> getTimeStamp(long lStampNumber);
087 }