Simple Address Book

Introduction Requirements Analysis Use Cases Design Class Responsibility Collabolator (CRC) Cards Sequence Diagrams Class Diagram Detailed Design Detailed Design

Requirements and User Interface for a Simple Address Book

The software to be designed is a program that can be used to maintain an address book. An address book holds a collection of entries, each recording a person's first and last names, address, city, state, zip, and phone number. It must be possible to add a new person to an address book, to edit existing information about a person (except the person's name), and to delete a person. It must be possible to sort the entries in the address book alphabetically by last name (with ties broken by first name if necessary), or by ZIP code (with ties broken by name if necessary). It must be possible to print out all the entries in the address book in "mailing label" format. It must be possible to create a new address book, to open a disk file containing an existing address book to close an address book, and to save an address book to a disk file, using standard New, Open, Close, Save and Save As ... File menu options. The program's File menu will also have a Quit option to allow closing all open address books and terminating the program. The initial requirements call for the program to only be able to work with a single address book at a time; therefore, if the user chooses the New or Open menu option, any current address book will be closed before creating/opening a new one. A later extension might allow for multiple address books to be open, each with its own window which can be closed separately, with closing the last open window resulting in terminating the program. In this case, New and Open will result in creating a new window, without affecting the current window. The program will keep track of whether any changes have been made to an address book since it was last saved, and will offer the user the opportunity to save changes when an address book is closed either explicitly or as a result of choosing to create/open another or to quit the program. The program will keep track of the file that the current address book was read from or most recently saved to, will display the file's name as the title of the main window, and will use that file when executing the Save option. When a New address book is initially created, its window will be titled "Untitled", and a Save operation will be converted to Save As ... - i.e. the user will be required to specify a file.

User Interface
Because this is to be a "standard GUI" style application, some attention needs to be given to the user interface at this point. A user interface like the following might be adopted. Not shown in the screen shot is a File menu with New, Open, Close, Save, Save As ..., Print, and Quit options. For the "Edit" and "Delete" buttons, the user must first select a person in the scrolling list of names, and then can click the appropriate button to edit/delete that person.

Use Cases for a Simple Address Book

In the following, use cases are listed in the natural order that a user would think of them. In the actual File menu, items that correspond to the various use cases will be listed in the traditional order, which is slightly different.

Flows of Events for Individual Use Cases

Add a Person Use Case

The Add a Person use case is initiated when the user clicks the "Add" button in the main window. A dialog box appears, with title "New Person", containing fields for the user to fill in the new person's first and last names and other information. The box can be dismissed by

clicking either "OK" or "Cancel". If the "OK" button is clicked, a new person is added to the end of the address book, and the person's name is added to the end of the list of names in the main window. If the "Cancel" button is clicked, no changes are made either to the address book or to the main window.
Edit a Person Use Case

The Edit a Person use case is initiated when the user either highlights a name in the list of names in the main window and then clicks the "Edit" button, or the user double-clicks a name. In either case, a dialog box, with title "Edit person's name", appears containing current information about the person selected, (except the person's name, which appears only in the title). The user can then edit the individual fields. The box can be dismissed by clicking either "OK" or "Cancel". If the "OK" button is clicked, the entry in the address book for the selected person is updated to reflect any changes made by the user. If the "Cancel" button is clicked, no changes are made to the address book.
Delete a Person Use Case

The Delete a Person use case is initiated when the user highlights a name in the list of names in the main window and then clicks the "Delete" button. A dialog box appears, asking the user to confirm deleting this particular individual. The box can be dismissed by clicking either "OK" or "Cancel". If the "OK" button is clicked, the entry in the address book for the selected person is deleted, and the person's name is deleted from the list of names in the main window. If the "Cancel" button is clicked, no changes are made either to the address book or to the main window.
Sort Entries by Name Use Case

The Sort Entries by Name use case is initiated when the user clicks the Sort by Name button in the main window. The entries in the address book are sorted alphabetically by name, and the list in the main window is updated to reflect this order as well.
Sort Entries by ZIP Use Case

The Sort Entries by ZIP use case is initiated when the user clicks the Sort by ZIP button in the main window. The entries in the address book are sorted by zip code, and the list in the main window is updated to reflect this order as well.
Print Entries Use Case

The Print Entries use case is initiated when the user chooses "Print" from the File menu. A save file dialog is displayed, and the user is allowed to choose a file to print the labels to. (If the user cancels the file dialog, the Print operation is canceled.) The current contents of the address book are written out to the specified file (in their current order) in "mailing label" format. No information maintained by the program is changed.

Create New Address Book Use Case

The Create a New Address Book use case is initiated when the user chooses "New" from the File menu. If the current address book contents have been changed since the last successful New, Open, Save, or Save As ... operation was done, the Offer to Save Changes extension is executed. Unless the user cancels the operation, a new empty address book is then created and replaces the current address book. This results in the list of names in the main window being cleared, the current file becoming undefined, and the title of the main window becomes "Untitled". (NOTE: These conditions will also be in effect when the program initially starts up.)
Open Existing Address Book Use Case

The Open Existing Address Book use case is initiated when the user chooses "Open" from the File menu. If the current address book contents have been changed since the last successful New, Open, Save, or Save As ... operation was done, the Offer to Save Changes extension is executed. Unless the user cancels the operation, a load file dialog is displayed and the user is allowed to choose a file to open. Once the user chooses a file, the current address book is replaced by the result of reading in the specified address book. This results in the list of names in the main window being replaced by the names in the address book that was read, the file that was opened becoming the current file, and its name being displayed as the title of the main window. (If the user cancels the file dialog, or attempting to read the file results in an error, the current address book is left unchanged. If the cancellation results from an error reading the file, a dialog box is displayed warning the user of the error.)
Save Address Book Use Case

The Save Address Book use case is initiated when the user chooses "Save" from the File menu. (The Save option is grayed out unless changes have been made to the address book since the last New, Open, Save, or Save As ... operation was done.) If there is a current file, the current address book is saved to this file. (If attempting to write the file results in an error, a dialog box is displayed warning the user of the error.) If there is no current file, the Save Address Book As .. use case is done instead. In all cases, the current address book and window list are left unchanged.
Save Address Book As ... Use Case

The Save Address Book As ... use case is initiated when the user chooses "Save As ..." from the File menu. (The Save As ... option is always available.) A save file dialog is displayed and the user is allowed to choose the name of a file in which to save the address book. (If the user cancels the file dialog, the Save As ... operation is canceled.) The current address book is saved to the specified file, and the file to which it was saved becomes the current file and its name is displayed as the title of the main window. (If attempting to write the file results in an error, a dialog box is displayed warning the user of the error, and the current file and main window title are unchanged.) In all cases, the current address book and window list are left unchanged.

Quit Program Use Case

The Quit Program use case is initiated when the user chooses "Quit" from the File menu, or clicks the close box for the main window. In either case, if the current address book contents have been changed since the last New, Open, Save, or Save As ... operation was done, the Offer to Save Changes extension is executed. Unless the user cancels the operation, the program is terminated.
Offer to Save Changes Extension

The Offer to Save Changes extension is initiated from within the Create New Address Book, Open Existing Address Book, or Quit program use cases, if the current address book has been changed since the last successful New, Open, Save, or Save As ... operation was done. A dialog box is displayed, informing the user that there are unsaved changes, and asking the user whether to save changes, not save changes, or cancel the operation. If the user chooses to save changes, the Save Address Book Use Case is executed (which may result in executing the Save Address Book As ... Use Case if there is no current file). If the user chooses not to save changes, the original operation is simply resumed. If the user chooses to cancel (or cancels the save file dialog if one is needed), the original operation is canceled.

CRC Cards for the Address Book Example

A Class Responsibility Collaborator (CRC) model (Beck & Cunningham 1989; Wilkinson 1995; Ambler 1995) is a collection of standard index cards that have been divided into three sections. A class represents a collection of similar objects, a responsibility is something that a class knows or does, and a collaborator is another class that a class interacts with to fulfill its responsibilities. Responsibilities are assigned to the various classes based on the use of the model-view-controller design pattern. The two entity classes (AddressBook and Person) serve as the model. The GUI class (AddressBookGUI) serves as the view. The controller class (AddressBookController) serves, of course, as the controller. The view (AddressBookGUI) needs to be made an observer of the model (specifically, AddressBook) so that it always reflects the current state of the model - specifically, the list of names, the title, and its saved/needs to be saved status. Using CRC cards to assign responsibilities to various classes for the tasks required by the various use cases leads to the creation of the following cards.
Class AddressBook Class AddressBookController Class AddressBookGUI Class FileSystem Class Person

Class AddressBook Class AddressBookController

The basic responsibility of an AddressBookController object is to carry out the various use cases.
Responsibilities Allow the user to perform the Add a Person Use Case Allow the user to perform the Edit a Person Use Case Allow the user to perform the Delete a Person Use Case Allow the user to perform the Sort Entries by Name Use Case Collaborators AddressBook AddressBook AddressBook AddressBook

Allow the user to perform the Sort Entries by ZIP Use Case AddressBook Allow the user to perform the Create New Address Book Use Case AddressBook

Allow the user to perform the Open Existing Address Book FileSystem Use Case Allow the user to perform the Save Address Book Use Case Allow the user to perform the Save Address Book As ... Use Case Allow the user to perform the Print Entries Use Case Perform the Offer to Save Changes Extension when needed by another Use Case AddressBook FileSystem FileSystem AddressBook AddressBook

Class AddressBookGUI
The basic responsibility of a GUI object is to allow interaction between the program and the human user.
Responsibilities Keep track of the address book object it is displaying Display a list of the names of persons in the current address book Display the title of the current address book - if any AddressBook AddressBook Collaborators

Maintain the state of the "Save" menu option - usable only when the address book has been changed since the last AddressBook time it was opened / saved.

Allow the user to request the performance of a use case

AddressBookController

Class FileSystem
The basic responsibility of a FileSystem object is to manage interaction between the program and the file system of the computer it is running on.
Responsibilities Collaborators

Read a stored address book from a file, given its file name AddressBook Save an address book to a file, given its file name AddressBook

Class Person
The basic responsibility of a Person object is to maintain information about a single individual.
Responsibilities Create a new object, given an individual's name, address, city, state, ZIP, and phone Furnish the individual's first name Furnish the individual's last name Furnish the individual's address Furnish the individual's city Furnish the individual's state Furnish the individual's ZIP Furnish the individual's phone number Update the stored information (except the name) about an individual Collaborators

Sequence Diagrams for the Address Book Example

Each of the use cases discovered in the analysis of the system will be realized by a sequence of operations involving the various objects comprising the system.

Sequence Diagram Realizing the Add a Person Use Case Sequence Diagram Realizing the Edit a Person Use Case Sequence Diagram Realizing the Delete a Person Use Case Sequence Diagram Realizing the Sort Entries by Name Use Case Sequence Diagram Realizing the Sort Entries by ZIP Use Case Sequence Diagram Realizing the Print Entries Use Case Sequence Diagram Realizing the Create New Address Book Use Case Sequence Diagram Realizing the Open Existing Address Book Use Case Sequence Diagram Realizing the Save Address Book Use Case Sequence Diagram Realizing the Save Address Book As ... Use Case Sequence Diagram Realizing the Offer to Save Changes Extension

Add a Person Use Case Sequence Diagram

Edit a Person Use Case Sequence Diagram

Delete a Person Use Case Sequence Diagram

Sort Entries By Name Use Case Sequence Diagram

Sort Entries By Zip Use Case Sequence Diagram

Print Entries Use Case Sequence Diagram

Create New Address Book Use Case Sequence Diagram

Open Existing Address Book Use Case Sequence Diagram

Save Address Book Use Case Sequence Diagram

Offer To Save Changes Extension Use Case

Class Diagram for the Address Book Example

Shown below is the class diagram for the Address Book Example. To prevent the diagram from becoming overly large, only the name of each class is shown - the attribute and behavior "compartments" are shown in the detailed design, but are omitted here. The diagram includes the classes discovered during analysis, plus some additional classes discovered during design. (In a more significant system, the total number of classes may be about five times as great as the number of classes uncovered during analysis.)
AddressBookApplication - main class for the application; responsible for creating the FileSystem and GUI objects and starting up the application. MultiInputPane - a utility class for reading multiple values at a single time. (Design not further documented, but javadoc is included.) Person.CompareByName - Comparator for comparing two Person objects by name (used for sorting by name). Person.CompareByZip - Comparator for comparing two Person objects by zip (used for sorting by name). The main application object is responsible for creating a single file system object and a single controller object. The file system object is responsible for saving and re-loading address books The controller object is responsible for creating a single GUI object. The controller object is responsible for initially creating an address book object, but the GUI is henceforth responsible for keeping track of its current address book - of which it only has one at any time. The GUI object and the address object are related by an observer-observable relationship, so that changes to the address book content lead to corresponding changes in the display The address book object is responsible for creating and keeping track of person objects, of which there can be many in any given address book. A MultiInputPane object is used by the controller to allow the user to enter multiple items of data about a person. A comparator object of the appropriate kind is used by the address book object when sorting itself.

The following relationships hold between the objects:

Detailed Class Design for the Address Book Example

Given below is a "three compartment" design for the classes appearing in the class diagram. This information was not included in that diagram due to size considerations; however, it could have been - in which case this document would have been unnecessary.

Class AddressBook Class AddressBookApplication Class AddressBookController Class AddressBookGUI Class FileSystem Class Person (No detailed design is given for Comparator class Person.CompareByName) (No detailed design is given for Comparator class Person.CompareByZip) (No detailed design is given for utility class MultiInputPane)