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 getTimeStamp(long lStampNumber);
087    }