Homework 10: SimLaundry 2010

Due 1 Friday, 9 April 2009 2010 at 11:00 A.M. (Wednesday before class)

Preface

This assignment has a long description but the coding involved is straightforward. Most of the code for the full application has been written as support code by the course staff. In the our solution written by the course staff, the remaining code remaining for that you to must write (excluding test code) consists of approximately 175 250 lines (including some terse comments and whitespace lines).

...

The course staff is providing a framework for writing this program that includes many classes and interfaces. The framework is packaged as a zipped DrJava project laundry.zip. This file will unzip into a self-contained file tree with root directory laundry. This directory contains the source tree for the laundry framework with root directory edu, a DrJava project file laundry.drjava and two text files sampleIn and sampleOut used by the sample laundry test class edu.rice.comp211.laundry.tests.LaundryTest. Given the text input in sampleIn, your program should generate the text in sampleOut. The provided framework compiles but LaundryTest will fail because most of the members in two the key classes class DoCommandVisitor and Student have been stubbed out.

After unzipping the laundry.zip file, you can open the DrJava laundry project by starting DrJava, setting the Language Level to Full Java, pulling down the Project menu and selecting the Open command. In the file chooser that pops up, select the project profile file laundry.drjava embedded in the file in the unzipped file tree for laundry.zip. You can save the project state at any point during a DrJava session using the Save command in the Project menu. You can also save individual files within the project using the Save button on command file or the File menu.

The Test Project Test commands runs all of the JUnit test files in the project.

...

• the name of the student,
• the closet shelf with its piles of clean clothes,
• the dirty laundry pile, and
• the laundry room with its piles of laundered garmets sitting on tables.
• and methods to manipulate those data representations to perform the specified simulation

Wiki MarkupWhen the simulation begins, Acker is wearing _white_ pants, _white_ white socks, and a _white_ shirt. The closet shelf, dirty laundry pile, and laundry facilities are all initially empty. The program starts execution using the special method {{public static void main(String\[\] args)}} in class {{Main}}. The {{main}} method interface is the only vehicle for executing Java programs directly from the command line. (DrJava has a {{main}} method for this reason.)

Form of Event Commands

Your program executes a loop that repeatedly reads input from an input "process" that returns Command objects. The input process (provided by our supporting framework) reads a series of event description commands, one to a line, either from the console or from a file. The input process converts a stream of characters to Command objects which are passed to your program.

In addition to performing the specified command, your program should output a brief description of for each command that it performs in the exact format described below. In the following list of commands, the output line specifies what your program should print.

Your solution will be graded using the textual interface. Graphical interfaces are notoriously difficult to test and all of the graphical interface code is part of our support code anyway. Your correctness and testing scores (which each count 25% of your grade) will be based on how well your implementation of each command complies with the given specifications and on how well you demonstrate this compliance with test cases. You can test your DoCommandVisitor using the same approach given in our LaundryTest.java class. These tests use the simulate method in Student to drive the execution of DoCommandVisitor. If you write some utility methods fopr BiLists you should separately test these methods. You are NOT responsible for testing any of our support code in laundry.zip including the BiList class.

A major portion of your grade (35%) will be based on your program style. If you write your code in the OO style practiced in this course, you should do very well on this aspect of the assignment. The remaining 15% of your grade is based on your documentation, particularly your javadoc comments for classes and methods.

Form of Event Commands

Your program executes a loop that repeatedly reads input from an input "process" that returns Command objects. The input process (provided by our supporting framework) reads a series of event description commands, one to a line, either from the console or from a file. The input process converts a stream of characters to Command objects which are passed to your program.

In addition to performing the specified command, your program should output a brief description of for each command that it performs in the exact format described below. In the following list of commands, the output line specifies what your program should print.

• The command

  Code Block
  receive <adjective> <article>

  means Acker received a gift of the specified article (<adjective> <article>) of clothing. In responseThe command

  Code Block
  receive <adjective> <article>

  means Acker received a gift of the specified article (<adjective> <article>) of clothing. In response, the simulation outputs

  Code Block
  received <adjective> <article>

  and updates the state of the StudentEnvironment. For example,

  Code Block
  receive argyle socks

  generates

  Code Block
  received argyle socks

  and adds the argyle socks to the top of the socks pile on the shelf.
  The command

  Code Block
  lose <adjective> <article>

  means Acker misplaced the specified article of clothing. If the item exists and Acker is not wearing it, the simulation outputs

  Code Block
  lost <adjective> <article>

  and updates the state of the StudentEnvironment accordingly. If Acker is wearing it, the simulation outputs

  Code Block
  Acker is wearingreceived <adjective> <article>

  and leaves updates the state of the StudentEnvironment unchanged. If the item does not exist, the simulation outputs . For example,

  Code Block
  <adjective>receive <article> does not exist

  and leaves the StudentEnvironment unchanged

  argyle socks

  generates

  Code Block
  received argyle socks

  and adds the argyle socks to the top of the socks pile on the shelf.
  
  
• The command

  Code Block
  changelose <adjective> <article>

  means Acker doffed misplaced the specified article of clothing, discarding it in the dirty laundry pile, and donned a replacement article using the protocol described above. In response. If the item exists and Acker is not wearing it, the simulation outputs

  Code Block
  doffedlost <adjective> <article>

  and updates the state of the StudentEnvironment accordingly. If Acker is wearing it, the simulation outputs

  Code Block
  Acker is wearing donned <adjective> <article>

  describing the article doffed and leaves the article donned.
  The command

  Code Block
  {{launder}}

  means Acker washed and dried a load of laundry. If the dirty clothes pile is not empty StudentEnvironment unchanged. If the item does not exist, the simulation outputs

  Code Block
  washed <adjective> <article>, ..., <adjective> <article>

  listing the clothes in the order they were removed from the dirty clothes pile. If the dirty clothes pile is empty

  does not exist

  and leaves the StudentEnvironment unchanged.
  
  
• The command

  Code Block
  change <article>

  means Acker doffed the specified article of clothing, discarding it in the dirty laundry pile, and donned a replacement article using the protocol described above. In response, the simulation outputs

  Code Block
  nothing to wash doffed <adjective> <article>, donned <adjective> <article>

  describing the article doffed and the article donned.
  
  
• The command

  Code Block
  fold{{launder}}

  means Acker retrieved washed and dried a load of laundry, folded it, and put it on the closet shelf. If a load of laundry is available. If the dirty clothes pile is not empty, the simulation outputs

  Code Block
  foldedwashed <adjective> <article>, ..., <adjective> <article>

  for the oldest unfolded load. List 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, then the simulation outputs were removed from the dirty clothes pile. If the dirty clothes pile is empty, the simulation outputs

  Code Block
  nothing to fold wash

  
  
• If the oldest load is empty (because all items in it were lost), the simulation outputs

  Code Block
  folded empty load

  The command

  Code Block
  outfitfold

  asks "what is Acker wearing?" The means Acker retrieved a load of laundry, folded it, and put it on the closet shelf. If a load of laundry is available, the simulation outputs

  Code Block
  wearingfolded <adjective> <shirt><article>, <adjective> pants..., <adjective> socks<article>

Supporting Code and Programming Details

Our supporting framework is provided in the zip file laundry.zip. The test input in the file sampleIn (with corresponding output) sampleOut is far from comprehensive.

• for the oldest unfolded load. List 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, then the simulation outputs

  Code Block
  nothing to fold

  If the oldest load is empty (because all items in it were lost), the simulation outputs

  Code Block
  folded empty load

  
  
• The command

  Code Block
  outfit

  asks "what is Acker wearing?" The simulation outputs

  Code Block
  wearing <adjective> <shirt>, <adjective> pants, <adjective> socks

Supporting Code and Programming Details

Our supporting framework is provided in the zip file laundry.zip. The test input in the file sampleIn (with corresponding output) sampleOut is far from comprehensive.

All of our supporting code is included in the unzipped project. Each file All of our supporting code is included in the unzipped project. Each file resides in a package that is identified by a package statement at the beginning of the file. Most support classes are public so that they can be accessed anywhere. Classes without a visibility modifier have "default" visibility, which means that they can only be accessed from classes within the same package.

...

ReadIteratorI which includes methods for moving a cursor through lists implementing the EnumI interface.

The interfaces are already defined in the framework provided by the course staff.

The input processor class TerminalIO implements the IOProcess interface. You are welcome to inspect the code of TerminalIO but it relies heavily on the Java I/O library, particularly the class StreamTokenizer . To understand this code, you will need to read Chapter 11 of JLS (or similar reference). The framework also includes implementations of EnumI and ReadIteratorI as part of a BiList (mutable circular doubly linked list) class implementation.

The Student class implements the StudentEnvironment interface, which includes the simulate method supporting the laundry simulation. The simulate method contains a loop that reads commands from its IOProcess and invokes DoCommandVisitor on each command. Within the DoCommandVistor class you must implement methods that process the various possible commands.

The program includes two class definitions defining unions (composites without recursion): Garment, specifying the representation of garments that appear in the input stream, and Command, specifying the representation of event description commands. Both classes include the hooks required to support the visitor pattern. The data definition for Garment is important because the GUI IOProcess included in the framework animates the state of your implementation before each command. This IOProcess expects the garments that appear as elements in lists (as revealed by the EnumI and ReadIteratorI interfaces) to be instances of the Garment class. Hence, you must use the representation of garments that our class Garment provides.

The file DoCommandVisitor.java contains comments describing all of the members that you need to write. This class could have been defined as an inner class of Student but we made it a top level class to simplify debugging.

The IOProcess interface includes a method PrintStream open(StudentEnvironment a, boolean debug) which initializes an IOProcess object for a laundry simulation of the specified environment and returns the PrintStream object to be used for terminal output. (Up to now you have implicitly used the PrintStream object System.out.) The PrintStream method println(String s) prints the string s followed by a newline character to the PrintStream. The boolean debug argument indicates whether or not debugging output should be produced. The IOProcess interface also includes a method nextCommand which reads the next command from the input channel supported by the IOProcess object.

Each call on nextCommand returns the next command in the stream provided by the IOProcess object, until it reaches an end-of-file ({-d} from the keyboard). End-of-file is reported as a null reference of type Command.

The nextCommand method in TerminalIO processes character strings consisting of words separated by ``space'' characters such as ' ' and '\n' . A word is any sequence of printable characters other than space, '\n' (newline), and '\r' . (return). An adjective must be a single word. An article must be one the words shirt , pants , or socks . The same adjective, say argyle may be applied to garments of different types, but there are no duplicate items of clothing.

The program passes a boolean debug flag to (TerminalIO). The value of the flag is true iff the command line argument -d or -debug is passed to main .

The GUI Interface

In principle, the GUI interface to the laundry simulation (implemented by SimLaundryApplication and affiliated classes) could have been written as an alternate implementation of the IOProcess interface. But in Java GUIs (and GUIs in other languages) essentially all code that accesses and updates GUI components must run in the event-handling thread of the Java Virtual Machine. When the program runs in TerminalIO mode, the Main class creates a student and runs the simulation (using the simluate method in Student) in the main thread. A GUI implementation of IOProcess would have to install closures (called listeners or callbacks) in the Student class that would run whenever the state of Acker's world changed (as displayed in the GUI window). The Student class would have to be extended to include methods that accept such listeners and code to execute the appropriate listeners whenever the state of some object in Acker's world changed. But note that these listeners will run in the main thread unless the code in the listeners specifically addresses this issue. The listener code can send closures (technically anonymous classes implementing the Runnable interface) to the event-handling thread using the methods invokeLater and invokeAndWait.

implementing the EnumI interface.

The interfaces are already defined in the framework provided by the course staff.

The input processor class TerminalIO implements the IOProcess interface. You are welcome to inspect the code of TerminalIO but it relies heavily on the Java I/O library, particularly the class StreamTokenizer . To understand this code, you will need to read Chapter 11 of JLS (or similar reference). The framework also includes implementations of EnumI and ReadIteratorI as part of a BiList (mutable circular doubly linked list) class implementation.

The Student class implements the StudentEnvironment interface, which includes the simulate method supporting the laundry simulation. The simulate method contains a loop that reads commands from its IOProcess and invokes DoCommandVisitor on each command. Within the DoCommandVistor class you must implement methods that process the various possible commands.

The program includes two class definitions defining unions (composites without recursion): Garment, specifying the representation of garments that appear in the input stream, and Command, specifying the representation of event description commands. Both classes include the hooks required to support the visitor pattern. The data definition for Garment is important because the graphical version of the user interface included in the framework animates the state of your implementation before each command. This graphical user interface (GUI) expects the garments that appear as elements in lists (as revealed by the EnumI and ReadIteratorI interfaces) to be instances of the Garment class. Hence, you must use the representation of garments that our class Garment provides.

The file DoCommandVisitor.java contains comments describing all of the members that you need to write. This class could have been defined as an inner class of Student but we made it a top level class to simplify debugging.

The IOProcess interface includes a method PrintStream open(StudentEnvironment a, boolean debug) which initializes an IOProcess object for a laundry simulation of the specified environment and returns the PrintStream object to be used for terminal output. (Up to now you have implicitly used the PrintStream object System.out.) The PrintStream method println(String s) prints the string s followed by a newline character to the PrintStream. The boolean debug argument indicates whether or not debugging output should be produced. The IOProcess interface also includes a method nextCommand which reads the next command from the input channel supported by the IOProcess object.

Each call on nextCommand returns the next command in the stream provided by the IOProcess object, until it reaches an end-of-file (<control>-d from the keyboard). End-of-file is reported as a null reference of type Command.

The nextCommand method in TerminalIO processes character strings consisting of words separated by ``space'' characters such as ' ' and '\n' . A word is any sequence of printable characters other than space, '\n' (newline), and '\r' . (return). An adjective must be a single word. An article must be one the words shirt , pants , or socks . The same adjective, say argyle may be applied to garments of different types, but there are no duplicate items of clothing.

The program passes a boolean debug flag to (TerminalIO). The value of the flag is true iff the command line argument -d or -debug is passed to main .

The Graphical User Interface (GUI)

But for simple GUIs applications like this laundry simulation, it is often simpler to write the GUI as an application that is driven by GUI events. The initialization of the GUI creates an Acker Student object and associated DoCommandVisitor. Each GUI event triggers the execution of DoCommandVisitor; in some cases, such as reading input from a file, it triggers the execution of DoCommandVisitor on a stream of Commands. In essence, the event-handling loop built-in to the Java Swing framework is used to drive the computation rather than a separate loop in the main thread such as the one in the simulate method in Student. writing the GUI as an implementation of IOProcess means the program has the computation rather than a separate loop in the main thread such as the one in the simulate method in Student.

The GUI could also have been written as an implementation of the IOProcess interface. This approach, which conforms to the classic "model-view-controller" (MVC) pattern, is more flexible because it decouples the GUI (the view in MVC terminology) from the model, but it is also more complex because it involves the cooperative execution of
two loops in separate threads--a main program loop in the simulate method of Student and the loop driving the event-handling thread supporting the processing of GUI inputs. The SimLaundryApplication dispenses with the main program loop by absorbing the application (often called the model) into the GUI (often called the view),.

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.

...