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]);
	}

}