src/share/classes/java/lang/Throwable.java

Print this page




 435      * } catch (LowLevelException le) {
 436      *     throw (HighLevelException)
 437      *           new HighLevelException().initCause(le); // Legacy constructor
 438      * }
 439      * </pre>
 440      *
 441      * @param  cause the cause (which is saved for later retrieval by the
 442      *         {@link #getCause()} method).  (A {@code null} value is
 443      *         permitted, and indicates that the cause is nonexistent or
 444      *         unknown.)
 445      * @return  a reference to this {@code Throwable} instance.
 446      * @throws IllegalArgumentException if {@code cause} is this
 447      *         throwable.  (A throwable cannot be its own cause.)
 448      * @throws IllegalStateException if this throwable was
 449      *         created with {@link #Throwable(Throwable)} or
 450      *         {@link #Throwable(String,Throwable)}, or this method has already
 451      *         been called on this throwable.
 452      * @since  1.4
 453      */
 454     public synchronized Throwable initCause(Throwable cause) {
 455         if (this.cause != this)
 456             throw new IllegalStateException("Can't overwrite cause");





 457         if (cause == this)
 458             throw new IllegalArgumentException("Self-causation not permitted");
 459         this.cause = cause;
 460         return this;
 461     }
 462 
 463     /**
 464      * Returns a short description of this throwable.
 465      * The result is the concatenation of:
 466      * <ul>
 467      * <li> the {@linkplain Class#getName() name} of the class of this object
 468      * <li> ": " (a colon and a space)
 469      * <li> the result of invoking this object's {@link #getLocalizedMessage}
 470      *      method
 471      * </ul>
 472      * If {@code getLocalizedMessage} returns {@code null}, then just
 473      * the class name is returned.
 474      *
 475      * @return a string representation of this throwable.
 476      */
 477     public String toString() {
 478         String s = getClass().getName();


1022      * <p>An exception may have suppressed exceptions while also being
1023      * caused by another exception.  Whether or not an exception has a
1024      * cause is semantically known at the time of its creation, unlike
1025      * whether or not an exception will suppress other exceptions
1026      * which is typically only determined after an exception is
1027      * thrown.
1028      *
1029      * <p>Note that programmer written code is also able to take
1030      * advantage of calling this method in situations where there are
1031      * multiple sibling exceptions and only one can be propagated.
1032      *
1033      * @param exception the exception to be added to the list of
1034      *        suppressed exceptions
1035      * @throws IllegalArgumentException if {@code exception} is this
1036      *         throwable; a throwable cannot suppress itself.
1037      * @throws NullPointerException if {@code exception} is {@code null}
1038      * @since 1.7
1039      */
1040     public final synchronized void addSuppressed(Throwable exception) {
1041         if (exception == this)
1042             throw new IllegalArgumentException(SELF_SUPPRESSION_MESSAGE);
1043 
1044         if (exception == null)
1045             throw new NullPointerException(NULL_CAUSE_MESSAGE);
1046 
1047         if (suppressedExceptions == null) // Suppressed exceptions not recorded
1048             return;
1049 
1050         if (suppressedExceptions == SUPPRESSED_SENTINEL)
1051             suppressedExceptions = new ArrayList<>(1);
1052 
1053         suppressedExceptions.add(exception);
1054     }
1055 
1056     private static final Throwable[] EMPTY_THROWABLE_ARRAY = new Throwable[0];
1057 
1058     /**
1059      * Returns an array containing all of the exceptions that were
1060      * suppressed, typically by the {@code try}-with-resources
1061      * statement, in order to deliver this exception.
1062      *


 435      * } catch (LowLevelException le) {
 436      *     throw (HighLevelException)
 437      *           new HighLevelException().initCause(le); // Legacy constructor
 438      * }
 439      * </pre>
 440      *
 441      * @param  cause the cause (which is saved for later retrieval by the
 442      *         {@link #getCause()} method).  (A {@code null} value is
 443      *         permitted, and indicates that the cause is nonexistent or
 444      *         unknown.)
 445      * @return  a reference to this {@code Throwable} instance.
 446      * @throws IllegalArgumentException if {@code cause} is this
 447      *         throwable.  (A throwable cannot be its own cause.)
 448      * @throws IllegalStateException if this throwable was
 449      *         created with {@link #Throwable(Throwable)} or
 450      *         {@link #Throwable(String,Throwable)}, or this method has already
 451      *         been called on this throwable.
 452      * @since  1.4
 453      */
 454     public synchronized Throwable initCause(Throwable cause) {
 455         if (this.cause != this) {
 456             IllegalStateException ise =
 457                 new IllegalStateException("Can't overwrite cause", this);
 458             if (cause != null)
 459                 ise.addSuppressed(cause);
 460             throw ise;
 461         }
 462         if (cause == this)
 463             throw new IllegalArgumentException("Self-causation not permitted", this);
 464         this.cause = cause;
 465         return this;
 466     }
 467 
 468     /**
 469      * Returns a short description of this throwable.
 470      * The result is the concatenation of:
 471      * <ul>
 472      * <li> the {@linkplain Class#getName() name} of the class of this object
 473      * <li> ": " (a colon and a space)
 474      * <li> the result of invoking this object's {@link #getLocalizedMessage}
 475      *      method
 476      * </ul>
 477      * If {@code getLocalizedMessage} returns {@code null}, then just
 478      * the class name is returned.
 479      *
 480      * @return a string representation of this throwable.
 481      */
 482     public String toString() {
 483         String s = getClass().getName();


1027      * <p>An exception may have suppressed exceptions while also being
1028      * caused by another exception.  Whether or not an exception has a
1029      * cause is semantically known at the time of its creation, unlike
1030      * whether or not an exception will suppress other exceptions
1031      * which is typically only determined after an exception is
1032      * thrown.
1033      *
1034      * <p>Note that programmer written code is also able to take
1035      * advantage of calling this method in situations where there are
1036      * multiple sibling exceptions and only one can be propagated.
1037      *
1038      * @param exception the exception to be added to the list of
1039      *        suppressed exceptions
1040      * @throws IllegalArgumentException if {@code exception} is this
1041      *         throwable; a throwable cannot suppress itself.
1042      * @throws NullPointerException if {@code exception} is {@code null}
1043      * @since 1.7
1044      */
1045     public final synchronized void addSuppressed(Throwable exception) {
1046         if (exception == this)
1047             throw new IllegalArgumentException(SELF_SUPPRESSION_MESSAGE, exception);
1048 
1049         if (exception == null)
1050             throw new NullPointerException(NULL_CAUSE_MESSAGE);
1051 
1052         if (suppressedExceptions == null) // Suppressed exceptions not recorded
1053             return;
1054 
1055         if (suppressedExceptions == SUPPRESSED_SENTINEL)
1056             suppressedExceptions = new ArrayList<>(1);
1057 
1058         suppressedExceptions.add(exception);
1059     }
1060 
1061     private static final Throwable[] EMPTY_THROWABLE_ARRAY = new Throwable[0];
1062 
1063     /**
1064      * Returns an array containing all of the exceptions that were
1065      * suppressed, typically by the {@code try}-with-resources
1066      * statement, in order to deliver this exception.
1067      *