artima.com

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.

Part 19 of 21

API Design | Contents | Book List | Printer Friendly Version | Previous | Next

Last Updated: Friday, April 26, 2002
Copyright © 1996-2002 Artima Software, Inc. All Rights Reserved.
URL: http://www.artima.com/apidesign/object19.html
Artima.com is created by Bill Venners