20.22 Classes for Exceptions and Errors

The throw statement (§14.16) is permitted to throw only instances of the class Throwable and its subclasses. Instances of two subclasses, Error and Exception, are conventionally used to indicate that exceptional situations have occurred. Typically, these instances are freshly created in the context of the exceptional situation so as to include relevant information (such as stack trace data).

The following list shows the hierarchical relationships of all the exception classes predefined in package java.lang by the Java language:

Throwable
    Error
        LinkageError
            ClassCircularityError
            ClassFormatError
            ExceptionInInitializerError

            IncompatibleClassChangeError
                AbstractMethodError
                IllegalAccessError
                InstantiationError
                NoSuchFieldError
                NoSuchMethodError
            NoClassDefFoundError
            UnsatisfiedLinkError
            VerifyError
        VirtualMachineError
            InternalError
            OutOfMemoryError
            StackOverflowError
            UnknownError
     ThreadDeath
    Exception
        ClassNotFoundException
        CloneNotSupportedException
        IllegalAccessException
        InstantiationException
        InterruptedException
        RuntimeException
            ArithmeticException
            ArrayStoreException
            ClassCastException
            IllegalArgumentException
                IllegalThreadStateException
                NumberFormatException
            IllegalMonitorStateException
            IndexOutOfBoundsException
            NegativeArraySizeException
            NullPointerException
            SecurityException

By convention, class Throwable and all its subclasses have two constructors, one that takes no arguments and one that takes a String argument that can be used to produce an error message. This is true of all the classes shown above, with one exception: ExceptionInInitializerError. These predefined classes otherwise have no new content; they merely inherit methods from class Throwable.

public class Throwable {
 public Throwable();
 public Throwable(String message);
 public String toString();
 public String getMessage();
 public Throwable fillInStackTrace();
    public void printStackTrace();
    public void printStackTrace(java.io.PrintStream s);
}

20.22.1 public Throwable()

This constructor initializes a newly created Throwable object with null as its error message string. Also, the method fillInStackTrace(§20.22.5) is called for this object.

20.22.2 public Throwable(String message)

This constructor initializes a newly created Throwable object by saving a reference to the error message string s for later retrieval by the getMessage method (§20.22.3). Also, the method fillInStackTrace(§20.22.5) is called for this object.

20.22.3 public String getMessage()

If this Throwable object was created with an error message string (§20.22.2), then a reference to that string is returned.

If this Throwable object was created with no error message string (§20.22.1), then null is returned.

20.22.4 public String toString()

If this Throwable object was created with an error message string (§20.22.2), then the result is the concatenation of three strings:

• The name of the actual class of this object
• ": " (a colon and a space)
• The result of the getMessage method (§20.22.3) for this object

If this Throwable object was created with no error message string (§20.22.1), then the name of the actual class of this object is returned.

20.22.5 public Throwable fillInStackTrace()

This method records within this Throwable object information about the current state of the stack frames for the current thread.

20.22.6 public void printStackTrace()

This method prints a stack trace for this Throwable object on the error output stream that is the value of the field System.err(§20.18.3). The first line of output contains the result of the toString method (§20.22.4) for this object. Remaining lines represent data previously recorded by the method fillInStackTrace(§20.22.5). The format of this information depends on the implementation, but the following example may be regarded as typical:

java.lang.NullPointerException
    at MyClass.mash(MyClass.java:9)
    at MyClass.crunch(MyClass.java:6)
    at MyClass.main(MyClass.java:3)

This example was produced by running the program:

class MyClass {

    public static void main(String[] argv) {
        crunch(null);
    }

  static void crunch(int[] a) {
        mash(a);
    }


    static void mash(int[] b) {
        System.out.println(b[0]);
    }

}