package sale;

import sale.events.*;
import java.io.Serializable;

/**
  * An object that is to be able to do the time management for your application has to implement this interface.
  *
  * <p>It is intended and therefore strongly recommended, that for higher flexibility implementations
  * of this interface use an object implementing the {@link Time Time} interface to hold the current time and
  * delegate most of the functionality to that object.</p>
  *
  * @author Stephan Gambke
  * @version 2.0 11/06/1999
  * @since v2.0
  */
public interface Timer extends Serializable {

  /**
    * Set the current time.
    *
    * <p>This method should call the equivalent method of the {@link Time Time} object and fire a
    * <code>timeSet</code> event.</p>
    *
    * <p>Of course, <code>IllegalArgumentException</code>s thrown by the {@link Time Time} object must be
    * forwarded to the calling method.</p>
    *
    * @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
    *
    * @see sale.events.TimerListener#onTimeSet
    */
  public void setTime (Object oTime) throws IllegalArgumentException;

  /**
    * Get the current time.
    *
    * <p>This method should call the equivalent method of the {@link Time Time} object.</p>
    *
    * @override Always
    *
    * @return an Object representing the current time
    */
  public Object getTime();

  /**
    * Set the interval to be used by {@link #goAhead goAhead()}.
    *
    * <p>An <code>IllegalArgumentException</code> is not yet thrown because the new interval is only stored.</p>
    *
    * <p>This method should fire an <code>intervalSet</code> event.</p>
    *
    * @override Always
    *
    * @param oInterval the interval to be set
    *
    * @see sale.events.TimerListener#onIntervalSet
    */
  public void setInterval (Object oInterval);

  /**
    * Get the current interval for calls to {@link #goAhead goAhead()}.
    *
    * @override Always
    *
    * @return an Object representing the interval
    */
  public Object getInterval();

  /**
    * Adds a listener for {@link TimerEvent TimerEvents} fired by this timer.
    *
    * @override Always
    *
    * @param tlListener the listener to be added
    *
    * @see sale.events.TimerListener
    */
  public void addTimerListener (TimerListener tlListener);

  /**
    * Removes a listener for {@link TimerEvent TimerEvents}.
    *
    * @override Always
    *
    * @param tlListener the listener to be removed
    *
    * @see sale.events.TimerListener
    */
  public void removeTimerListener (TimerListener tlListener);

  /**
    * Increases the current time by an interval.
    *
    * <p>This method should call the equivalent method at the {@link Time Time} object passing the interval
    * set by through {@link #setInterval setInterval()}. If no interval has been set yet, the {@link Time Time}
    * object's {@link Time#getDefaultInterval getDefaultInterval()} method can be used to get a valid default.</p>
    *
    * <p>Additionally, a <code>goneAhead</code> event should be fired.</p>
    *
    * <p>This method forwards <code>IllegalArgumentExceptions</code> thrown by the Time object's
    * {@link Time#goAhead goAhead()} method to the calling method.</p>
    *
    * @override Always
    *
    * @exception IllegalArgumentException if the interval does not meet the time object's class or format
    * requirements
    *
    * @see sale.events.TimerListener#onGoneAhead
    */
  public void goAhead() throws IllegalArgumentException;

  /**
    * Create and return a fresh time stamp.
    *
    * <p>This method should call the {@link Time Time} object's {@link Time#getTimeStamp getTimeStamp()}
    * method passing a <code>long</code> value representing the number of the time stamp in this time period.
    *
    * @override Always
    */
  public Comparable getTimeStamp();
}