Contents:

• Overview
• Collaboration Policy
• Formal Requirements
• Artifacts to Submit
• Extra Credit

Topic: Stopwatch
Related Reading: Ch. 4 of text
Due: Tuesday, 27 September 2011, 11:59pm

The goal of this assignment is to provide experience in writing event handlers in Java. To do this, we will have you develop a simple stopwatch application.

Collaboration Policy

For this assignment, you must work individually.

Please make sure you adhere to the policies on academic integrity in this regard.

Formal Requirements

You are the implement a Stopwatch class that provides a stand-alone window performing as a stopwatch. You may rely on a simple flow layout to produce an interface similar to the following:

To ensure decent object-oriented principles in your code, we will be testing your class using the following simple main routine:

public static void main(String[] args) {
  new Stopwatch();
  new Stopwatch();
}

Functionality

The time is to be kept with precision to the hundredth of a second (including displays with trailing zeros when necessary, as in 3.50). The start button should start the stopwatch (if not already running). The stop button should stop the stopwatch if it is currently running. The reset button should reset the displayed time to 0.00. A reset should not alter the running state; that is, a reset when running should reset the time while continuing to count.

• javax.swing.JFrame
• javax.swing.JButton
• javax.swing.JLabel
• javax.swing.Timer
• java.awt.event.ActionListener interface
• String.format function

Artifacts to Submit

Your assignment should be submitted electronically (details on the submission process).

• Source Code
  Please submit a single file Stopwatch.java containing your source code.

• Readme File
  Submit a separate text file named "readme" that provides a brief overview of your program an any interesting design decisions that you made. You may include any other discussion that you feel will be helpful when grading your assignment, for example, if there are known bugs or problems with your program.

Extra Credit

If modeling your code on examples from our textbook, you may have used the command setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE) for the stopwatch JFrame. That signifies that when the JFrame window is closed, the entire application should be immediately exited. Without that command, the window is closed but the application is technically still running (you can kill it in the command line by Cntr-C, or in Eclipse by clicking on the red square in the console toolbar.)

While the EXIT_ON_CLOSE is a reasonable rule for an application that only has one window, it causes an undesirable effect. If two stopwatch windows are displayed by the application, closing either one of them causes the entire program to exit. Or if the stopwatch window was used as part of a larger application, closing the stopwatch would exit the whole application. For extra credit, we want you to modify the Stopwatch class to provide a more appropriate resolution. However, doing so requires a bit more understanding about multithreaded programming.

Traditional programs have a single thread of control, based upon the commands in the main routine of the application. But when a new window is opened in Swing, a new thread is created for managing the window and its events. The overall program typically continues to execute until all threads terminate. This is a good thing, as it allows a program like the Stopwatch tester to continue executing, even when the primary flow of control reaches the end of the main routine. If the secondary thread is still alive, the program remains alive.

The question then arises as to when the overall program should exit, or what should happen if the user closes the GUI window through the operating system (typically by clicking on the "X" icon on the title bar). By default, when a JFrame window is closed, the window is removed from the screen but its underlying thread remains alive. The book's use of EXIT_ON_CLOSE not only forces the termination of the window's controlling thread, but the immediate termination of the entire application.

A more balanced approach can be specified by using the option DISPOSE_ON_CLOSE. In a typical setting, this causes the window's controlling thread to terminate, but does not automatically end the overall application. At a higher level, the overall application formally terminates once all of its threads have terminated. In the context of this Stopwatch assignment, this means that a one-line change gets us much closer to a desirable behavior. By using DISPOSE_ON_CLOSE, we have the possibility of keeping the program alive until both stopwatches have been closed. However, it is not quite so easy (and we cannot give extra credit for a one-line change).

The remaining problem is the following. If you happen to close the stopwatch window when the underlying Timer is still running, the thread does not immediately terminate. The timer keeps it alive indefinitely (and thus keeps the overall program running indefinitely). For a robust solution, you must make sure that when the user closes the window that you stop the Timer from running. But you need to be able to detect when the window is closed. Fortunately, this can be done in accordance with the WindowListener class in Java. Much like button can announce its events, a top-level window has a set of possible events that it is able to announce (such as when it is opened, closed, iconified, deiconified). If you want to provide your own responses to those window events, you can do so by defining a class implementing the WindowListener interface, and registering that listener with the JFrame.

For extra credit, read the relevant documentation and update your Stopwatch class implementation so that it provides this more robust reaction to a window being closed. If you are successful, the program should still work with the same main routine provided for the regular assignment, but you should find that the application cleanly terminates after both stopwatch windows are closed (regardless of whether the user left the timers running or not). Please make sure to note your attempt at extra credit as part of your readme file.