JAVA VERSION AND PLATFORM: - The application has been tested with java latest version 1.4.2. - No deprecated methods have been used. - The platform used to develop was Win XP Pro. - The application has been tested on Solaris machine. The speed at which the GUI is refreshed is extremely low when tested on machines in the Unix lab. GENERAL DESCRIPTION The Elevator Simulation application compares different Elevator algorithms for elevator movement. It consists of 2 parts - Simulator and GUI. The simulation determines which algorithm will minimize average wait time and average total trip time (wait time plus time in the elevator). PACKAGE DESCRIPTION The application consists of 3 packages: project.simulator - for simulator classes project.gui - for gui classes project.events - for events classes The classes which are used in common are put in project DESIGN DESCRIPTION GENERAL DESIGN The simulator adopts an Event based mechanism to simulate different algorithm actions. The sequence of generation of events and the action performed by the events differ based on the algorithm used for simulation. For a particular action, the appropriate event is generated and added to an Event Queue. Eventually, the Simulator retrieves the event from the queue and executes it. The event in itself has all the information needed to perform the action for which it is responsible for. The Simulator, after having executed the event, adds it to yet another queue, the GUI Queue. The dumb GUI, which is unaware of the simulator happenings, redraws the GUI based on the event it is working on. The Simulator and GUI run on two different threads to make sure that the GUI actions do not affect the performance of the simulator. There are 2 different hierarchies - Event and Algorithm. They are explained below: EVENTS HIERARCHY DESIGN An event is implemented using the abstract Event . Every event which extends the abstract Event has the following responsibilities when executed by the simulator: - Setting the message to be logged in the log file - Updating the Building structure - Generating the successive event The Event logs the message set by the sub classes and adds the event to the GUI queue. The GUI retrieves the event eventually and redraws the part of screen relating to the event. The Event base class is refactored to initialize the fields used by most of the sub classes. The sub classes invoke super class' constructor to initialize the fields. (A few examples of the fields initialized are LogWriter handle, Algorithm handle, ElevatorSimulation handle) The next event generated by any event is dependent on the algorithm used for the simulation. To abstract the branching on algorithm, an AlgorithmFactory is designed to determine the algorithm. This is explained in the next section. To abstract the generation of new event in each Event class, the generateNewEvent() method is refactored and a separate sub class is created for this event, one for every algorithm which generates a different set of new events. Instead of passing the LogWriter handle to each sub Event to log message, the logging is done in the base Event class and the string to be logged is alone set by the sub classes. ALGORITHM HIERARCHY DESIGN Every algorithm consists of methods to create a particular new event. The dumb and express algorithms have a lot of similarities, hence lot of Events in common. The creation of such events in common is done one level up in hierarchy in the AbsDumbExpressAlgorithm. Similarly creation of common events for Standard and Intelligent algorithms is done in AbsStandardIntelligentAlgorithm. The creation of events common for all algorithms is done by introducing one more level of abstraction - by having a base Algorithm class which has the common methods. ALGORITHM FACTORY DESIGN This singleton class obviates the need for branching on algorithm in every event class. It creates an instance of the appropriate Algorithm class by consulting the properties and returns the Algorithm handle. This Algorithm handle is used by the event classes to create new events. LOG DESIGN The log file has to be updated during the execution of every event. It has to be changed when the user changes the log file in the property. A separate LogWriter class, when passed a file name, - creates a stream for the file - opens the stream in append mode - emits a specified string to the stream - closes the previous stream and constructs a new one if the log file is changed PROPERTIES DESIGN The ElevatorSimulationProperties class, which extends the standard library Properties sets the protected field (default) of Properties to a set of default property values which have been tested and fixed. If the user specified property file misses some of the property key value pairs, it is taken from the default Properties list. The properties are also validated and error window is popped up for invalid values. Every time the user changes any property or property file, the simulator is notified of the change through ElevatorSimulation. These updated values are displayed on the running statistics screen. RESULTS DESIGN The LogWriter is used to create a Results file stream. When LogWriter is constructed without a filename, the Standard Output stream is opened. A Statistics class holds information needed for the statistics management. Statistics is reset for every run of the simulation. The statistics are displayed both on GUI and results file GUI DESIGN The events communicate with GUI using the ElevatorSimulationUI interface. The GUI thread retrieves the event from the GUIQueue and invokes redraw on the event, passing the ElevatorSimulationUI handle. This interface comprises of GUI methods to redraw elevator, floor, passenger , report error, update clock. Design for Building Panel Building Panel is used to hold two arrays. One array is for all ElevatorCanvas, the other is for all FloorCanvas. Both extend Canvas. Both these canvas classes contain many private methods which draw the floor and elevator with passengers on them. It uses different color bars (if no image available) to show whether passenger is going up or down, and the color of the elevator frame changes to white for door open , and changes back to green for door close. Passengers on the queue are laid out one after another so the number of passengers on floors and elevators can be counted. ERROR HANDLING A Error window is displayed when the user specifies an invalid property value or file. The ElevatorSimulation uses the ElevatorSimulationUI to communicate the error from the simulator to GUI. ALGORITHMS DESCRIPTION The Dumb, Standard, Intelligent and Express algorithms have been implemented as directed. Genius Algorithm: It is a better version of Intelligent. It does the following: Before any elevator goes idle (it has reached the destination floor and there are no passenger to load or unload), the ground floor is checked for any waiting passengers. If there are, the elevator moves down to the ground floor. On the way, it picks up passengers going down. Since in busy hours the ground floor has more passenger population, this algorithm gives extra attention to the ground floor and hence helps bring down the average trip time of passengers. GUI DESCRIPTION LOOK AND LAYOUT DESCRIPTION: The GUI consists of the following components: - A outer enclosing frame - A Control Panel on the left o Has a Clock display area at the top o Running statistics display area at the center o 2 panels of buttons, one for play, stop, pause, other for change property and change file - A Building Panel on the right. It has o one Canvas for each Elevator o one canvas for each floor Border layout, Flow layout and Grid Layout are used in the appropriate places. USER CONTROLS AND FEATURES IMPLEMENTED: The user can start, stop, pause, change property or change file. These are implemented as buttons. All the buttons are implemented as different commands and are executed by a single button listener. Play Button - used to start, resume and restart the simulation. - If pressed after pause, it is resume. If pressed after stop, it is restart Stop Button - used to stop the simulation. When play is pressed, it's a new run of the simlation Pause Button - used to pause the simulation Change Property Button - Displays a new property window. This window has all the property and values displayed in a table format. At the bottom, it has a change and a cancel buttons The changes are saved only if change is pressed Change File Button. Change File Button - Displays a file chooser and if the user specifies a corrupt file, it displays error message. CLASSES DESCRIPTION: ElevatorSimulation - kick starts the application. - creates Simulator and GUI - coordinates the communication between simulator and gui - Singleton class Generic classes LogWriter - Handle to create and update log and results file Statistics - Statistics information for results file and statistics display on GUI Simulator classes: ElevatorSimulator - Initializes building based on property and decides on the algorithm. Executes events on the EventQueue and adds it to the GUI queue Building - represents the building under consideration Elevator - represents an elevator Passenger - represents a person using the elevator. PassengerQueue - Queue to hold the passengers Floor - represents the floor Direction - represents Direction of Elevator Exponential - Exponential Distribution UniformDistribution - Uniform Distribution Event Classes: Event - abstract base class Generic Events - all the events extend Event StartEvent PassengerGenEvent OpenDoorEvent CloseDoorEvent LoadPassengerEvent UnloadPassengerEvent MoveElevatorEvent ClockEvent TerminateEvent Events specific to Dumb StartEventDumb MoveElevatorDumb Events specific to Express StartEventExpress MoveElevatorExpress Events specific to Standard PassengerGenEventStandard Events specific to Intelligent PassengerGenEventIntelligent Events specific to Genius MoveElevatorEventGenius CloseDoorEventGenius Events specific to Dumb and Express CloseDoorEventDumbExpress PassengerGenEventDumbExpress Events specific to Standard and intelligent StartEventStandardIntelligent MoveElevatorEventStandardIntelligent Algorithm classes: AlgorithmFactory - creates the appropriate Algorithm class based on the property file - Singleton class Algorithm - Abstract base class AbsDumbExpressAlgorithm - extends Algorithm Abstract class which has the create methods common to dumb and express algorithm AbsStandardIntelligentAlgorithm - extends Algorithm Abstract class which has the methods common to standard and intelligent algorithm DumbAlgorithm - Extends AbsDumbExpressAlgorithm ExpressAlgorithm - Extends AbsDumbExpressAlgorithm StandardAlgorithm - Extends AbsStandardIntelligentAlgorithm IntelligentAlgorithm - Extends AbsStandardIntelligentAlgorithm GeniusAlgorithm - Extends AbsStandardIntelligentAlgorithm GUI classes ElevatorSimulationUI ElevatorSimulationGUI GUIControlPanel GUIPropertyWindow ElevatorCanvas FloorCanvas GUIQueue Inner classes of GUIControlPanel ButtonListener - listens different button presses Command - interface StartButtonCommand - invoked for start button StopButtonCommand - invoked for stop button PauseButtonCommand - invoked for pause button ChangePropertyCommand - invoked for change property ChangeFileCommand - invoked for change file OUTPUT The various algorithms have been tested under busy, free and moderate occupancy conditions. The sample runs are included in OutputRuns.txt ANALYSIS OF OUTPUT: A glimpse of the output shows that the Genius algorithm performs better than other algorithms for most of the situations. KNOWN ISSUES: The GUI canvas is not repainted if the window is minimized or focus is changed. This could be fixed using some ideas from Double Buffering ACKNOWLEDGEMENT During the process of development, references were made to Prof. Ethan Bolker's Example code for Elevator Simulation Project Members : Xuedong Chen, Sowmya Venkat Project : Elevator Simulation Course : CS680 Date : 12-10-03 compiling and Running the application ------------------------------------- build.bat - compiles in pc run.bat - runs the application in pc build.sh - compiles in unix run.sh - runs in unix