package umontreal.iro.lecuyer.simevents.eventlist; 

import java.util.ListIterator; 
import umontreal.iro.lecuyer.simevents.Event;


/**
 * An interface for implementations of event lists.
 * Different implementations are provided in SSJ:
 * doubly-linked list, splay tree, Henricksen's method, etc.
 * The events in the event list are objects of the class
 * {@link umontreal.iro.lecuyer.simevents.Event Event}.
 * The method {@link umontreal.iro.lecuyer.simevents.Sim#init(EventList) Sim.init}
 * permits one to select
 * the actual implementation used in a simulation.
 * 
 * 

 * To allow the user to print the event list, the 
 * {@link java.lang.Object#toString toString} method
 * from the {@link Object} class should be reimplemented in all EventList
 * implementations.  It will return a string in the following format:
 * ``Contents of the event list event list class:'' for the first line and
 * each subsequent line has format 
 * ``scheduled event time, event priority : event string''.
 * The event string is obtained by calling the
 * toString method of the event objects.
 * The string should not end with the end-of-line character.
 * 
 * 

 * The following example is the event list of the bank example,
 * printed at 10h30.  See examples.pdf for more information.
 * 
 * 

 * 
 * Contents of the event list SplayTree:
 *    10.51,        1 : BankEv$Arrival@cfb549
 *    10.54,        1 : BankEv$Departure@8a7efd
 *       11,        1 : BankEv$3@86d4c1
 *       14,        1 : BankEv$4@f9f9d8
 *       15,        1 : BankEv$5@820dda
 * 
 * 
 */
public interface EventList extends Iterable {

 
   /**
    * Returns true if and only if the event list is empty
    *    (no event is scheduled).
    *  
    * @return true if the event list is empty
    * 
    */
   public boolean isEmpty();


   /**
    * Empties the event list, i.e., cancels all events.
    * 
    */
   public void clear();


   /**
    * Adds a new event in the event list, according to
    *   the time of ev.
    *   If the event list contains events scheduled to happen at the same time as
    *   ev, ev must be added after all these events.
    *  
    * @param ev event to be added
    * 
    * 
    */
   public void add (Event ev);


   /**
    * Adds a new event at the beginning of the event list.  The given
    *    event ev will occur at the current simulation time.
    *  
    * @param ev event to be added
    * 
    * 
    */
   public void addFirst (Event ev);


   /**
    * Same as {@link #add add}, but adds the new event ev
    *   immediately before the event other in the list.
    *  
    * @param ev event to be added
    * 
    *    @param other reference event before which ev will be added
    * 
    * 
    */
   public void addBefore (Event ev, Event other);


   /**
    * Same as {@link #add add}, but adds the new event ev
    *   immediately after the event other in the list.
    *  
    * @param ev event to be added
    * 
    *    @param other reference event after which ev will be added
    * 
    * 
    */
   public void addAfter (Event ev, Event other);


   /**
    * Returns the first event in the event list.
    *  If the event list is empty, returns null.
    *  
    * @return the first event in the event list, or null if the list is empty
    * 
    */
   public Event getFirst();


   /**
    * Returns the first event of the class cl (a subclass of
    *   Event) in the event list.  If no such event is found, returns
    *   null.
    *  
    * @return the first event of class cl, or null if no such event exists in the list
    * 
    */
   public Event getFirstOfClass (String cl);


   /**
    * Returns the first event of the class E (a subclass of
    *   Event) in the event list. If no such event is found, returns
    *   null.
    *  
    * @return the first event of class cl, or null if no such event exists in the list
    * 
    */
   public  E getFirstOfClass (Class cl);


   /**
    * Returns a list iterator over the elements of the class Event in this list.
    * 
    * @return a list iterator over the elements of the class Event in this list
    * 
    */
   public ListIterator listIterator();


   /**
    * Removes the event ev from the event list (cancels this event).
    *  Returns true if and only if the event removal has succeeded.
    *  
    * @param ev event to be removed
    * 
    *    @return true if the event was successfully removed from the list
    * 
    */
   public boolean remove (Event ev);


   /**
    * Removes the first event from the event list (to cancel or
    *     execute this event).  Returns the removed event.  If the list is empty,
    *     then null is returned.
    *  
    * @return the first event removed from the list, or null if the list is empty
    * 
    */
   public Event removeFirst();

}