      1 /*
      2  * Copyright (c) 1999, 2019, Oracle and/or its affiliates. All rights reserved.
      3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
      4  *
      5  * This code is free software; you can redistribute it and/or modify it
      6  * under the terms of the GNU General Public License version 2 only, as
      7  * published by the Free Software Foundation.  Oracle designates this
      8  * particular file as subject to the "Classpath" exception as provided
      9  * by Oracle in the LICENSE file that accompanied this code.
     10  *
     11  * This code is distributed in the hope that it will be useful, but WITHOUT
     12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
     13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
     14  * version 2 for more details (a copy is included in the LICENSE file that
     15  * accompanied this code).
     16  *
     17  * You should have received a copy of the GNU General Public License version
     18  * 2 along with this work; if not, write to the Free Software Foundation,
     19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
     20  *
     21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
     22  * or visit www.oracle.com if you need additional information or have any
     23  * questions.
     24  */
     25
     26 package java.lang.reflect;
     27
     28 import java.io.IOException;
     29 import java.io.ObjectInputStream;
     30 import java.io.ObjectOutputStream;
     31 import java.io.ObjectStreamField;
     32 import jdk.internal.access.SharedSecrets;
     33
     34 /**
     35  * Thrown by a method invocation on a proxy instance if its invocation
     36  * handler's {@link InvocationHandler#invoke invoke} method throws a
     37  * checked exception (a {@code Throwable} that is not assignable
     38  * to {@code RuntimeException} or {@code Error}) that
     39  * is not assignable to any of the exception types declared in the
     40  * {@code throws} clause of the method that was invoked on the
     41  * proxy instance and dispatched to the invocation handler.
     42  *
     43  * <p>An {@code UndeclaredThrowableException} instance contains
     44  * the undeclared checked exception that was thrown by the invocation
     45  * handler, and it can be retrieved with the
     46  * {@code getUndeclaredThrowable()} method.
     47  * {@code UndeclaredThrowableException} extends
     48  * {@code RuntimeException}, so it is an unchecked exception
     49  * that wraps a checked exception.
     50  *
     51  * <p>As of release 1.4, this exception has been retrofitted to
     52  * conform to the general purpose exception-chaining mechanism.  The
     53  * "undeclared checked exception that was thrown by the invocation
     54  * handler" that may be provided at construction time and accessed via
     55  * the {@link #getUndeclaredThrowable()} method is now known as the
     56  * <i>cause</i>, and may be accessed via the {@link
     57  * Throwable#getCause()} method, as well as the aforementioned "legacy
     58  * method."
     59  *
     60  * @author      Peter Jones
     61  * @see         InvocationHandler
     62  * @since       1.3
     63  */
     64 public class UndeclaredThrowableException extends RuntimeException {
     65     @java.io.Serial
     66     static final long serialVersionUID = 330127114055056639L;
     67
     68     /**
     69      * Constructs an {@code UndeclaredThrowableException} with the
     70      * specified {@code Throwable}.
     71      *
     72      * @param   undeclaredThrowable the undeclared checked exception
     73      *          that was thrown
     74      */
     75     public UndeclaredThrowableException(Throwable undeclaredThrowable) {
     76         super(null, undeclaredThrowable);  // Disallow initCause
     77     }
     78
     79     /**
     80      * Constructs an {@code UndeclaredThrowableException} with the
     81      * specified {@code Throwable} and a detail message.
     82      *
     83      * @param   undeclaredThrowable the undeclared checked exception
     84      *          that was thrown
     85      * @param   s the detail message
     86      */
     87     public UndeclaredThrowableException(Throwable undeclaredThrowable,
     88                                         String s)
     89     {
     90         super(s, undeclaredThrowable);  // Disallow initCause
     91     }
     92
     93     /**
     94      * Returns the {@code Throwable} instance wrapped in this
     95      * {@code UndeclaredThrowableException}, which may be {@code null}.
     96      *
     97      * <p>This method predates the general-purpose exception chaining facility.
     98      * The {@link Throwable#getCause()} method is now the preferred means of
     99      * obtaining this information.
    100      *
    101      * @return the undeclared checked exception that was thrown
    102      */
    103     public Throwable getUndeclaredThrowable() {
    104         return super.getCause();
    105     }
    106
    107     /**
    108      * Serializable fields for UndeclaredThrowableException.
    109      *
    110      * @serialField undeclaredThrowable Throwable
    111      */
    112     @java.io.Serial
    113     private static final ObjectStreamField[] serialPersistentFields = {
    114         new ObjectStreamField("undeclaredThrowable", Throwable.class)
    115     };
    116
    117     /*
    118      * Reconstitutes the UndeclaredThrowableException instance from a stream
    119      * and initialize the cause properly when deserializing from an older
    120      * version.

    121      */
    122     @java.io.Serial
    123     private void readObject(ObjectInputStream s) throws IOException, ClassNotFoundException {
    124         ObjectInputStream.GetField fields = s.readFields();
    125         Throwable exception = (Throwable) fields.get("undeclaredThrowable", null);
    126         if (exception != null) {
    127             SharedSecrets.getJavaLangAccess().setCause(this, exception);
    128         }
    129     }
    130
    131     /*
    132      * To maintain compatibility with older implementation, write a serial
    133      * "ex" field with the cause as the value.

    134      */
    135     @java.io.Serial
    136     private void writeObject(ObjectOutputStream out) throws IOException {
    137         ObjectOutputStream.PutField fields = out.putFields();
    138         fields.put("undeclaredThrowable", super.getCause());
    139         out.writeFields();
    140     }
    141 }
    --- EOF ---