Source code: desmoj/Experiment.java

   package desmoj;
   
   import java.awt.event.*;      // import the stuff to close window of progress bar
   import javax.swing.*;          // import the stuff to display a progress bar
   import desmoj.exception.*;    // import special exceptions
   import desmoj.dist.*;          // import distributions
   import desmoj.report.*;        // import reporting & messaging
   import java.util.Enumeration;  // import Enumeration needed for reporting
   import java.text.ParseException;  // import ParseException needed if parsing
                                    // of reference time fails
  import java.io.File;          // import for file handling
  
  /**
   * Experiment is the class that provides the infrastructure
   * for running the simulation of a model.
   * It contains all data structures necessary to simulate the model
   * and takes care of all necessary output. To actually run an experiment,
   * a new instance of the experiment class and a new instance of the
   * desired model have to be created. To link both instances, call the
   * <code>connectToExperiment(Experiment e)</code> method of the model instance
   * and pass the new experiment as a parameter.
   * Additional functionality by Ruth Meyer: Experiments may be "timed", i.e.
   * the simulation time (represented as doubles) may be mapped to a true date
   * and time. This requires the specification of a time unit, too.
   * Example: Simulation starts at sim time 0.0 = true time 23.5.1999 10:00,
   * time unit is minutes, so sim time 5.0 = true time 23.5.1999 10:05.
   *
   * @author Tim Lechler
   * @author modified by Soenke Claassen, Ruth Meyer, Nicolas Knaak
   *
   * @version DESMO-J,  Ver. 1.5 copyright (c) 2001 licensed under GNU GPL
   */
  public class Experiment extends NamedObject {
  
    /**
    * Status of an Experiment just created without any accessories created yet.
    */
    public static final int NOT_INITIALIZED = -3;
  
    /**
    * Status of an Experiment instantiated with all needed accessories 
    * available.
    */
    public static final int INITIALIZED = -2;
  
    /**
    * Status of an Experiment connected to a Model and ready to be started.
    */
    public static final int CONNECTED = -1;
  
    /**
    * Status of an Experiment being started.
    * Only if an Experiment is 
    */
    public static final int STARTED = 0;
  
    /**
    * Status of an Experiment stopped after having run.
    */
    public static final int STOPPED = 1;
  
    /**
    * Status of an Experiment currently running the simulation.
    */
    public static final int RUNNING = 2;
  
    /**
    * Status of an Experiment finished and to be cleared.
    */
    public static final int ABORTED = 3;
  
    /**
    * The last suffix used with filenames when creating multiple batch 
    * runs of an experiment.
    */
    private static int lastSuffix;
    
    /**
    * The class reference to messages of type desmoj.report.TraceNote
    */
    static Class tracenote;
  
    /**
    * The class reference to messages of type desmoj.report.DebugNote
    */
    static Class debugnote;
  
    /**
    * The class reference to messages of type desmoj.report.ErrorMessage
    */
    static Class errormessage;
  
    /**
    * The class reference to messages of type desmoj.report.Reporter
    */
    static Class reporter;
  
    /**
    * The <code>Condition</code> which can cause an experiment to stop.
   * The user has to implement the  <code>check()</code> method of this 
   * <code>Condition</code> in order to effectively stop an experiment.
   */
   private Condition stopper;
 
   /**
   * Flag indicating if the simulation is supposed to stop after the current
   * event is processed.
   */
   private boolean abortFlag;
 
   /**
   * Flag indicating if the simulation is running.
   */
   private int status;
 
   /**
   * The model to be run by this experiment.
   */
   private Model client;
 
   /**
   * The scheduler used for this experiment.
   */
   private Scheduler clientScheduler;
 
   /**
   * The distribution manager for the model's distributions.
   */
   private DistributionManager distMan;
 
   /**
   * The report manager for the model's reports.
   */
   private ReportManager repMan;
   
   /**
   * The message manager for the model's messages.
   */
   private MessageDistributor messMan;
 
   /**
   * The seed used to start the SeedGenerator with. Default is zero, but can be
   * set via the ExperimentOptions to individual values.
   */
   private long seedGeneratorSeed;
 
   /**
   * The ThreadGroup for this Experiment.
   */
   private ThreadGroup expThreads;
 
   /**
   * The number of floating point digits of simulation time to be
   * printed in Reports.
   */
   private int timeFloats;
 
   /**
   * The Vector to register all FileOutput objects to close them after finishing
   * the Experiment.
   */
   private java.util.Vector fileRegistry;
   
   /**
  * The resource database storing all resource allocations and requests. Also
  * needed to detect deadlocks.
  */
   private ResourceDB resDB;
 
  /**
   * The SimTime when the experiment is supposed to stop. Is initially 
   * <code>null</code> and will be set only if the user provides a time
   * limit as some kind of stop <code>Condition</code>. 
   */
   private SimTime stopTime = null;
 
  /**
   * Flag indicating whether a progressbar for this experiment should be 
   * displayed or not.
   */
   private boolean showProgressBar;
 
   /**
    * The time converter used to convert sim time to true time and vice versa.
    */
   private TimeConverter trueTimer;
 
   /**
    * Flag to indicate if this experiment is "timed", i.e. if sim time is
    * mapped to a true date and time. Default is <tt>false</tt>.
    */
   private boolean isTimed;
 
  /**
   * Specifies an output path for the report files 
   * (Modification by Nicolas Knaak, 02/2001) 
   */
   private String pathname;
   /**
   * Specifies an output path for the report files 
   * (Modification by Nicolas Knaak, 02/2001) 
   */
   private String pathName;
 
 /**
  * Constructs a new Experiment with the given name.
  * This is the shortcut constructor with just the name needed as parameter
  * to identify the outputfiles produced by this experiment.
  * All other possible settings are set to default values.
  * These settings for an experiment without special ExperimentOptions are:
  * <ol>
  * <li>epsilon = 0.00001 : The minimum distinguishable timespan</li>
  * <li>time floats = 4 : The number of floating point digits displayed for
  * simulation time in reports</li>
  * <li>seed = 979 : The initial seed setting for the seed-generator</li>
  * </ol>
  * The default stop condition for this experiment will never interfere, always
  * returning false.
  * @param name String : The name of the experiment determining the outputfile's
  * names, too. So please avoid characters that your local filesystem does not
  * support in filenames.
  */
 public Experiment(String name) {
   
   this(name, ".", null, 0);    // call most special constructor
 
 }
 /**
  * Constructs a new Experiment with the given name.
  * This is the shortcut constructor with just the name needed as parameter
  * to identify the outputfiles produced by this experiment.
  * All other possible settings are set to default values.
  * These settings for an experiment without special ExperimentOptions are:
  * <ol>
  * <li>epsilon = 0.00001 : The minimum distinguishable timespan</li>
  * <li>time floats = 4 : The number of floating point digits displayed for
  * simulation time in reports</li>
  * <li>seed = 979 : The initial seed setting for the seed-generator</li>
  * </ol>
  * The default stop condition for this experiment will never interfere, always
  * returning false.
  * @param name String : The name of the experiment determining the outputfile's
  * names, too. So please avoid characters that your local filesystem does not
  * support in filenames.
  * @param pathName java.lang.String : The output path for report files
  */
 public Experiment(String name, String pathName) {
 
   this(name, pathName, null, 0);    // call most special constructor
 
 }
 /**
  * Constructs a new Experiment with the given name.
  * This is the shortcut constructor with just the name needed as parameter
  * to identify the outputfiles produced by this experiment.
  * All other possible settings are set to default values.
  * These settings for an experiment without special ExperimentOptions are:
  * <ol>
  * <li>epsilon = 0.00001 : The minimum distinguishable timespan</li>
  * <li>time floats = 4 : The number of floating point digits displayed for
  * simulation time in reports</li>
  * <li>seed = 979 : The initial seed setting for the seed-generator</li>
  * </ol>
  * The default stop condition for this experiment will never interfere, always
  * returning false.
  * @param name String : The name of the experiment determining the outputfile's
  * names, too. So please avoid characters that your local filesystem does not
  * support in filenames.
  * @param referenceTime java.lang.String : The true date and time when this simulation starts.
  * The reference time has to be specified as a String following the pattern
  * <tt>&lt;date&gt;&lt;blank&gt;&lt;time&gt;</tt> where <tt>&lt;date&gt; =
  * [d]d.[M]M.[yy]yy</tt> and
  * <tt>&lt;time&gt; = [H]H[:[m]m[:[s]s[:[S][S]S]]]</tt>
  * It is mapped to simulation time 0.0 if no other start time is given (via call
  * of the <code>start(SimTime initTime)</code> method.
  * @param referenceUnit int : The time unit to be mapped to a simulation time
  * step of 1.0 . So far, Hour, Minute, Second and Millisecond are supported.
  * Please use the constants defined in the interface <tt>Units</tt>.
  * @see desmoj.Units
  */
 public Experiment(String name, String referenceTime, int referenceUnit) {
   
   this(name, ".", referenceTime, referenceUnit);    // call most special constructor  
 
 }
 /**
  * Constructs a new Experiment with the given name.
  * This is the shortcut constructor with just the name needed as parameter
  * to identify the outputfiles produced by this experiment.
  * All other possible settings are set to default values.
  * These settings for an experiment without special ExperimentOptions are:
  * <ol>
  * <li>epsilon = 0.00001 : The minimum distinguishable timespan</li>
  * <li>time floats = 4 : The number of floating point digits displayed for
  * simulation time in reports</li>
  * <li>seed = 979 : The initial seed setting for the seed-generator</li>
  * </ol>
  * The default stop condition for this experiment will never interfere, always
  * returning false.
  * @param name String : The name of the experiment determining the outputfile's
  * names, too. So please avoid characters that your local filesystem does not
  * support in filenames.
  * @param pathName java.lang.String : The output path for report files
  * @param referenceTime java.lang.String : The true date and time when this simulation starts.
  * The reference time has to be specified as a String following the pattern
  * <tt>&lt;date&gt;&lt;blank&gt;&lt;time&gt;</tt> where <tt>&lt;date&gt; =
  * [d]d.[M]M.[yy]yy</tt> and
  * <tt>&lt;time&gt; = [H]H[:[m]m[:[s]s[:[S][S]S]]]</tt>
  * It is mapped to simulation time 0.0 if no other start time is given (via call
  * of the <code>start(SimTime initTime)</code> method.
  * @param referenceUnit int : The time unit to be mapped to a simulation time
  * step of 1.0 . So far, Hour, Minute, Second and Millisecond are supported.
  * Please use the constants defined in the interface <tt>Units</tt>.
  * @see desmoj.Units
  */
 public Experiment(String name, String pathName, String referenceTime, int referenceUnit) {
   super(name);    // create a NamedObject with an attitude ;-)
 
   // initialize variables
   status           = NOT_INITIALIZED;
   stopper          = null;  // no Stopper can be set at instantiation time 
   expThreads       = new ThreadGroup(name);
   abortFlag        = false;
   timeFloats       = 4;
   fileRegistry     = new java.util.Vector(4);  // usually 4 files open
   lastSuffix       = 0;    // no batches have run so far ;-)
   showProgressBar = true;  // display a progress bar for this experiment
   
   // Check and set output path
   if (pathName == null || pathName == "" || pathName == ".")
     this.pathName = System.getProperty("user.dir", ".");
   else this.pathName = pathName;
 
   // set class variables for basic messagetypes
   try {
     tracenote = Class.forName("desmoj.report.TraceNote");
     debugnote = Class.forName("desmoj.report.DebugNote");
     errormessage = Class.forName("desmoj.report.ErrorMessage");
     reporter = Class.forName("desmoj.report.Reporter");
   }
   catch (ClassNotFoundException cnfEx) {
     System.out.println("Can not create Experiment!");
     System.out.println("Constructor of desmoj.Experiment.");
     System.out.println("Classes are probably not installed correctly.");
     System.out.println("Check your CLASSPATH setting.");
     System.out.println("Exception caught : "+cnfEx);
   }
 
   // create output system first
   messMan = new MessageDistributor();
   
   // create and register the debug output
   DebugFileOut dbg = new DebugFileOut(timeFloats);
   dbg.open(pathName, name);
   messMan.register(dbg, debugnote);
   messMan.switchOff(debugnote);
   register(dbg);
 
   // create and register the report output
   ReportFileOut rpt = new ReportMultRowsFileOut(timeFloats);
   // ReportFileOut rpt = new ReportFileOut(timeFloats);
   rpt.open(pathName, name);
   messMan.register(rpt, reporter);
   register(rpt);
 
   // create and register the error output
   ErrorFileOut err = new ErrorFileOut(timeFloats);
   err.open(pathName, name);
   messMan.register(err, errormessage);
   register(err);
 
   // create and register the trace output
   TraceFileOut trc = new TraceFileOut(timeFloats);
   trc.open(pathName, name);
   messMan.register(trc, tracenote);
   messMan.switchOff(tracenote);
   register(trc);
   
   // create the distributionmanager to register distributions at
   distMan = new DistributionManager(name, 979, this);
 
   // now create the simulation runtime accessories
   client = null;  // no object connected
 
   // make a default epsilon
   SimTime epsilon  = new SimTime(0.00001);
 
   // create the scheduler and clock
   clientScheduler = new Scheduler(this, name, epsilon);
 
   // create a resource database and tell it that it belongs to this experiment
   resDB = new ResourceDB(this);
 
   // set status to first valid value - initialized, but not connected
   status = INITIALIZED;
 
   // initialize time converter with reference time und reference unit
   trueTimer = null;
   isTimed = false;
   try {
     if (referenceTime == null) {
       trueTimer = new TimeConverter();
     }
     else {
       trueTimer = new TimeConverter(referenceTime, referenceUnit);
       // set timedFlag to true
       isTimed = true;
     }
   }
   catch (java.text.ParseException e) {
     // referenceTime seems to be invalid
     throw (new desmoj.exception.SimAbortedException(
            new desmoj.report.ErrorMessage (null,
             "Can't create timed Experiment! Simulation aborted.",
             "Class : TimeConverter  Constructor : TimeConverter(String, int)",
             "the value passed for parameter referenceTime failed parsing : "+referenceTime,
             "Required time format is : d.M.yy H[:m[:s[:S]]]",
              null)));
   }
 
   
 }
 /**
  * Adds a messagereceiver for debugnotes to the experiment.
  * Whenever a model produces a message of that type, it will also be sent to
  * the given messagereceiver for further processing.
  * Note that the given receiver must be capable of handling debugnotes.
  * @param trcRec desmoj.report.MessageReceiver : The new messagereceiver for the
  * given type of messages
  */
 public void addDebugReceiver(MessageReceiver trcRec) {
   
   if ( trcRec==null) {
     sendWarning (
       "Can not add receiver to experiment! Command ignored.",
       "Experiment '"+getName()+"', method 'void addDebugReceiver("+
       "MessageReceiver trcRec)'",
       "The parameter 'trc' passed was a null reference.",
       "Make sure to construct a valid MessageReciever before adding it to "+
       "the experiment's messaging system.");
     return;  // do nothing
   }
   
   messMan.register(trcRec, debugnote);
   
 }
 /**
  * Adds a messagereceiver for error messages to the experiment.
  * Whenever a model produces a message of that type, it will also be sent to
  * the given messagereceiver for further processing.
  * Note that the given receiver must be capable of handling messagereceiver.
  * @param trcRec desmoj.report.MessageReceiver : The new messagereceiver for the
  * given type of messages
  */
 public void addErrorReceiver(MessageReceiver trcRec) {
   
   if ( trcRec==null) {
     sendWarning (
       "Can not add receiver to experiment! Command ignored.",
       "Experiment '"+getName()+"', method 'void addErrorReceiver("+
       "MessageReceiver trcRec)'",
       "The parameter 'trc' passed was a null reference.",
       "Make sure to construct a valid MessageReciever before adding it to "+
       "the experiment's messaging system.");
     return;  // do nothing
   }
   
   messMan.register(trcRec, errormessage);
   
 }
 /**
  * Adds a messagereceiver for the given subtype of message to the experiment.
  * Whenever a model produces a message of that type, it will also be sent to
  * the given messagereceiver for further processing.
  * @param trcRec desmoj.report.MessageReceiver : The new messagereceiver for the
  * given type of messages
  * @param messageType Class : The type of message to be sent to the given
  * messagereceiver
  */
 public void addReceiver(MessageReceiver trcRec, Class messageType) {
   
   if ( trcRec==null) {
     sendWarning (
       "Can not add receiver to experiment! Command ignored.",
       "Experiment '"+getName()+"', method 'void addReceiver(MessageReceiver "+
       "trcRec, Class messageType)'",
       "The parameter 'trc' passed was a null reference.",
       "Make sure to construct a valid MessageReciever before adding it to "+
       "the experiment's messaging system.");
     return;  // do nothing
   }
   
   if ( messageType==null) {  // again these damned null values 
     sendWarning (
       "Can not add receiver to experiment! Command ignored.",
       "Experiment '"+getName()+"', method 'void addReceiver(MessageReceiver "+
       "trcRec, Class messageType)'",
       "The parameter 'messageType' passed was a null reference.",
       "Make sure to construct a valid Class object before adding it to "+
       "the experiment's messaging system.");
     return;  // do nothing
   }
   
   messMan.register(trcRec, messageType);
   
 }
 /**
  * Adds a messagereceiver for tracenotes to the experiment.
  * Whenever a model produces a message of that type, it will also be sent to
  * the given messagereceiver for further processing.
  * Note that the given Receiver must be capable of handling tracenotes.
  * @param trcRec desmoj.report.MessageReceiver : The new messagereceiver for the
  * given type of messages
  */
 public void addTraceReceiver(MessageReceiver trcRec) {
   
   if ( trcRec==null) {
     sendWarning (
       "Can not add receiver to experiment! Command ignored.",
       "Experiment '"+getName()+"', method 'void addTraceReceiver("+
       "MessageReceiver trcRec)'",
       "The parameter 'trc' passed was a null reference.",
       "Make sure to construct a valid MessageReciever before adding it to "+
       "the experiment's messaging system.");
     return;  // do nothing
   }
   
   messMan.register(trcRec, tracenote);
   
 }
 /**
  * Returns a boolean indicating whether debug notes are forwarded to the debug
  * ouput or not.
  * Debug ouput can be switched on and off using the methods
  * <code>debugOn(SimTime startTime)</code> or 
  * <code>debugOff(SimTime stopTime)</code>
  * @return boolean
  */
 public boolean debugIsOn() {
   
   return messMan.isOn(debugnote);
   
 }
 /**
  * Switches the debug output off at the given point of simulation time.
  * @param duration SimTime : The point in simulation time to switch off debug
  */
 public void debugOff(SimTime stopTime) {
 
   // check initial SimTime parameter
   if ( stopTime == null ) {
     sendWarning (
       "Invalid start time parameter for debug output given! "+
       "StopTime is set to current time.",
       "Experiment '"+getName()+"', method 'void debugOn(SimTime startTime)'",
       "A null value or a not initialized SimTime reference has been passed.",
       "Make sure to have a valid SimTime object, otherwise use method "+
       "start() without SimTime parameter.");
     stopTime = SimTime.NOW;
   }
   
   // check if parameter is in future
   if ( SimTime.isLarger(clientScheduler.currentTime(), stopTime) ) {
     sendWarning (
       "Invalid start time parameter for debug output given! "+
       "StopTime is set to current time.",
       "Experiment '"+getName()+"', method 'void debugOn(SimTime stopTime)'",
       "The stopTime given is in the past.",
       "Make sure to give a SimTime parameter larger than the current time.");
     stopTime = SimTime.NOW;
   }
 
   ExternalEvent debugOff = new ExternalEventDebugOff(client, true);
   
   debugOff.schedule(stopTime);
 
 }
 /**
  * Switches the debug output on at the given point of simulation time.
  * @param duration SimTime : The point in simulation time to switch on debug
  */
 public void debugOn(SimTime startTime) {
 
   // check initial SimTime parameter
   if ( startTime == null ) {
     sendWarning (
       "Invalid start time parameter for debug output given! "+
       "StartTime is set to current time.",
       "Experiment '"+getName()+"', method 'void debugOn(SimTime startTime)'",
       "A null value or a not initialized SimTime reference has been passed.",
       "Make sure to have a valid SimTime object, otherwise use method "+
       "start() without SimTime parameter.");
     startTime = SimTime.NOW;
   }
   
   // check if parameter is in future
   if ( SimTime.isLarger(clientScheduler.currentTime(), startTime) ) {
     sendWarning (
       "Invalid start time parameter for debug output given! "+
       "StartTime is set to current time.",
       "Experiment '"+getName()+"', method 'void debugOn(SimTime startTime)'",
       "The startTime given is in the past.",
       "Make sure to give a SimTime parameter larger than the current time.");
     startTime = SimTime.NOW;
   }
 
   ExternalEvent debugOn = new ExternalEventDebugOn(client, true);
   
   debugOn.schedule(startTime);
   
 }
 /**
  * Switches the debug output on for the given period of simulation time.
  * If the second parameter (off) is "sooner" then the first parameter (on),
  * they will be swapped automatically. 
  * Same parameters will result in no debug output at all!
  * @param duration SimTime : The point in simulation time to switch debug
  * on
  * @param duration SimTime : The point in simulation time to switch debug
  * off
  */
 public void debugPeriod(SimTime startTime, SimTime stopTime) {
 
   // check initial SimTime parameter
   if ( startTime == null ) {
     sendWarning (
       "Invalid start time parameter for debug output given! Command ignored",
       "Experiment '"+getName()+"', Method 'debugPeriod(SimTime startTime, "+
       "SimTime stopTime)'",
       "A null value or a not initialized SimTime reference has been passed.",
       "Make sure to have a valid SimTime object.");
     return;
   }
   
   // check initial SimTime parameter
   if ( stopTime == null ) {
     sendWarning (
       "Invalid stop time parameter for debug output given! Command ignored.",
       "Experiment '"+getName()+"', Method 'debugPeriod(SimTime startTime, "+
       "SimTime stopTime)'",
       "A null value or a not initialized SimTime reference has been passed.",
       "Make sure to have a valid SimTime object.");
     return;
   }
 
   // check for correct order in parameters
   if ( SimTime.isLarger(startTime, stopTime) ) {
 
     // swap parameters
     SimTime buffer = stopTime;
     stopTime = startTime;
     startTime = buffer;
     
   }
 
   // check if stop parameter is in future
   if ( SimTime.isLarger(clientScheduler.currentTime(), stopTime) ) {
     sendWarning (
       "Invalid stop time parameter for debug output given! Command ignored.",
       "Experiment '"+getName()+"', Method 'debugPeriod(SimTime startTime, "+
       "SimTime stopTime)'",
       "The stopTime given is in the past.",
       "Make sure to give a SimTime parameter larger than the current time.");
     return;
   }
 
   // check if start parameter is in past
   if ( SimTime.isLarger(clientScheduler.currentTime(), startTime) ) {
     sendWarning (
       "Invalid start time parameter for debug output given! "+
       "Debug output has been set to start immediately.",
       "Experiment '"+getName()+"', Method 'debugPeriod(SimTime startTime, "+
       "SimTime startTime)'",
       "The startTime given is in the past.",
       "Make sure to give a SimTime parameter larger than the current time.");
     startTime = clientScheduler.currentTime();
   }
 
   // set debug to switch on
   ExternalEvent debugOn = new ExternalEventDebugOn(client, true);
   debugOn.schedule(startTime);
 
   // set debug to switch off
   ExternalEvent debugOff = new ExternalEventDebugOff(client, true);
   debugOff.schedule(stopTime);
 
 }
 /**
  * De-registers a file at the experiment.
  * Registered files will be flushed and closed after the experiment 
  * has finished. If the file is manually closed by the user and has been
  * registered at the Experiment,
  * deRegister it
  * @param file desmoj.report.FileOutput : The file to be closed with the
  * end of an Experiment
  */
 public void deRegister(FileOutput file) {
   
   if ( file == null ) {
     sendWarning (
       "Can not de-register FileOutput! Command ignored.",
       "Experiment '"+getName()+"' method 'void deRegister(FileOutput file).'",
       "The parameter given was a null reference.",
       "Make sure to only connect valid FileOutputs at the Experiment.");
     return;
   }
   
   fileRegistry.removeElement(file);  // remove whether it was inside or not
   
 }
 /**
  * Stopps all running simprocesses that might still be scheduled and 
  * closes the output files.
  */
 public void finish() {
 
   // check if experiment has not been aborted before
   if ( status >= ABORTED ) {
     return;
   }
 
   // set status to let all simthreads be killed
   status = ABORTED;  
   
   // close all files still open
   if ( !fileRegistry.isEmpty() ) {
     for ( int i = 0 ; i < fileRegistry.size() ; i++ ) {
       ((FileOutput)fileRegistry.elementAt(i)).close();
     }
   }
 
   // kill all SimThreads still active 
   Thread[] survivors = new Thread[expThreads.activeCount()];
   expThreads.enumerate(survivors);
 
   for ( int i = 0 ; i < survivors.length ; i++ ) {
 
     // print existing threads for controlling purposes only
     // System.out.println(survivors[i]);
 
     // if we get the enumeration of survivors, some of them
   // might not have made it until here and die in between
   // so an occasional NullPointerException is perfectly
   // alright and no reason to worry -> we just dump it.
   try {
     ((SimThread)survivors[i]).kill();
     }
   catch (NullPointerException e){
     ;   // forget it anyway...
   }
   }
   
 }
 /**
  * Returns the distributionmanager for this experiment.
  * Distributions need access to the distributionmanager for handling
  * antithetic modes, resetting and their initial seeds.
  * @return desmoj.dist.DistributionManager : The distributionmanager for this
  * experiment
  */
 public DistributionManager getDistributionManager() {
   
   return distMan;
   
 }
 /**
  * Returns the epsilon value representing the minimum distinguishable
  * span of simulation time for this experiment.
  * This has effect on the simulation clock, that won't advance if the
  * new point of simulation time is smaller than epsilon. In this case
  * two events are occurring at the same point of simulation time in the report.
  * @return SimTime : The minimum difference in simulation time
  */
 public SimTime getEpsilon() {
   
   return clientScheduler.getSimClock().getEpsilon();
   
 }
 /**
  * Returns the messagemanager for this experiment.
  * Messages need access to the MessageManager for distributing the messages
  * to one or more specified output streams.
  * @return desmoj.dist.MessageManager : The messagemanager for this
  * experiment
  */
 public MessageDistributor getMessageManager() {
   
   return messMan;
   
 }
 /**
  * Returns the model that is connected to this experiment or <code>null</code>
  * if no model is connected so far.
  * @return Model : The model that this experiment is connected to
  * or <code>null</code> if no connection is established.
  */
 public Model getModel() {
   
   return client;
   
 }
   /**
    * Returns the name of the path the experiment's report-, trace-, debug- and
    * error-files are written to.
    * @return String the experiment's output path
    */
   public String getOutputPath() {
     return new File(pathName).getAbsolutePath();
   }
     /** Returns the reference time for this experiment. This is the true
    *  date and time of the start of the simulation run. If no reference
    *  time was specified for this experiment, the default reference time
    *  is returned.
    *  @return String the reference time
    */
   public String getReferenceTime() {
     return trueTimer.getReferenceTime();
   }
   /** Returns the reference unit for this experiment. This is the time
    *  unit mapped to a time step of 1.0 in simulation time. So far, Hour,
    *  Minute, Second and Millisecond are supported.
    *  @return int the reference unit as a constant defined in the interface
    *  <code>Units</code>.
    *  @see desmoj.Units
    */
   public int getReferenceUnit() {
     return trueTimer.getReferenceUnit();
   }
 /**
  * Returns the reportmanager for this experiment.
  * Reports need access to the reportmanager for handling output, 
  * report width parameters and proper sorting of individual reports.
  * @return desmoj.dist.ReportManager : The reportmanager for this
  * experiment
  */
 public ReportManager getReportManager() {
   
   return repMan;
   
 }
 /**
  * Returns the resource database for this experiment.
  * The <code>Res</code> objects need access to the resource database
  * to note their resource allocations and requests and for deadlock detection.
  * @return desmoj.ResourceDB : the resource database storing all resource
  * allocations and requests.
  * @author Soenke Claassen
  */
 public ResourceDB getResourceDB() {
   
   return resDB;
 }
 /**
  * Returns the scheduler for this experiment.
  * ModelComponents need access to the scheduler for identifying the
  * current active entity or process and to schedule themselves or other
  * schedulables to activate at a given time in the future.
  * @return Scheduler : The scheduler for this experiment
  */
 public Scheduler getScheduler() {
   
   return clientScheduler;
   
 }
 /**
  * Returns the simclock for this experiment.
  * ModelComponents need access to the simclock for retrieveing the current
  * simulation time.
  * @return SimCLock : The simclock for this experiment
  */
 public SimClock getSimClock() {
   
   return clientScheduler.getSimClock();
   
 }
 /**
  * Returns the SimTime when the experiment is expected to stop running.
  * @return desmoj.SimTime : The time, the experiment is expected to stop 
  * running.
  */
 public SimTime getStopTime() {
   
   return stopTime;
 }
 /**
  * Returns the threadgroup associated to this experiment.
  * All Threads are associated to this threadgroup to get control of their
  * number and state and to have a means to differentiate them
  * from possible other experiments' threads.
  * @return java.lang.ThreadGroup
  */
 ThreadGroup getThreadGroup() {
   
   return expThreads;
   
 }
 /**
  * Returns the experiment's number of floating point digits of simulation time
  * that are displayed in the various output files
  * @return int : The number of floating point digits of simulation time
  * to be displayed in output files
  */
 public int getTimeFloats() {
   
   return timeFloats;
   
 }
 /**
  * Displays the current state of the simulation run.
  * If an experient is aborted, it can not be proceeded.
  * All SimThreads still active are stopped, the main routine can finish.
  * @return boolean : Is <code>true</code> if the simulation is aborted,
  * <code>false</code> if it has not started yet or is still running
  */
 public boolean isAborted() {
   
   return (status>=ABORTED);
   
 }
 /**
  * Shows if this experiment has already been connected to a model.
  * @return boolean : Is <code>true</code>, if experiment is connected to 
  * a model, <code>false</code> otherwise
  */
 public boolean isConnected() {
   
   return ( status >= CONNECTED );  // model connected
   
 }
 /**
  * Displays the current state of the simulation run.
  * @return boolean : Is <code>true</code> if the simulation is running,
  * <code>false</code> if it has not started yet or has already finished
  */
 public boolean isRunning() {
   
   return (status==RUNNING);
   
 }
 /**
  * Returns if a progress bar should be displayed for this experiment or not.
  * @return boolean : <code>true</code> if a progress bar should be displayed for
  * this experiment, <code>false</code> otherwise.
  */
 public boolean isShowProgressBar() {
   
   return showProgressBar;
 }
 /**
  * Proceeds with a stopped experiment.
  * An experiment can be stopped, if either its status is changed from
  * <code>RUNNING</code> to some other state, the scheduler runs out of
  * scheduled events or if the <code>check()</code> method of the given 
  * stop <code>Condition</code> returns <code>true</code> after 
  * an Event has been processed.
  */
 public void proceed() {
 
   if ( status < STARTED ) { 
     sendWarning (
       "Can not proceed with Experiment! Command ignored.",
       "Experiment: "+getName()+" Method: void proceed().",
       "The Experiment has not been started yet.",
       "Only Experiments that have been stopped after method 'start()' has "+
       "been called can use method 'proceed()' to continue.");
     return;
   }
   
   if ( status > STOPPED ) { 
     sendWarning (
       "Can not proceed with Experiment! Command ignored.",
       "Experiment "+getName()+" Method: void proceed().",
       "The Experiment has already been aborted.",
       "Use method 'proceed()' only on stopped experiments.");
     return;
   }
 
   // print status message to calm users waiting long, long, long hours...
   System.out.println(getName() + " starts at simulation time "+
     getScheduler().currentTime()+"\n ...please wait...");
 
   // display a progress bar if stop time is known and showProgressBar is true
   if ( stopTime != null && showProgressBar)
   {
     JFrame frame = new ExpProgressBar (this);
 
     frame.addWindowListener( new WindowAdapter() {
       public void windowClosing( WindowEvent e ) {
         System.exit(0);
       }
     });
     
     frame.pack();
     // frame.setSize(380,90);
     frame.setVisible(true);
   }
 
   status = RUNNING;            // now checked to run
   boolean gotEvent = false;    // buffer to check if scheduler works

  try {
    
    while ( status==RUNNING ) {  // infinite loop until condition/time expired
      gotEvent = clientScheduler.processNextEventNote();
      if ( gotEvent == false )  status = STOPPED;
      
      // only check stopper if a stopper is set up 
      if ( stopper!=null ) {
        if ( stopper.check() ) status = STOPPED;
      }
      
    }
    
  }
  catch (DESMOJException e) {
    // this is the desaster recovery routine to stop simulation and save
    // the report to disc before exiting the faulty experiment
    messMan.receive(e.getErrorMessage());
    report();
    finish();
    status = ABORTED;
  }

  // give warning if reason for stopping was empty eventlist
  if ( gotEvent==false ) {
    sendWarning (
      "No more events scheduled! Experiment is stopped.",
      "Experiment '"+getName()+"' method void proceed().",
      "The scheduler has run out of events to handle .",
      "Make sure to always have events to be scheduled i.e. by letting an "+
      "Entity create and schedule its successor.");
  }

  // print status message to user...
  System.out.println(getName()+" stopped at simulation time "+
    getScheduler().currentTime());

}
/**
 * Registers a file output at the experiment.
 * Registered files will be flushed and closed after the experiment 
 * has finished. This is handy for modellers producing their own
 * output who want their files to be closed at the end of the experiment.
 * @param file desmoj.report.FileOutput : The file to be closed with the
 * end of an experiment
 */
public void register(FileOutput file) {
  
  if ( file == null ) {
    sendWarning (
      "Can not register FileOutput! Command ignored.",
      "Experiment '"+getName()+"' method void register(FileOutput file).",
      "The parameter given was a null reference.",
      "Make sure to only connect valid FileOutputs at the Experiment.");
    return;
  }
  
  if ( fileRegistry.contains(file) ) return;  // file already registered
  
  fileRegistry.addElement(file);
  
}
/**
 * Connects a model to this experiment.
 * The given model must not be submodel of other models and not already be
 * connected to some other experiment.
 * Otherwise an errormessage will be given and the experiment will
 * be stopped.
 */
void registerModel(Model mainModel) {
  
  if ( mainModel == null ) {
    sendWarning (
      "Can not register model at experiment! Command ignored.",
      "Experiment '"+getName()+"', Method 'void registerModel(Model mainModel)'",
      "The parameter passed was a null reference.",
      "Make sure to connect a valid main model to this experiment.");
    return;  // no connection possible.
  }
  
  if ( mainModel.getModel() != null ) {
    sendWarning (
      "Can not register model at experiment! Command ignored.",
      "Experiment '"+getName()+"', Method 'void registerModel(Model mainModel)'",
      "The model references another model as its owner, thus can not be the "+
      "main model.",
      "Make sure to connect a valid main model to this experiment.");
    return;  // no connection possible.
  }

  if ( isConnected() ) {
    sendWarning (
      "Can not register model at experiment! Command ignored.",
      "Experiment '"+getName()+"', Method 'void registerModel(Model mainModel)'",
      "This experiment is already connected to model : "+client.getName(),
      "An experiment may only be connected to one main model at a time.");
    return;  // no connection possible.
  }

  status = CONNECTED;
  client = mainModel;
  client.setMain();
  
}
/**
 * Removes a messagereceiver for debugnotes from the
 * experiment's messagedistributor.
 * Whenever a model produces a message of that type, it will not be sent to
 * the given messagereceiver anymore.
 * Note that if the messagereceiver is also registered for other types of
 * messages, these will not be affected.
 * Use method <code>removeReceiverAll(MessageReceiver msgRec)</code>
 * to remove a messagereceiver from all types of messages.
 * @param trcRec desmoj.report.MessageReceiver : The new messagereceiver to be
 * removed from the messagedistributor's list for the given messagetype
 */
public void removeDebugReceiver(MessageReceiver msgRec) {
  
  if ( msgRec==null) {
    sendWarning (
      "Can not remove receiver to experiment! Command ignored.",
      "Experiment '"+getName()+"', Method 'void removeDebugReceiver"+
      "(MessageReceiver msgRec)'",
      "The parameter 'msgRec' passed was a null reference.",
      "Make sure to give a valid MessageReciever reference before removing it "+
      "from the experiment's messaging system.");
    return;  // do nothing
  }
  
  messMan.deRegister(msgRec, debugnote);
  
}
/**
 * Removes a messagereceiver for errormessages from the
 * experiment's messagedistributor.
 * Whenever a model produces a message of that type, it will not be sent to
 * the given messagereceiver anymore.
 * Note that if the messagereceiver is also registered for other types of
 * messages, these will not be affected.
 * Use method <code>removeReceiverAll(MessageReceiver msgRec)</code>
 * to remove a messagereceiver from all types of messages.
 * @param trcRec desmoj.report.MessageReceiver : The new messagereceiver to be
 * removed from the vessagedistributor's list for the given messagetype
 */
public void removeErrorReceiver(MessageReceiver msgRec) {
  
  if ( msgRec==null) {
    sendWarning (
      "Can not remove receiver to experiment! Command ignored.",
      "Experiment '"+getName()+"', Method 'void removeErrorReceiver"+
      "(MessageReceiver msgRec)'",
      "The parameter 'msgRec' passed was a null reference.",
      "Make sure to give a valid MessageReciever reference before removing it "+
      "from the experiment's messaging system.");
    return;  // do nothing
  }
  
  messMan.deRegister(msgRec, errormessage);
  
}
/**
 * Removes a messagereceiver from the experiment's messagedistributor.
 * The given messagereceiver will not receive messages of any type any more
 * Use method <code>removeReceiver(MessageReceiver msgRec, Class
 * messageType)</code> to remove the messagereceiver from one type of messages
 * only.
 * @param trcRec desmoj.report.MessageReceiver : The new messagereceiver to be
 * removed from the messagedistributor's list for the given messagetype
 */
public void removeReceiver(MessageReceiver msgRec) {
  
  if ( msgRec==null) {
    sendWarning (
      "Can not remove receiver to experiment! Command ignored.",
      "Experiment '"+getName()+"', Method 'void removeReceiver(MessageReceiver "+
      "msgRec)'",
      "The parameter 'msgRec' passed was a null reference.",
      "Make sure to give a valid MessageReciever reference before removing it "+
      "from the experiment's messaging system.");
    return;  // do nothing
  }
  
  messMan.deRegister(msgRec);
  
}
/**
 * Removes a messagereceiver for the given subtype of message from the
 * Experiment's messagedistributor.
 * Whenever a model produces a message of that type, it will not be sent to
 * the given messagereceiver anymore.
 * Note that if the messagereceiver is also registered for other types of
 * messages, these will not be affected.
 * Use method <code>removeReceiverAll(MessageReceiver msgRec)</code>
 * to remove a messagereceiver from all types of messages.
 * @param trcRec desmoj.report.MessageReceiver : The new messagereceiver to be
 * removed from the messagedistributor's list for the given messagetype
 * @param messageType Class : The type of message not to be sent to the given
 * messagereceiver
 */
public void removeReceiver(MessageReceiver msgRec, Class messageType) {
  
  if ( msgRec==null) {
    sendWarning (
      "Can not remove receiver to experiment! Command ignored.",
      "Experiment '"+getName()+"', Method 'void removeReceiver(MessageReceiver "+
      "msgRec, Class messageType)'",
      "The parameter 'msgRec' passed was a null reference.",
      "Make sure to give a valid MessageReciever reference before removing it "+
      "from the experiment's messaging system.");
    return;  // do nothing
  }

  if ( messageType==null) {
    sendWarning (
      "Can not remove receiver to experiment! Command ignored.",
      "Experiment '"+getName()+"', Method 'void removeReceiver(MessageReceiver "+
      "msgRec, Class messageType)'",
      "The parameter 'msgRec' passed was a null reference.",
      "Make sure to give a valid MessageReciever reference before removing it "+
      "from the experiment's messaging system.");
    return;  // do nothing
  }
  
  messMan.deRegister(msgRec, messageType);
  
}
/**
 * Removes a messagereceiver for tracenotes from the
 * experiment's messagedistributor.
 * Whenever a model produces a message of that type, it will not be sent to
 * the given messagereceiver anymore.
 * Note that if the messagereceiver is also registered for other types of
 * messages, these will not be affected.
 * Use method <code>removeReceiverAll(MessageReceiver msgRec)</code>
 * to remove a messagereceiver from all types of messages.
 * @param trcRec desmoj.report.MessageReceiver : The new messagereceiver to be
 * removed from the messagedistributor's list for the given messagetype
 */
public void removeTraceReceiver(MessageReceiver msgRec) {
  
  if ( msgRec==null) {
    sendWarning (
      "Can not remove receiver to experiment! Command ignored.",
      "Experiment '"+getName()+"', Method 'void removeTraceReceiver"+
      "(MessageReceiver msgRec)'",
      "The parameter 'msgRec' passed was a null reference.",
      "Make sure to give a valid MessageReciever reference before removing it "+
      "from the experiment's messaging system.");
    return;  // do nothing
  }
  
  messMan.deRegister(msgRec, tracenote);
  
}
/**
 * Overrides inherited <code>NamedObjectImp.rename(String newName)</code> method 
 * to prevent the user from changing the experiment's name during an
 * experiment.
 * Renaming is not allowed with experiments, since it would not allow
 * the user to identify the reports produced by an experiment.
 * The method simply returns without changing the experiment's name,
 * ignoring the given parameter.
 * @param newName java.lang.String : The parameter given is not taken as the 
 * new name, method simply returns
 */
public void reName(String newName) {
  
  // do nothing since renaming experiments is not allowed
  // would do too much confusion
  
}
/**
 * Writes a report about the model connected top this experiment,
 * its reportable components and all related submodels into the report output.
 * Note that a report can only be produced, if a valid main model
 * is already connected to the experiment.
 */
public void report() {

  // just pass on the call with main model as parameter
  report(client);
  
}
/**
 * Writes a report about the given model which has to be connected to this
 * experiment as main model or as a submodel.
 * Note that this will report about a branch of the tree of submodels
 * constructed. A report will only be produced, if the model given is connected
 * to this experiment.
 * All reportable components of this model and all related submodels will be 
 * sent to the report output configured at the experiment's messagedistributor.
 * Note that a report can only be produced, if a valid main model
 * is already connected to the experiment.
 */
public void report(Model m) {

  Enumeration reporters;  // buffer for the reportmanager returned by client  
  
  if ( status < CONNECTED ) {
    sendWarning (
      "Can not produce report! Command ignored.",
      "Experiment: "+getName()+" Method: void report(Model m).",
      "The Experiment has not been connected to a model to report about yet.",
      "Connect a model to the experiment first using the model's method "+
      "connectToExperiment(Experiment exp).");
    return;  // no client there to be reported
  }

  if ( status >= ABORTED ) {
    // do nothing since experiment has already been aborted and all
    // output channels are already shut down
    return;  // Experiment aborted
  }

  if ( m == null ) {
    sendWarning (
      "Can not produce report! Command ignored.",
      "Experiment: "+getName()+" Method: void report(Model m).",
      "The model parameter given is a null reference.",
      "Always make sure to use valid references.");
    return;  // no model there to be reported
  }

  if ( m.getExperiment() != this ) {
    sendWarning (
      "Can not produce report! Command ignored.",
      "Experiment: "+getName()+" Method: void report(Model m).",
      "The model parameter given is connected to a different experiment.",
      "Only experiments connected to theat model can produce reports "+
      "about that model.");
    return;  // model connected to other experiment
  }

  // get the client's reportmanager containing all reporters in sorted order
  reporters = m.report();

  // get all out according to sorted order and send them to the report output
  // registered at the experiment's messagemanager
  while ( reporters.hasMoreElements() ) {
    
    messMan.receive( ( (Reporter)reporters.nextElement() ) );
    
  }
  
}
  /** Resets the time format to be used for output of true time Strings to
   *  the default pattern: <tt>dd.MM.yyyy HH:mm:ss:SSS</tt>.
   */
  public void resetOutputTimeFormat() {
    trueTimer.resetTimeFormat();
  }
  /** Schedules an <code>ExternalEventTimedTrace</code> event to insert an entry
   *  in the trace file stating the true time (and time unit) of the given
   *  sim time. This private helper method is called in the methods <code>
   *  tracePeriod(SimTime, SimTime)</code>, <code>traceOn(SimTime)</code>
   *  and <code>traceOff(SimTime)</code>.
   *  @param simTime SimTime : the sim time for the event to take place
   *  @param whatTime String : a description of this point in (simulation) time
   *  @param directSuccessor Event : the event before which the generated
   *  <code>ExternalEventTimedTrace</code> event should be scheduled; if no
   *  such event is specified the generated event is scheduled "normally"
   *  at the given sim time.
   */
  private void scheduleTimedTraceEvent(SimTime simTime, String whatTime,
                                       Event directSuccessor)
  {
    int refUnit = trueTimer.getReferenceUnit();
    StringBuffer pattern = new StringBuffer("dd.MM.yyyy HH:mm");
    switch (refUnit) {
      case Units.MS: pattern.insert(16, ":SSS");
      case Units.S : pattern.insert(16, ":ss");
    }
    trueTimer.setTimeFormat(pattern.toString());
    String time = trueTimer.toTrueTime(simTime);
    trueTimer.resetTimeFormat();
    ExternalEventTimedTrace event = new ExternalEventTimedTrace(time,
                                                                refUnit,
                                                                whatTime,
                                                                this.client);
    if (directSuccessor == null) {
       event.schedule(simTime);
    }
    else {
      event.scheduleBefore(directSuccessor);
    }
  }
/**
 * Creates and sends a debugnote to the messagedistributor.
 * Be sure to have a correct location, since the object and method that the
 * error becomes apparent is not necessary the location it was produced in.
 * The information about the simulation time is extracted from the
 * Experiment and must not be given as a parameter. 
 * @param description java.lang.String : The description of the error that
 * occured
 * @param location java.lang.String : The class and method the error occured in
 * @param reason java.lang.String : The reason most probably responsible for
 * the error to occur
 * @param prevention java.lang.String : The measures a user should take to
 * prevent this warning to be issued again
 */
void sendDebugNote(String component, String description) {
  
  // comnpose the DebugNote and send it in one command
  sendMessage( new DebugNote( clientScheduler.getCurrentModel(),
                              clientScheduler.getSimClock().getTime(),
                              component, description ) );
                                
}
/**
 * Sends a message to the messagedistributor.
 * Note that there are other shorthands for sending the standard DESMO-J 
 * messages.
 * @param m Message : The Message to be transmitted
 * @see ModelComponent#sendTraceNote
 * @see ModelComponent#sendDebugNote
 * @see ModelComponent#sendWarning
 */
void sendMessage(Message m) {
  
  if ( m==null ) {
    sendWarning ( "Can't send Message!",
                  "Experiment :"+getName()+" Method: SendMessage(Message m)",
                  "The Message given as parameter is a null reference.",
                  "Be sure to have a valid Message reference.");
    return;  // no proper parameter
  }

  messMan.receive(m);
  
}
/**
 * Creates and sends an error message to the messagedistributor to warn the 
 * modeller that some conditions required by the framework are not met.
 * Be sure to have a correct location, since the object and method that the
 * error becomes apparent is not necessary the location it was produced in.
 * The information about the simulation time is extracted from the
 * experiment and must not be given as a parameter. 
 * @param description java.lang.String : The description of the error that
 * occured
 * @param location java.lang.String : The class and method the error occured in
 * @param reason java.lang.String : The reason most probably responsible for
 * the error to occur
 * @param prevention java.lang.String : The measures a user should take to
 * prevent this warning to be issued again
 */
void sendWarning(String description, String location,
                        String reason, String prevention) {
                        
  // comnpose the WarningMessage and send it in one command
  sendMessage( new ErrorMessage( clientScheduler.getCurrentModel(),
                                   description, location,
                                  reason, prevention,
                                  clientScheduler.getSimClock().g