Programming Assignment

Due:

Please make sure you adhere to the policies on academic honesty.

Please see the general programming webpage for details about the programming environment for this course, and specifically for directions in how to submit your programming assignment electronically.

The files you need for this assignment can be downloaded here.

Overview

Web browsers commonly allow you to navigate through a "history" of web pages which have previously been visited. Example 4.1 of the textbook suggests that a stack ADT might be used to maintain this history, allowing the user to step "back" to get to the previously visited sites. If a web browser could hold infinitely many entries in its history, then this analogy might be valid. In reality, there may generally exist some fixed limit on the size of the history.

If the history must exist with a fixed maximum capacity, one approach may be to use the ArrayStack implementation of a Stack, as given in Code Fragment 4.4-4.5 of the text. In the case where an item is pushed onto an already full stack, this implementation throws up its hands (i.e., throws an Exception).

This is not how your Web browser behaves. If it only has room to save 50 pages in its history and yet you visit more pages, it will make room in the history for a new page by throwing away the page which is on the very bottom of the history (i.e., the least recently visited page). The formal Stack interface does not help, as it gives us no way to directly access or remove the object on the bottom of the stack.

In this assignment, we define a new ADT which we call a WebHistory. The interface for a WebHistory is very similar to the interface given for a Stack. However in the case when the capacity is exhausted, a call to push will result in the placement of the new page at the expense of the loss of the least recently accessed page. The interface is provided online in a file WebHistory.java.

/**
 * Interface for a web history: a collection of objects
 * that are inserted and removed according to the 
 * last-in first-out principle, but with overflow handled
 * by the removal of the least-recently accessed item.
 * 
 * @author Michael Goldwasser
 * @see WebHistoryEmptyException
 *
 * Any class which implements this interface should allow
 * a constructor which takes an integer parameter specifying
 * the maximum number of elements which the history will hold
 * e.g., 
 *          public class MyWebHistory implements WebHistory {
 *            public MyWebHistory(int maximum) {
 *               // set the maximum history size
 *            }      
 *          }      
 */

public interface WebHistory {
  /**
   * @return number of elements in the history.
   */
  public int size();

  /** 
   * @return true if the history is empty, false otherwise. 
   */
  public boolean isEmpty();

  /** 
   * @return top element in the history.
   * @exception WebHistoryEmptyException if the history is empty. 
   */
  public Object top() throws WebHistoryEmptyException;  

  /**
   * Insert an element at the top of the history making room, if
   * necessary, by removing the item at the bottom of the history.
   * @param element element to be inserted.
   */
  public void push (Object element); 

  /** 
   * Remove the top element from the history
   * @return element removed.
   * @exception WebHistoryEmptyException if the history is empty.
   */
  public Object pop() throws WebHistoryEmptyException; 
}

Files to Submit

You should submit the following files,
WebHistoryA.java, WebHistoryB.java, readme and inputfile,
as detailed below.

Your Task

For this assignment, you will be required to give two different implementations for the WebHistory interface, as described below. We will provide you with template files for these classes which you can modify.

WebHistoryA.java
One way to implement a WebHistory is as follows. Use the ArrayStack implementation verbatim from the book, modifying only the push method accordingly. In the case when pushing onto a "full" history, use a loop to shift all items down one location in the array. By doing this, you will lose your reference to the bottommost item while opening up the topmost location for the newly pushed object.
WebHistoryB.java
A second way to implement a WebHistory is to use an array viewed in a circular manner. You can mark the "top" and the "bottom" of the circular history by keeping two extra integer variables. With a bit of care, you can efficiently handle pushes, even those involving overflow.
Please note that the text uses a circular array to implement a Queue using an array in chapter 4.2.2. You may find this discussion quite informative, but please note two important differences. First, a Queue and a WebHistory do not have the same behavior. Second, the text's implementation of a Queue with an array of size N-1 items. For a WebHistory, you must carefully ensure that you maintain a history of the specified capacity. Of course you can always choose to use an array of size one larger if you wish, so long as you carefully adapt the technique.

Readme File

For each assignment, you are to submit a separate file "readme" as specified in the general programming webpage. For this assignment, you should include two separate tables, similar to Table 4.1 on page 144 of the text, summarizing the worst-case asymptotic running times for your implementations. One table should discuss WebHistoryA and one should discuss WebHistoryB.

Test Input

Part of developing good software is also knowing how to develop meaningful input for testing your software. For this reason, we are going to ask you to submit a file named "inputfile" which can be used to test other students' programs. The goal is to create test input which causes as many as possible of the other students' programs to fail in some way. (Please note that your goal is to cause mistakes in the student-written routines. You will not get credit for finding mistakes in the driver which we provide, although you should certainly report any such bugs directly to us.)

Please note that our input competition will be graded using automation. Therefore, you must make sure that your "inputfile" strictly adheres to the file format which is expected by the the text-based driver, WebHistoryDriver, which we describe below. In order to make sure that your inputfile follows the proper format, we strongly recommend that you run your program on your inputfile to make sure it is accepted by the driver.

Your file may use at most 100 commands. If your input file contains more than the prescribed number of commands, we will simply truncate the end of the file.

Here is a sample input file, appropriately formatted.

Files you will need

The files you need for this assignment can be downloaded here.

Drivers

We will provide you with two different drivers which you may find very helpful in testing your implementations. One driver is menu-driven, using text input from either the keyboard or a file. The other driver is an "Applet" which has a graphical user interface.

WebHistoryDriver.java
This is a text-based, menu-driven program for testing your web history implementations. The menu allows you to call any combination of WebHistory methods. You may even call the constructors for either of the two implementations anytime you want to restart with a different capacity.
By default, the program takes input from the keyboard. However the driver has an optional feature which allows it to read input from a file rather than from a keyboard. The file should have the identical characters which you would use if you were typing them yourself on the keyboard. This feature simply allows you to test and retest your program on a particular input without having to retype the input each time you want to run the program. It is also convenient at times when running with a debugger to have the input read from a file rather than from the keyboard. If the program reaches the end of the file without exiting, then it will revert back to reading input from the keyboard for the remainder of the program.
To use this feature, you must specify the exact filename (including any suffix), as a single argument at runtime. Details on how to provide such arguments are given in the general programming webpage.
WebHistoryApplet.java
This program allows you to test your implementations from a graphical interface that allows you to call methods by the click of a button.
While the menu-driven program keeps a single WebHistory active at any given time, the applet actually keeps two WebHistory's active - one for each of the two implementations. Every time you call a method, that method is called for both WebHistoryA and WebHistoryB. A correct program will always demonstrate the same behavior for each of the two implementations (However showing the same behavior for each of the implementations does not guarantee that the behavior is correct).
We have included an html file WebHistoryApplet.html which can be used in viewing the applet. Further instructions for running an applet can be found in the general programming webpage.

Grading Standards

The assignment is worth 10 points. Eight points will be awarded based on our own evaluation of your assignment and the readme file. One additional point will be awarded fractionally based on how well your program performs on other students' test inputs. The final point will be awarded fractionally based on how well your test input fools other students' flawed programs.

Hints Regarding Modular Arithmetic

When dealing with an array in a circular fashion, there are many possible ways for adjusting indicies as they "wrap around" the ends of the array. The text chooses to use modular arithmetic (the "%" operator in Java). Further discussion of this topic can be found in the general programming webpage.

Last modified: 11 September 2002

Programming Assignment

Due:

Contents: