Part I. Objects
People-Oriented API Design
Guideline 6. Design primarily Services that use their state to decide how to behave
by Bill Venners

<<  Page 14 of 20  >>

A Stamp Dispenser Example

For an example of a mutable expert, imagine an object that models the behavior of an extremely simple stamp machine described by these requirements:

Write control software for an automated stamp dispenser. The stamp dispenser accepts only nickels (5 cents) and dimes (10 cents) and dispenses only 20-cent stamps. The stamp dispenser's LED display indicates to the user the total amount of money inserted so far. As soon as 20 or more cents is inserted, a 20-cent stamp automatically dispenses along with any change. The only amounts the display shows, therefore, are 0, 5, 10, and 15 cents. If a dime and a nickel have been inserted, the display indicates 15 cents. If the user then inserts another dime, the stamp dispenser dispenses a 20-cent stamp, returns a nickel, and changes the display to show 0 cents. In addition to a coin slot, an opening for dispensing stamps and change, and an LED display, the stamp dispenser also has a coin return lever. When the user presses coin return, the stamp dispenser returns the amount of money indicated on the display, and changes the display to show 0 cents.

An object-oriented solution to these requirements could include a class StampDispenser, shown in Diagram 6-1, which models the functionality of the real-world stamp dispenser. The StampDispenser offers its primary services to clients via two public methods: add and returnCoins.

Diagram 6-1. A simple stamp dispenser

public class StampDispenser
    A stamp dispenser that accepts nickels and dimes and dispenses twenty cent stamps.
public StampDispenser()
    Constructs a new stamp dispenser with a starting balance of zero.
public synchronized void add(int amount)
    Add either 5 or 10 cents to the stamp dispenser.
public synchronized void addStampDispenserListener(StampDispenserListener l)
    Adds the specified stamp dispenser listener to receive stamp dispenser events from this stamp dispenser.
public synchronized void removeStampDispenserListener(StampDispenserListener l)
    Removes the specified stamp dispenser listener so that it no longer receives stamp dispenser events from this stamp dispenser.
public synchronized void returnCoins()
    Returns coins.

The StampDispenser also enables clients to be notified of events by registering themselves via the addStampDispenserListener method. Clients can change their minds via the removeStampDispenserListener method. Both of these methods take a StampDispenserListener parameter, an interface shown in Diagram 6-2.

Diagram 6-2. The StampDispenserListener interface

public interface StampDispenserListener
    Listener interface for receiving stamp dispenser events.
public void coinAccepted(StampDispenserEvent e)
    Invoked when coins have been accepted but no stamp has been dispensed.
public void coinsReturned(StampDispenserEvent e)
    Invoked when coins have been returned as the result of the returnCoins method being invoked on a StampDispenser.
public void stampDispensed(StampDispenserEvent e)
    Invoked when a stamp has been dispensed.

Were you to use a StampDispenser instance to control an actual stamp dispenser, the listeners would be responsible for actually returning coins, dispensing stamps, and changing the display. The client that invokes the add method would be code that knows money was inserted. The client that invokes the returnCoins method would be code that knows the return coins lever was pressed.

The StampDispenserListener methods indicate the stamp dispenser has accepted a coin, returned a coin, or dispensed a stamp. Each of these methods takes a StampDispenserEvent, shown in Diagram 6-3, which lets the listener determine the amount of money that should be returned, if any, and the current balance the display should show.

Diagram 6-3. The StampDispenserEvent class

public class StampDispenserEvent extends java.util.EventObject
    Event that indicates a stamp dispenser has performed an action.
public StampDispenserEvent(StampDispenser source, int amountReturned, int balance)
    Constructs a StampDispenserEvent with amountReturned, and balance.
public int getAmountReturned()
    Returns the amount of money returned to the client, expressed in units of American pennies.
public int getBalance()
    Returns the current balance: the amount of money that has been inserted into the stamp dispenser, but not returned via a coin return or consumed in exchange for a dispensed stamp.

<<  Page 14 of 20  >>

People-Oriented API Design | Contents | Book List | Print | Email | First Page | Previous | Next

Sponsored Links
Download Artima SuiteRunner Now - It's FREE!

Last Updated: Sunday, May 11, 2003
Copyright © 1996-2003 Artima Software, Inc. All Rights Reserved.
URL: is created by Bill Venners