package sale;

import java.io.Serializable;

/**
  * Interface used by implementations of the {@link Timer Timer} interface.
  *
  * <p>So, it is possible for a timer to deal with different time formats.</p>
  *
  * @author Stephan Gambke
  * @version 2.0 11/06/1999
  * @since v2.0
  */
public interface Time extends Serializable {

  /**
    * Set the time.
    *
    * @override Always
    *
    * @param oTime the time to be set
    *
    * @Exception IllegalArgumentException if the time does not meet the time object's class or format
    * requirements
    */
  public void setTime (Object oTime) throws IllegalArgumentException;

  /**
    * Get the current time.
    *
    * <p>The returned object should have a useful {@link java.lang.Object#toString toString()} method, so that
    * the time can be printed in a meaningful way.</p>
    *
    * @override Always
    *
    * @return an object representing the current time.
    */
  public Object getTime();

  /**
    * Increases the current time by the given interval.
    *
    * @override Always
    *
    * @param oInterval the interval
    *
    * @Exception IllegalArgumentException if the interval does not meet the time object's class or format
    * requirements
    */
  public void goAhead (Object oInterval) throws IllegalArgumentException;

  /**
    * Get the default interval to be used by timers.
    *
    * <p>This method is required for calls of {@link Timer#goAhead Timer.goAhead()} before the
    * {@link Timer#setInterval Timer.setInterval()} method was called.</p>
    *
    * @override Always
    *
    * @return an object representing a valid interval for this Time object
    */
  public Object getDefaultInterval();

  /**
    * Create and return a time stamp.
    *
    * <p>The returned time stamps have to be in a natural order that is identical to the order of creation.
    * A good idea would be a String consisting of the time in a correctly sortable format followed by a value
    * representing the stamp number in this time interval.</p>
    *
    * <p>More formally two time stamps <i>a</i> and <i>b</i> must fulfil the following conditions:</p>
    *
    * <ul>
    *   <li><code><i>a</i>.compareTo (<i>b</i>) &lt; 0</code> iff <i>a</i> was obtained before <i>b</i>.</li>
    *   <li><code><i>a</i>.compareTo (<i>b</i>) &gt; 0</code> iff <i>a</i> was obtained after <i>b</i>.</li>
    *   <li><code><i>a</i>.compareTo (<i>b</i>) == 0</code> iff <i>a</i> was obtained at the same time as
    *       <i>b</i>, i.e. iff <code><i>a</i> == <i>b</i></code>.</li>
    * </ul>
    *
    * @override Always
    *
    * @param lStampNumber the number of the stamp
    *
    * @return a time stamp that fulfills the above conditions.
    */
  public Comparable getTimeStamp(long lStampNumber);
}