Part I. Objects
People-Oriented API Design
Guideline 7. Design Messengers when you don't know the behavior
by Bill Venners

<<  Page 17 of 20  >>



One common example of messengers is exceptions. Exception objects are generally composed of a small amount of data, which is passed to the constructor, and some accessor methods that let catch clauses access the data. Like most messengers, exceptions usually have short lives. They are created when an abnormal condition is encountered, thrown up the call stack, caught by an application or default catch clause, handled, and discarded. Diagram 7-1 shows an example of an exception class.

Diagram 7-1. The InsufficientFundsException is a messenger

public class InsufficientFundsException extends Exception
    Exception thrown by Accounts to indicate that a requested withdrawal has failed because of insufficient funds.
public InsufficientFundsException(long shortfall)
    Constructs an InsufficientFundsException with the passed shortfall and no specified detail message.
public InsufficientFundsException(String message, long shortfall)
    Constructs an InsufficientFundsException with the passed detail message and shortfall.
public long getShortfall()
    Returns the shortfall that caused a withrawal request to fail.

An InsufficientFundsException contains an optional message and a required shortfall. The exception sender passes this data to a constructor. The exception recipient (a catch clause) can retrieve the data via accessor methods. Often, the most important piece of information carried in an exception is embodied in the name of the exception class. Exception class names usually indicate the kind of abnormal condition encountered. In this case, the name InsufficientFundsException indicates that someone attempted to withdraw more money than was available in their account. Any data stored in the exception object generally adds more detailed information about the abnormal condition described by the exception class name.

InsufficientFundsException may be thrown by the withdraw method of class OverdraftAccount, shown in Diagram 7-2. The reason a bundle of data makes sense in the InsufficientFundsException case is that the designer of the withdraw method doesn't know how to deal with the situation that triggers the exception. The designer knows someone has attempted to withdraw more money than is available in their account, but doesn't know what behavior is appropriate.

Diagram 7-2. The OverdraftAccount class

public class OverdraftAccount
    Represents a bank account with overdraft protection.
public OverdraftAccount(long overdraftMax)
    Constructs a new Account with the passed overdraft maximum.
public void addOverdraftListener(OverdraftListener l)
    Adds the specified overdraft listener to receive overdraft events from this Account.
public void deposit(long amount)
    Deposits the passed amount into the Account.
public long getBalance()
    Gets the current balance of this Account.
public long getOverdraft()
    Returns the current overdraft, the amount the bank has loaned to the client that has not yet been repaid.
public long getOverdraftMax()
    Returns the overdraft maximum, the maximum amount the bank will allow the client to owe it.
public void removeOverdraftListener(OverdraftListener l)
    Removes the specified overdraft listener so that it no longer receives overdraft events from this Account.
public long withdraw(long amount) throws InsufficientFundsException
    Withdraws the passed amount from this Account.

The appropriate behavior to take when insufficient funds exist to make a withdrawal depends on the context in which the withdraw method is invoked. Some clients may wish to abort the withdrawal. Some clients may wish to abort the withdrawal and charge a fee. Some clients may wish to abort the withdrawal, charge a fee, and freeze the account. Because the designer of the withdraw method does not know the appropriate behavior, it makes sense to create a messenger and send it to code that does know. The withdraw method creates an InsufficientFundsException and throws the information up the call stack to code written by a programmer with sufficient knowledge of the context to know the appropriate action to take.

<<  Page 17 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