Creating your own exceptions
You’re not stuck using the existing Java exceptions. The JDK exception hierarchy can’t foresee all the errors you might want to report, so you can create your own to denote a special problem that your library might encounter.
To create your own exception class, you must inherit from an existing exception class, preferably one that is close in meaning to your new exception (although this is often not possible). The most trivial way to create a new type of exception is just to let the compiler create the default constructor for you, so it requires almost no code at all:
//: c09:SimpleExceptionDemo.java
// Inheriting your own exceptions.
import com.bruceeckel.simpletest.*;
class SimpleException extends Exception {}
public class SimpleExceptionDemo {
private static Test monitor = new Test();
public void f() throws SimpleException {
System.out.println("Throw SimpleException from f()");
throw new SimpleException();
}
public static void main(String[] args) {
SimpleExceptionDemo sed = new SimpleExceptionDemo();
try {
sed.f();
} catch(SimpleException e) {
System.err.println("Caught it!");
}
monitor.expect(new String[] {
"Throw SimpleException from f()",
"Caught it!"
});
}
} ///:~
The compiler creates a default constructor, which automatically (and invisibly) calls the base-class default constructor. Of course, in this case you don’t get a SimpleException(String) constructor, but in practice that isn’t used much. As you’ll see, the most important thing about an exception is the class name, so most of the time an exception like the one shown here is satisfactory.
Here, the result is printed to the console standard error stream by writing to System.err. This is usually a better place to send error information than System.out, which may be redirected. If you send output to System.err, it will not be redirected along with System.out so the user is more likely to notice it.
You can also create an exception class that has a constructor with a String argument:
//: c09:FullConstructors.java
import com.bruceeckel.simpletest.*;
class MyException extends Exception {
public MyException() {}
public MyException(String msg) { super(msg); }
}
public class FullConstructors {
private static Test monitor = new Test();
public static void f() throws MyException {
System.out.println("Throwing MyException from f()");
throw new MyException();
}
public static void g() throws MyException {
System.out.println("Throwing MyException from g()");
throw new MyException("Originated in g()");
}
public static void main(String[] args) {
try {
f();
} catch(MyException e) {
e.printStackTrace();
}
try {
g();
} catch(MyException e) {
e.printStackTrace();
}
monitor.expect(new String[] {
"Throwing MyException from f()",
"MyException",
"%% \tat FullConstructors.f\\(.*\\)",
"%% \tat FullConstructors.main\\(.*\\)",
"Throwing MyException from g()",
"MyException: Originated in g()",
"%% \tat FullConstructors.g\\(.*\\)",
"%% \tat FullConstructors.main\\(.*\\)"
});
}
} ///:~
The added code is small: two constructors that define the way MyException is created. In the second constructor, the base-class constructor with a String argument is explicitly invoked by using the super keyword.
In the handlers, one of the Throwable (from which Exception is inherited) methods is called: printStackTrace( ). This produces information about the sequence of methods that were called to get to the point where the exception happened. By default, the information goes to the standard error stream, but overloaded versions allow you to send the results to any other stream as well.
The process of creating your own exceptions can be taken further. You can add extra constructors and members:
//: c09:ExtraFeatures.java
// Further embellishment of exception classes.
import com.bruceeckel.simpletest.*;
class MyException2 extends Exception {
private int x;
public MyException2() {}
public MyException2(String msg) { super(msg); }
public MyException2(String msg, int x) {
super(msg);
this.x = x;
}
public int val() { return x; }
public String getMessage() {
return "Detail Message: "+ x + " "+ super.getMessage();
}
}
public class ExtraFeatures {
private static Test monitor = new Test();
public static void f() throws MyException2 {
System.out.println("Throwing MyException2 from f()");
throw new MyException2();
}
public static void g() throws MyException2 {
System.out.println("Throwing MyException2 from g()");
throw new MyException2("Originated in g()");
}
public static void h() throws MyException2 {
System.out.println("Throwing MyException2 from h()");
throw new MyException2("Originated in h()", 47);
}
public static void main(String[] args) {
try {
f();
} catch(MyException2 e) {
e.printStackTrace();
}
try {
g();
} catch(MyException2 e) {
e.printStackTrace();
}
try {
h();
} catch(MyException2 e) {
e.printStackTrace();
System.err.println("e.val() = " + e.val());
}
monitor.expect(new String[] {
"Throwing MyException2 from f()",
"MyException2: Detail Message: 0 null",
"%% \tat ExtraFeatures.f\\(.*\\)",
"%% \tat ExtraFeatures.main\\(.*\\)",
"Throwing MyException2 from g()",
"MyException2: Detail Message: 0 Originated in g()",
"%% \tat ExtraFeatures.g\\(.*\\)",
"%% \tat ExtraFeatures.main\\(.*\\)",
"Throwing MyException2 from h()",
"MyException2: Detail Message: 47 Originated in h()",
"%% \tat ExtraFeatures.h\\(.*\\)",
"%% \tat ExtraFeatures.main\\(.*\\)",
"e.val() = 47"
});
}
} ///:~
A field i has been added, along with a method that reads that value and an additional constructor that sets it. In addition, Throwable.getMessage( ) has been overridden to produce a more interesting detail message. getMessage( ) is something like toString( ) for exception classes.
Since an exception is just another kind of object, you can continue this process of embellishing the power of your exception classes. Keep in mind, however, that all this dressing-up might be lost on the client programmers using your packages, since they might simply look for the exception to be thrown and nothing more. (That’s the way most of the Java library exceptions are used.)
