Principle

To capture the failure, the detail message of an exception should contain the values of all parameters and fields that "contributed to the exception.

One way to ensure that exceptions contain adequate failure-capture information in their detail messages is to require this information in their constructors instead of a string detail message.

/**

* Construct an IndexOutOfBoundsException.

*

* @param lowerBound the lowest legal index value.

* @param upperBound the highest legal index value plus one.

* @param index the actual index value.

*/

public IndexOutOfBoundsException(int lowerBound, int upperBound, int index) {

// Generate a detail message that captures the failure

super("Lower bound: " + lowerBound +

", Upper bound: " + upperBound +

", Index: " + index);

// Save failure information for programmatic access

this.lowerBound = lowerBound;

this.upperBound = upperBound;

this.index = index;

}

As suggested in Item 58, it may be appropriate for an exception to provide accessor methods for its failure-capture information (lowerBound, upperBound, and inde xin the above example). It is more important to provide such accessor methods on checked exceptions than on unchecked exceptions, because the failure-capture information could be useful in recovering from the failure. It is rare (although not inconceivable) that a programmer might want programmatic access to the details of an unchecked exception. Even for unchecked exceptions, however, it seems advisable to provide these accessors on general principle (Item 10, page 53).