Copyright © 2004 O'Reilly Media, Inc. All Rights Reserved.
Essential ActionScript 2.0
By Colin Moock
June 2004
ISBN: 0-596-00652-7
More info... .
Available from booksellers or direct from O'Reilly Media, www.oreilly.com.

Cover image
This content is excerpted from the above-named O'Reilly publication, with permission, by agreement with ActionScript.org.

Our first option is to accept the preceding setWidth( ) definition, which throws the same error type (BoxDimensionException) for all three Box-related error conditions. Because the method uses BoxDimensionException and not Error to throw exceptions, Box exceptions are already distinguishable from other generic exceptions. Users of the setWidth( ) method can use code such as the following to discriminate between Box-related errors and other generic errors:

var b:Box = new Box( );
var someWidth:Number = -10;

try {
// This call to setWidth( ) will generate a BoxDimensionException.
b.setWidth(someWidth);
// Other statements in this try block might generate other generic errors.
// For demonstration purposes, we'll throw a generic error directly.
throw new Error("A generic error.");
} catch (e:BoxDimensionException) {
// Handle Box dimension errors here.
trace("An error occurred: " + e.message);
trace("Please specify a valid dimension.");
} catch (e:Error) {
// Handle all other errors here.
trace("An error occurred: " + e.message);
}

For many applications, the level of error granularity provided by BoxDimensionException is enough. In such a case, we should at least refactor the setWidth( ) method so that it doesn't contain redundant code (throwing the BoxDimensionException three times). Here's the refactored code (which was option 2 in our earlier list):

public function setWidth (w:Number):Void {
if ((isNaN(w) || w == null) || (w <= 0) || (w > Number.MAX_VALUE)) {
throw new BoxDimensionException( );
}
width = w;
}

Using configurable debugging messages

Now let's turn to option 3 (adding configurable debugging messages to the BoxDimensionException class). Options 1 and 2 let us distinguish a Box exception from other exceptions in the application but didn't help us distinguish, say, an overflow exception from a less-than-zero exception. If we feel that it's difficult to debug a Box dimension problem without knowing whether a box is too big or too small, we can adjust the BoxDimensionException class so that it accepts an optional description (the equivalent of a proverbial "note to self"). Here's the adjusted BoxDimensionException class:

class BoxDimensionException extends Error {
// The default error message still stands.
public var message:String = "Illegal Box dimension specified.";

// Provide a constructor that allows a custom message to be supplied.
public function BoxDimensionException (boxErrMsg:String) {
super(boxErrMsg);
}
}

To make use of our adjusted BoxDimensionException class in setWidth( ), we revert to our setWidth( ) code used in option 1 and add debugging error messages, as follows:

public function setWidth (w:Number):Void {
if (isNaN(w) || w == null) {
// The default error message is fine in this case, 
// so don't bother specifying a custom error message.
throw new BoxDimensionException( );
} else if (w <= 0) {
// Here's the custom "too small" error message.
throw new BoxDimensionException("Box dimensions must " 
+ "be greater than 0.");
} else if (w > Number.MAX_VALUE) {
// Here's the custom "too big" error message.
throw new BoxDimensionException("Box dimensions must be less "
+ "than Number.MAX_VALUE.");
}
width = w;
}

Now that setWidth( ) supplies custom error messages, we'll have an easier time debugging a Box problem because we'll know more information when the error occurs. Our use of the setWidth( ) method has not changed, but we're better informed when something goes wrong, as shown next:

var b:Box = new Box( );
var someWidth:Number = -10;

try {
b.setWidth(someWidth);
} catch (e:BoxDimensionException) {
// Handle Box dimension errors here.
// In this case, the helpful debugging output is:
// An error occurred: Box dimensions must be greater than 0.
trace("An error occurred: " + e.message);
} catch (e:Error) {
// Handle all other errors here.
trace("An error occurred: " + e.message);
}