API Design: The Object

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

Part 18 of 21

Exceptions

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 5-1 shows an example of an exception class.

Diagram 5-1. The InsufficientFundsException is a messenger

com.artima.examples.account.ex3
InsufficientFundsException

public class InsufficientFundsException extends Exception
Exception thrown by Accounts to indicate that a requested withdrawal has failed because of insufficient funds.

Constructors

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.

Methods

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 5-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 5-2. The OverdraftAccount class

com.artima.examples.account.ex3
OverdraftAccount

public class OverdraftAccount
Represents a bank account with overdraft protection.

Constructors

public OverdraftAccount(long overdraftMax)
Constructs a new OverdraftAccount with the passed overdraft maximum.

Methods

public void addOverdraftListener(OverdraftListener l)
Adds the specified overdraft listener to receive overdraft events from this OverdraftAccount.

public void deposit(long amount)
Deposits the passed amount into the OverdraftAccount.

public long getBalance()
Gets the current balance of this OverdraftAccount.

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 OverdraftAccount.

public long withdraw(long amount) throws InsufficientFundsException
Withdraws the passed amount from this OverdraftAccount.

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.