It's often suitable to catch a particular type of exception and rethrow a different one. This is sometimes necessary because a client might not know or care to handle the original exception. For example, say that a client invokes an action on a Struts application to upload an image file to a database. Let's further assume the Action class calls an update method whose signature looks like the following:
public void updateImageFile( String imagePath ) throws UploadException;
When the method is called with an image to upload and a problem occurs, an UploadException will be thrown. However, the underlying problem will be more specific—for example, the filesystem is full or the database already has the image, depending on the destination of the image upload. The original exception thrown may be IOException or SQLException, but the user doesn't need to know or care about this level of detail; all he needs to know is that the update function failed. Although the end user doesn't care about the specific exception thrown, the system administrator or the developers who will be assigned the task of debugging and fixing the problem do. That's why you don't want to throw away the root cause of the problem when you rethrow a different exception.
Prior to Version 1.4, Java didn't provide a built-in mechanism to wrap the original exception with a new one. Developers were left to their own devices to solve the problem. Most homegrown solutions looked something like the exception class in Example 10-1.
import java.io.PrintStream;
import java.io.PrintWriter;
/**
* This is the common superclass for all application exceptions. This
* class and its subclasses support the chained exception facility that allows
* a root cause Throwable to be wrapped by this class or one of its
* descendants.
*/
public class BaseException extends Exception {protected Throwable rootCause = null;
protected BaseException( Throwable rootCause ) {this.rootCause = rootCause;
}
public void setRootCause(Throwable anException) {rootCause = anException;
}
public Throwable getRootCause( ) {return rootCause;
}
public void printStackTrace( ) {printStackTrace(System.err);
}
public void printStackTrace(PrintStream outStream) {printStackTrace(new PrintWriter(outStream));
}
public void printStackTrace(PrintWriter writer) {super.printStackTrace(writer);
if ( getRootCause( ) != null ) {getRootCause( ).printStackTrace(writer);
}
writer.flush( );
}
}
The exception class in Example 10-1 allows you to wrap the original Throwable with an instance of this exception class or any of its descendants. The nice thing about this feature is that it allows you to abstract out the ugly details of lower-level exceptions, while at the same time keeping those details available so they can be printed out to a log and used by developers. Because these exceptions can be chained together endlessly, this concept is commonly referred to as exception chaining.
Exception chaining is an excellent way of preventing lower-layer abstractions, such as JDBC access, from propagating outward to an end user. The end user doesn't care about the lower-layer problem, and abstracting the problem to a higher-level exception will keep him from seeing many of the details.
Another benefit of using a higher-layer exception class is that the API of the upper layer is not tied nor coupled to the details of the implementation. Continuing our earlier example, suppose that a filesystem is initially used to store the images, and therefore the throws clause of the updateImageFile( ) method declares that it throws an IOException. If later the implementation changes to use JDBC instead, the throws clause and the clients invoking the method must be changed to declare or catch a SQLException. By using a higher level of abstraction, the client only needs to be concerned about the UploadException, regardless of the underlying implementation.
A slight variation on the exception chaining idea is the concept of throwing multiple exceptions from a method. For example, say a user is filling out a form that has several price fields that must fall between some minimum and maximum values. Let's further assume the price values can be validated only on the backend and not within an ActionForm.
Unless your application can throw multiple exceptions from a method, the user will see only one exception at a time. This approach will work, but will probably become very annoying for end users, who will have to fix one field and then resubmit only to receive the next error. It would be easier for users if all of the errors were displayed and could be fixed at the same time. Unfortunately, a Java method can throw only a single instance of Throwable.
One solution to dealing with multiple exceptions is to allow an exception class to have a primary exception while supporting a collection of other exceptions. Each exception can be treated the same, but the primary exception is used when only a single exception occurs, and the client can check the exception collection to see if there are more. Example 10-2 illustrates what the BaseException class from Example 10-1 would look like with this feature added to it.
package com.oreilly.struts.framework.exceptions;
import java.util.List;
import java.util.ArrayList;
import java.io.PrintStream;
import java.io.PrintWriter;
/**
* This is the common superclass for all application exceptions. This
* class and its subclasses support the chained exception facility that allows
* a root cause Throwable to be wrapped by this class or one of its
* descendants. This class also supports multiple exceptions via the
* exceptionList field.
*/
public class BaseException extends Exception{protected Throwable rootCause = null;
private List exceptions = new ArrayList( );
public BaseException( ){super( );
}
public BaseException( Throwable rootCause ) {this.rootCause = rootCause;
}
public List getExceptions( ) {return exceptions;
}
public void addException( BaseException ex ){ exceptions.add( ex ); } public void setRootCause(Throwable anException) { rootCause = anException; } public Throwable getRootCause( ) { return rootCause; } public void printStackTrace( ) { printStackTrace(System.err); } public void printStackTrace(PrintStream outStream) { printStackTrace(new PrintWriter(outStream)); } public void printStackTrace(PrintWriter writer) { super.printStackTrace(writer); if ( getRootCause( ) != null ) { getRootCause( ).printStackTrace(writer); } writer.flush( ); }}
Notice in Example 10-2 that a java.util.List has been added to the class. If more than one exception occurs during the processing of a method, the additional exceptions can be added and returned to the client. If the client wants to deal with only a single exception, it doesn't have to retrieve the additional ones.