There are two special cases: Error and RuntimeException:
* these two classes (and their subclasses) are considered unchecked
* exceptions, and are either frequent enough or catastrophic enough that you
* do not need to declare them in throws clauses. Everything
* else is a checked exception, and is ususally a subclass of
* Exception; these exceptions have to be handled or declared.
*
*
Instances of this class are usually created with knowledge of the * execution context, so that you can get a stack trace of the problem spot * in the code. Also, since JDK 1.4, Throwables participate in "exception * chaining." This means that one exception can be caused by another, and * preserve the information of the original. * *
One reason this is useful is to wrap exceptions to conform to an * interface. For example, it would be bad design to require all levels * of a program interface to be aware of the low-level exceptions thrown * at one level of abstraction. Another example is wrapping a checked * exception in an unchecked one, to communicate that failure occured * while still obeying the method throws clause of a superclass. * *
A cause is assigned in one of two ways; but can only be assigned once
* in the lifetime of the Throwable. There are new constructors added to
* several classes in the exception hierarchy that directly initialize the
* cause, or you can use the initCause method. This second
* method is especially useful if the superclass has not been retrofitted
* with new constructors:
*
* try
* {
* lowLevelOp();
* }
* catch (LowLevelException lle)
* {
* throw (HighLevelException) new HighLevelException().initCause(lle);
* }
*
* Notice the cast in the above example; without it, your method would need
* a throws clase that declared Throwable, defeating the purpose of chainig
* your exceptions.
*
* By convention, exception classes have two constructors: one with no * arguments, and one that takes a String for a detail message. Further, * classes which are likely to be used in an exception chain also provide * a constructor that takes a Throwable, with or without a detail message * string. * *
Another 1.4 feature is the StackTrace, a means of reflection that
* allows the program to inspect the context of the exception, and which is
* serialized, so that remote procedure calls can correctly pass exceptions.
*
* @author Brian Jones
* @author John Keiser
* @author Mark Wielaard
* @author Tom Tromey
* @author Eric Blake (ebb9@email.byu.edu)
*/
public class Throwable
{
/**
* The detail message.
*/
private final String detailMessage;
/**
* Instantiate this Throwable with an empty message. The cause remains
* uninitialized. fillInStackTrace() will be called to set
* up the stack trace.
*/
public Throwable()
{
this((String) null);
}
/**
* Instantiate this Throwable with the given message. The cause remains
* uninitialized. fillInStackTrace() will be called to set
* up the stack trace.
*
* @param message the message to associate with the Throwable
*/
public Throwable(String message)
{
detailMessage = message;
}
/**
* Get the message associated with this Throwable.
*
* @return the error message associated with this Throwable, may be null
*/
public String getMessage()
{
return detailMessage;
}
/**
* Get a human-readable representation of this Throwable. The detail message
* is retrieved by getLocalizedMessage(). Then, with a null detail
* message, this string is simply the object's class name; otherwise
* the string is getClass().getName() + ": " + message.
*
* @return a human-readable String represting this Throwable
*/
public String toString()
{
String msg = getMessage();
return getClass().getName() + (msg == null ? "" : ": " + msg);
}
/**
* Print a stack trace to the standard error stream. This stream is the
* current contents of System.err. The first line of output
* is the result of toString(), and the remaining lines represent
* the data created by fillInStackTrace(). While the format is
* unspecified, this implementation uses the suggested format, demonstrated
* by this example:
*
* public class Junk
* {
* public static void main(String args[])
* {
* try
* {
* a();
* }
* catch(HighLevelException e)
* {
* e.printStackTrace();
* }
* }
* static void a() throws HighLevelException
* {
* try
* {
* b();
* }
* catch(MidLevelException e)
* {
* throw new HighLevelException(e);
* }
* }
* static void b() throws MidLevelException
* {
* c();
* }
* static void c() throws MidLevelException
* {
* try
* {
* d();
* }
* catch(LowLevelException e)
* {
* throw new MidLevelException(e);
* }
* }
* static void d() throws LowLevelException
* {
* e();
* }
* static void e() throws LowLevelException
* {
* throw new LowLevelException();
* }
* }
* class HighLevelException extends Exception
* {
* HighLevelException(Throwable cause) { super(cause); }
* }
* class MidLevelException extends Exception
* {
* MidLevelException(Throwable cause) { super(cause); }
* }
* class LowLevelException extends Exception
* {
* }
*
* *
* HighLevelException: MidLevelException: LowLevelException
* at Junk.a(Junk.java:13)
* at Junk.main(Junk.java:4)
* Caused by: MidLevelException: LowLevelException
* at Junk.c(Junk.java:23)
* at Junk.b(Junk.java:17)
* at Junk.a(Junk.java:11)
* ... 1 more
* Caused by: LowLevelException
* at Junk.e(Junk.java:30)
* at Junk.d(Junk.java:27)
* at Junk.c(Junk.java:21)
* ... 3 more
*
*/
public native void printStackTrace();
}