API Design: The Object

Chapter 1 of API Design
The Object
Guideline 3. Design service-oriented objects that use their state to decide how to behave
by Bill Venners

Part 10 of 21

A Stamp Dispenser Example

For an example of a mutable service-oriented object, 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 3-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 3-1. A simple stamp dispenser

com.artima.examples.stampdispenser.ex1
StampDispenser

public class StampDispenser
A stamp dispenser that accepts nickels and dimes and dispenses twenty cent stamps.

Constructors

public StampDispenser()
Constructs a new stamp dispenser with a starting balance of zero.

Methods

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 3-2.

Diagram 3-2. The StampDispenserListener interface

com.artima.examples.stampdispenser.ex1
StampDispenserListener

public interface StampDispenserListener
Listener interface for receiving stamp dispenser events.

Methods

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 3-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 3-3. The StampDispenserEvent class

com.artima.examples.stampdispenser.ex1
StampDispenserEvent

public class StampDispenserEvent extends java.util.EventObject
Event that indicates a stamp dispenser has performed an action.

Constructors

public StampDispenserEvent(StampDispenser source, int amountReturned, int balance)
Constructs a StampDispenserEvent with amountReturned, and balance.

Methods

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.