Comp 212 Programming Assignment #2
SimLaundry 2000

Due 99.November 15 at 11:59:59 P.M. (Monday night)

Introduction

This programming assignment is designed to help you learn how to write a simulation program that is driven by discrete events.  In the process, you will learn how to design the object system for such a program.  You will need to use common container objects such as stacks, queues, and lists for the purpose of proper storage and retrieval of your objects.  You will also learn to apply the MVC pattern to build a GUI application on top of your object model.

Set Up

Copy the following files to your local directory.

    ~comp212/projects/02/*.java
    ~comp212/projects/02/tinyin.txt
    ~comp212/projects/02/tinyout.txt

Program Description

You are to write a program that simulates the following hypothetical world.

Rice student J. H. Acker has decided to drop out of school and become a high-tech billionaire by marketing a virtual reality game based on Acker's own personal hygiene. The game is called SimLaundry 2000, and it models the laundry habits of a typical college student. In this assignment, you will help Acker to create this game, in return for a cut of the profits and a good Comp 212 grade.

We will assume there are only three types of clothing: shirts, pants, and socks. We will add undergarments once Acker joins the Victoria Secrets Society. Acker neatly stacks clean shirts, pants, and socks in separate piles on a shelf in his closet.    Acker has a laundry that has a table where he can pile all of his laundered garments.

When changing clothing, Acker throws dirty clothing onto a pile in the corner of the closet, then selects the top clean item of a particular type from the closet shelf; the resulting outfits rarely coordinate, but Acker is no slave to fashion. If there are no clean clothes of a particular variety in the closet, Acker goes to the clean pile on the laundry table and takes the needed garment starting from the top of the pile.  If there are no such clean garment from the laundry table, Acker removes from the dirty laundry pile the least recently worn article of that type, smells it, and always decides it can be worn again after all. (Acker never has to go naked, because there is at least one item of the desired type in the laundry, namely the one Acker just removed.)

When doing laundry, Acker removes fifteen (or fewer, if the pile isn't that large) items from the top of the dirty clothes pile. In the simulation, a load of clothes is laundered and dried instantaneously and placed on a table for clean clothes reserved for Acker in the laundry room. Acker changes clothes so infrequently that the washing and drying time is negligible, so our simulation is a good approximation. The garments in each load of clean clothes are piled in exactly the same order they appeared in the dirty pile. Acker fills the washer and dryer so full that the clothing doesn't get jumbled up!

Eventually Acker retrieves the clean laundry load, folds it, and places it on the closet shelf. In the process, he reverses the order of the clothing within the load; whatever was on the bottom of the pile on the laundry table is now on top of the appropriate pile (shirts, pants, or socks) of clean clothes on the shelf. Hence, if a blue shirt was on top of a white one in the dirty clothes pile and they are washed in the same load, then the white shirt will be on top of the blue one on the closet shelf.

Acker periodically receives gifts of clothing from relatives, which are placed on the closet shelf. He never buys any clothes.

Acker never discards clothing, no matter how threadbare, but does, on rare occasions, lose some. They can be lost from anywhere, namely the closet shelf, the dirty laundry pile, and the laundry room.

For the purposes of this assignment, a pair of socks is an indivisible article of clothing; we make the unrealistic assumptions that single socks are never lost and that Acker does not wear mismatched socks. Also, you needn't be any more concerned than Acker is about separating white and color laundry or other such niceties.

What you must do

Your job is to write a simulation for Acker's activities.  How do we write such a program?  To start, let us try to define what "simulation"  and "activities" mean.  It is easier to first think about "activities".  In our problem, activities are actions performed by Acker.   We model these activities as objects that manipulate the "things" that exist in Acker's world, such as the clothes he wears, the piles of clean garments, of dirty clothes, and of laundered clothes.  We model Acker's world as a class that contains all these "things".  In the language of simulation, Acker's activities are called (discrete) "events", and Acker's world is called a "simulation agent".  In object-oriented thinking, the events are capable of processing themselves by manipulating the simulation agent.  A "simulation" is simply a class that can repeatedly generate new events, and ask the events to process themselves  as they are produced, using the appropriate simulation agent.  We thus need an event (i.e. activity) factory to generate various activities at run time.   An example of such a factory is an object that can read from an input file containing textual representation of various events.  A simulation run would consist of calling this reader object to read an input file, producing various events, and outputting the event processing. For example, with Acker initially wearing white shirt, socks, and pants, and an input file the following chain of events:

receive blue socks
receive green pants
receive red shirt
change socks
receive yellow shirt
change shirt
outfit
change socks
launder
change pants
fold
change socks

The simulation should produce the following output:

received blue socks
received green pants
received red shirt
doffed white socks, donned blue socks
received yellow shirt
doffed white shirt, donned yellow shirt
wearing yellow shirt, white pants, blue socks
doffed blue socks, donned white socks
washed blue socks, white shirt
doffed white pants, donned green pants
folded blue socks, white shirt
doffed white socks, donned blue socks

We now discuss in details the design of:

• Acker's world, the simulation agent,
• Acker's activities, the discrete events,
• The event factory, a strategy for the simulation to generate events,
• The simulation framework, a generic pattern for implementing simulations.

Simulation Agent

As discussed in the above, Acker's world is the simulation agent.  It contains things that Acker's activities manipulate.  All of Acker's activities can be described at an abstract level as "moving garments around and about his closet and his laundry room".  What kinds of garments do we have? shirts, pants, and socks.   It may not be a bad idea to apply the union pattern here to model the garments.   The closet consists of four piles (i.e. containers) of garment objects: a pile of clean socks, a pile of clean pants, a pile of clean shirts, and a pile of dirty clothes.   The laundry room only has one pile of (clean) laundered clothes.  We need to choose appropriate data structures to model these piles.  The activities need to have access to the piles both from the top and from the bottom for insertion, removal, and search.  The circular list structure (CLList) seems to satisfy our requirements.

Here is the UML diagram describing our initial design of Acker's world.

The meanings of the fields and methods in AckerWorld should be clear here.  We will describe the methods for the garment objects (AGarment and its variants) in the next section where we discuss the design of the simulation events (i.e. activities).

Events

 We represent an event by a Java interface called IEvent.   It has an abstract method called String process ().   Each concrete variant of IEvent will have its own way of processing itself by interacting with the appropriate simulation agent.  We use the union pattern to represent the following six concrete events:

1. Receive (garment)

   Acker receives a garment gift and puts it on top of the appropriate pile.
   process () returns receive attribute name .   For example, receive argyle socks

2. Lose (garment)

   Acker misplaces a garment from one of the piles of clothing.  The garment may or may not exist in the piles.
   If the item exists in the piles,  process () returns lost attribute name
   If the item does not exist, process () returns lost attribute name does not exist

3. Change (garment) 

   Acker dumps the garment he is wearing into the dirty pile and puts on the new garment.
   process () returns doffed attribute1 name1, donned attibute2 name2

4. Launder

   Acker washes and dries a load of dirty clothes from the dirty pile.
   If the dirty clothes pile is not empty, process () returns
   washed attribute1 name1, ..., attibuteN nameN
   listing the clothes in the order they were removed from the dirty clothes pile.
   If the dirty clothes pile is empty, process () returns
   nothing to wash

5. Fold

   Acker retrieves a load of clean laundry, folds it, and puts each garment on the appropriate clean pile.
   If a load of clean laundry is available, process () returns
   folded attribute1 name1, ..., attibuteN nameN
   listing the clothes in the order they are placed on the shelf. Hence the top garment on the shelf should be the last one listed.
   If no load of laundry has been washed and dried, process () returns
   nothing to fold

6. Outfit

   What is Acker wearing?  process () returns
   wearing attribute1 shirt, attribute2 pants, attribute3 socks

Much of the garment movements from one pile to another can be "automated" (i.e. simplified) by making the garment object much more intelligent.  For example,   in the Receive (socks) event, the socks know to go to the dirty pile and the new socks know that they must come from the clean socks pile.   The Java files that are provided to you show some pseudo-code to illustrate this "intelligence". Understanding this code will help enhance your object-oriented programming skill.

NOTE: To lookup and compare the classes of objects, you can use the method getClass() inherited from Object.  

Below is the UML diagram for the event and garment objects.  We add a NullEvent singleton to facilitate event generation.  This is an example of the null object pattern.  Note that the Fold event is a visitor for a CLList as well.  This is a suggested design only.  You are not required to implement Fold this way.  The suggested design for AGarment and its subclasses are incomplete.  You are free to modify the methods of AGarment and its subclasses in any way you see fit, except for the names of the classes and their constructors.  The provided EventReader class that reads input from a text file and produces the appropriate event objects depends on them.  This EventReader class is an example of what is called an event generator in simulation parlance.  We will discuss the notion of event generation in the next section.

Event Factory

 To do simulation, we need to have a way to generate events at run-time.  In pattern language, it's called a factory.  The provided EventReader class is an example of such a factory.  It generates events by reading from a text file, parses it, and instantiates appropriate events, one at a time.  The format for each line of its input file is as follows.

• receive attribute garment-name
• lose attribute garment-name
• change garment-name
• launder
• fold
• outfit

tinyin.txt is an example of such input files.  tinyout.txt is the corresponding out file.

Event generation can come from many other mechanisms.  We represent this abstraction as an abstract class called AEventMaker. Later in the week, you will be given a GUI view and a controller to hook up with your current AckerWorld model without you changing any of your code.   This will serve to reinforce your understanding of the MVC pattern.

Simulation Framework

 Simulation can be done using the framework described by the UML diagram below.

The Simulation class uses an AEventMaker as its strategy for generating events.  We construct a Simulation class, we pass it a concrete subclass of AEventMaker.   Simulation is carried out in a loop that calls for the event generator to produce an event, which is then called to process itself.  For example, I can test your program by writing a main method in a Client class that instantiates a Simulation object with EventReader.Singleton, and calls on the Simulation object to simulate.  I then run the Client by entering the (Unix) command:

java Client < tynin.txt > output.txt

Efficiency

For this assignment, you should be concerned about relevant asymptotic efficiency. Choose the simplest representation that yields good performance on inputs of plausible size. Changing an article of clothing should take constant time (i.e., no searching should be done) provided there's an appropriate garment on the shelf. If the shelf contains no clothing of that type, then in the common case we expect to find one of those near the bottom of the pile, no matter how big the pile is: make that case fast. Infrequent operations need not be blazing fast, because they have little impact on the running time of the entire system. (Suppose one operation accounts for 5% of the runtime, and we can make it run 10 times as fast. How does that compare to making an operation that accounts for 25% of the runtime twice as fast?) .

Submission

Electronic.

Submission Bonus

For each day you submit ahead of the deadline, you will get an additional 2% of your pre-bonus earned grade, up to a maximum of 6% of your pre-bonus earned grade.