API Design: The Object

Chapter 1 of API Design
The Object
Guideline 5. Use messengers to transmit information
by Bill Venners

Part 19 of 21

Events

Another example of messengers is events. Like exceptions, event objects usually contain a small amount of data, which is passed to the constructor, and some accesor methods by which recipients access the data. Also like exceptions, events usually have short lives. When an event occurs, an event object is instantiated and filled with data that describes the event. The event object is then passed to all listeners that have registered interest in the event. Each listener handles the event in its own way, and the event object is discarded. Diagram 5-3 shows an example of an event class.

Diagram 5-3. The OverdraftEvent class

com.artima.examples.account.ex3
OverdraftEvent

public class OverdraftEvent extends java.util.EventObject
Event that indicates an overdraft has either been loaned to a client or repaid by a client during a withdrawal or deposit transaction on an Account.

Constructors

public OverdraftEvent(OverdraftAccount source, long overdraft, long amount)
Constructs an OverdraftEvent with the passed source, and overdraft.

Methods

public long getAmount()
Returns the amount of money either loaned to the client or repaid to the bank during the transaction that caused this event to be propagated.

public long getOverdraft()
Returns the current overdraft, the amount of of overdraft after the transaction that caused this event to be propagated.

OverdraftEvents are fired by OverdraftAccounts, shown in Diagram 5-2. An OverdraftAccount represents a bank account with overdraft protection. If a customer attempts to withdraw from his OverdraftAccount more the current balance (an overdraft), the bank will loan the customer enough money to cover the overdraft up to a certain maximum. When a customer with a current overdraft deposits money back into the account, that money will first be used to pay back the bank for its overdraft loan. Any remainder will be deposited into the customer's account. An OverdraftAccount fires an OverdraftEvent if an overdraft occurs on that account, or if an existing overdraft is partially or fully repaid.

OverdraftAccount has an addOverdraftListener method, which accepts an OverdraftListener, shown in Diagram 5-4. OverdraftListeners passed to the addOverdraftListener method receive any OverdraftEvents fired by the OverdraftAccount, until unregistered via the removeOverdraftListener method.

Diagram 5-4. The OverdraftListener interface

com.artima.examples.account.ex3
OverdraftListener

public interface OverdraftListener
Listener interface for receiving overdraft events.

Methods

public void overdraftOccurred(OverdraftEvent e)
Invoked when an overdraft has occurred.

public void overdraftRepaid(OverdraftEvent e)
Invoked when some or all of the outstanding overdraft that a bank has loaned to a client is repaid.

An OverdraftEvent is a messenger. It contains a source, a reference to the object that fired the event, the amount loaned or repaid, and the current overdraft. An OverdraftAccount passes this data to the constructor, then fires the event to the listeners. The listeners can retrieve the data from accessor methods.

The reason a bundle of data makes sense in the OverdraftEvent case is that the designer of class OverdraftAccount doesn't necessarily know everything to do when an overdraft occurs or is repaid. The OverdraftAccount object does know to update the account balance and overdraft amounts. But it is reasonable to expect that other behavior will be desired, such as adding an entry to an audit trail, calculating statistics, or charging a fee based on some complex and often-changing formula. By using an event, other kinds of behavior can be added later and dynamically changed at run time.