Module java.base
Package java.lang

Class Throwable

java.lang.Object
java.lang.Throwable
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
Error, Exception

public class Throwable extends Object implements Serializable
This class is the superclass of all classes which can be thrown by the virtual machine. The two direct subclasses represent recoverable exceptions (Exception) and unrecoverable errors (Error). This class provides common methods for accessing a string message which provides extra information about the circumstances in which the throwable was created, and for filling in a walkback (i.e. a record of the call stack at a particular point in time) which can be printed later.
See Also:
  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
     
    Constructs a new instance of this class with its walkback filled in.
     
    Throwable(String detailMessage)
    Constructs a new instance of this class with its walkback and message filled in.
     
    Throwable(String detailMessage, Throwable throwable)
    Constructs a new instance of this class with its walkback, message and cause filled in.
    protected
    Throwable(String detailMessage, Throwable throwable, boolean enableSuppression, boolean enableWritableStackTrace)
    Constructs a new instance of this class with its walkback, message and cause filled in.
     
    Throwable(Throwable throwable)
    Constructs a new instance of this class with its walkback and cause filled in.
  • Method Summary

    Modifier and Type
    Method
    Description
    final void
    The specified exception is going to be suppressed in order to give priority to this exception (primary exception) and to be appended to the list of suppressed exceptions.
    Record in the receiver a walkback from the point where this message was sent.
    Answers the cause of this Throwable, or null if there is no cause.
    Answers the extra information message which was provided when the throwable was created.
    Answers the extra information message which was provided when the throwable was created.
    Answers an array of StackTraceElement.
    final Throwable[]
    Returns an array of exceptions suppressed, typically by the automatically generated code from the try-with-resources statement, in order to give priority to this exception (primary exception).
    initCause(Throwable throwable)
    Initialize the cause of the receiver.
    void
    Outputs a printable representation of the receiver's walkback on the System.err stream.
    void
    Outputs a printable representation of the receiver's walkback on the stream specified by the argument.
    void
    Outputs a printable representation of the receiver's walkback on the writer specified by the argument.
    void
    Sets the array of StackTraceElements.
    Answers a string containing a concise, human-readable description of the receiver.

    Methods declared in class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
  • Constructor Details

    • Throwable

      public Throwable()
      Constructs a new instance of this class with its walkback filled in.
    • Throwable

      public Throwable(String detailMessage)
      Constructs a new instance of this class with its walkback and message filled in.
      Parameters:
      detailMessage - String The detail message for the exception.
    • Throwable

      public Throwable(String detailMessage, Throwable throwable)
      Constructs a new instance of this class with its walkback, message and cause filled in.
      Parameters:
      detailMessage - String The detail message for the exception.
      throwable - The cause of this Throwable
    • Throwable

      public Throwable(Throwable throwable)
      Constructs a new instance of this class with its walkback and cause filled in.
      Parameters:
      throwable - The cause of this Throwable
    • Throwable

      protected Throwable(String detailMessage, Throwable throwable, boolean enableSuppression, boolean enableWritableStackTrace)
      Constructs a new instance of this class with its walkback, message and cause filled in. enableSuppression and enableWritableStackTrace are true by default in other constructors If enableSuppression is false, suppression is disabled, getSuppressed() returns a zero-length array and calls to addSuppressed(Throwable) have no effect. If enableWritableStackTrace is false, fillInStackTrace() will not be called within this constructor, stackTrace field will be set to null, subsequent calls to fillInStackTrace() and setStackTrace(StackTraceElement[]) will not set the stack trace, and getStackTrace() will return a zero length array.
      Parameters:
      detailMessage - String The detail message for the exception.
      throwable - The cause of this Throwable
      enableSuppression - boolean enable or disable suppression
      enableWritableStackTrace - boolean whether the stack trace is writable
      Since:
      1.7
  • Method Details

    • fillInStackTrace

      public Throwable fillInStackTrace()
      Record in the receiver a walkback from the point where this message was sent. The message is public so that code which catches a throwable and then re-throws it can adjust the walkback to represent the location where the exception was re-thrown.
      Returns:
      the receiver
    • getMessage

      public String getMessage()
      Answers the extra information message which was provided when the throwable was created. If no message was provided at creation time, then answer null.
      Returns:
      String The receiver's message.
    • getLocalizedMessage

      public String getLocalizedMessage()
      Answers the extra information message which was provided when the throwable was created. If no message was provided at creation time, then answer null. Subclasses may override this method to answer localized text for the message.
      Returns:
      String The receiver's message.
    • getStackTrace

      public StackTraceElement[] getStackTrace()
      Answers an array of StackTraceElement. Each StackTraceElement represents a entry on the stack.
      Returns:
      an array of StackTraceElement representing the stack
    • setStackTrace

      public void setStackTrace(StackTraceElement[] trace)
      Sets the array of StackTraceElements. Each StackTraceElement represents a entry on the stack. A copy of this array will be returned by getStackTrace() and printed by printStackTrace().
      Parameters:
      trace - The array of StackTraceElement
    • printStackTrace

      public void printStackTrace()
      Outputs a printable representation of the receiver's walkback on the System.err stream.
    • printStackTrace

      public void printStackTrace(PrintStream err)
      Outputs a printable representation of the receiver's walkback on the stream specified by the argument.
      Parameters:
      err - PrintStream The stream to write the walkback on.
    • printStackTrace

      public void printStackTrace(PrintWriter err)
      Outputs a printable representation of the receiver's walkback on the writer specified by the argument.
      Parameters:
      err - PrintWriter The writer to write the walkback on.
    • toString

      public String toString()
      Answers a string containing a concise, human-readable description of the receiver.
      Overrides:
      toString in class Object
      Returns:
      String a printable representation for the receiver.
    • initCause

      public Throwable initCause(Throwable throwable)
      Initialize the cause of the receiver. The cause cannot be reassigned.
      Parameters:
      throwable - The cause of this Throwable
      Returns:
      the receiver.
      Throws:
      IllegalArgumentException - when the cause is the receiver
      IllegalStateException - when the cause has already been initialized
    • getCause

      public Throwable getCause()
      Answers the cause of this Throwable, or null if there is no cause.
      Returns:
      Throwable The receiver's cause.
    • addSuppressed

      public final void addSuppressed(Throwable exception)
      The specified exception is going to be suppressed in order to give priority to this exception (primary exception) and to be appended to the list of suppressed exceptions. This method is typically called by the automatically generated code from the try-with-resources statement.
      Parameters:
      exception - Throwable an exception to be suppressed and added to the list of suppressed exceptions
      Throws:
      IllegalArgumentException - if exception is this throwable, can't suppress itself
      NullPointerException - if exception is null and there is an exception suppressed before
      Since:
      1.7
    • getSuppressed

      public final Throwable[] getSuppressed()
      Returns an array of exceptions suppressed, typically by the automatically generated code from the try-with-resources statement, in order to give priority to this exception (primary exception).
      Returns:
      an array of exceptions representing all exceptions suppressed to give priority to this exception (primary exception)
      Since:
      1.7