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;
27 import jdk.internal.misc.VM;
28
29 import java.io.*;
30 import java.util.*;
31
32 /**
33 * The {@code Throwable} class is the superclass of all errors and
34 * exceptions in the Java language. Only objects that are instances of this
35 * class (or one of its subclasses) are thrown by the Java Virtual Machine or
36 * can be thrown by the Java {@code throw} statement. Similarly, only
37 * this class or one of its subclasses can be the argument type in a
38 * {@code catch} clause.
39 *
40 * For the purposes of compile-time checking of exceptions, {@code
41 * Throwable} and any subclass of {@code Throwable} that is not also a
42 * subclass of either {@link RuntimeException} or {@link Error} are
43 * regarded as checked exceptions.
44 *
45 * <p>Instances of two subclasses, {@link java.lang.Error} and
46 * {@link java.lang.Exception}, are conventionally used to indicate
47 * that exceptional situations have occurred. Typically, these instances
809 * a virtual machine that has no stack trace information concerning
810 * this throwable is permitted to return a zero-length array from this
811 * method. Generally speaking, the array returned by this method will
812 * contain one element for every frame that would be printed by
813 * {@code printStackTrace}. Writes to the returned array do not
814 * affect future calls to this method.
815 *
816 * @return an array of stack trace elements representing the stack trace
817 * pertaining to this throwable.
818 * @since 1.4
819 */
820 public StackTraceElement[] getStackTrace() {
821 return getOurStackTrace().clone();
822 }
823
824 private synchronized StackTraceElement[] getOurStackTrace() {
825 // Initialize stack trace field with information from
826 // backtrace if this is the first call to this method
827 if (stackTrace == UNASSIGNED_STACK ||
828 (stackTrace == null && backtrace != null) /* Out of protocol state */) {
829 stackTrace = new StackTraceElement[depth];
830 for (int i = 0; i < depth; i++) {
831 stackTrace[i] = new StackTraceElement();
832 }
833 getStackTraceElements(stackTrace);
834 } else if (stackTrace == null) {
835 return UNASSIGNED_STACK;
836 }
837 return stackTrace;
838 }
839
840 /**
841 * Sets the stack trace elements that will be returned by
842 * {@link #getStackTrace()} and printed by {@link #printStackTrace()}
843 * and related methods.
844 *
845 * This method, which is designed for use by RPC frameworks and other
846 * advanced systems, allows the client to override the default
847 * stack trace that is either generated by {@link #fillInStackTrace()}
848 * when a throwable is constructed or deserialized when a throwable is
849 * read from a serialization stream.
850 *
851 * <p>If the stack trace of this {@code Throwable} {@linkplain
852 * Throwable#Throwable(String, Throwable, boolean, boolean) is not
853 * writable}, calling this method has no effect other than
865 *
866 * @since 1.4
867 */
868 public void setStackTrace(StackTraceElement[] stackTrace) {
869 // Validate argument
870 StackTraceElement[] defensiveCopy = stackTrace.clone();
871 for (int i = 0; i < defensiveCopy.length; i++) {
872 if (defensiveCopy[i] == null)
873 throw new NullPointerException("stackTrace[" + i + "]");
874 }
875
876 synchronized (this) {
877 if (this.stackTrace == null && // Immutable stack
878 backtrace == null) // Test for out of protocol state
879 return;
880 this.stackTrace = defensiveCopy;
881 }
882 }
883
884 /**
885 * Gets the stack trace elements.
886 * @param elements
887 * @throws IndexOutOfBoundsException if {@code elements.length != depth }
888 */
889 private native void getStackTraceElements(StackTraceElement[] elements);
890
891 /**
892 * Reads a {@code Throwable} from a stream, enforcing
893 * well-formedness constraints on fields. Null entries and
894 * self-pointers are not allowed in the list of {@code
895 * suppressedExceptions}. Null entries are not allowed for stack
896 * trace elements. A null stack trace in the serial form results
897 * in a zero-length stack element array. A single-element stack
898 * trace whose entry is equal to {@code new StackTraceElement("",
899 * "", null, Integer.MIN_VALUE)} results in a {@code null} {@code
900 * stackTrace} field.
901 *
902 * Note that there are no constraints on the value the {@code
903 * cause} field can hold; both {@code null} and {@code this} are
904 * valid values for the field.
905 */
906 private void readObject(ObjectInputStream s)
907 throws IOException, ClassNotFoundException {
908 s.defaultReadObject(); // read in all fields
909 if (suppressedExceptions != null) {
910 List<Throwable> suppressed = null;
911 if (suppressedExceptions.isEmpty()) {
|
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;
27
28 import java.io.*;
29 import java.util.*;
30
31 /**
32 * The {@code Throwable} class is the superclass of all errors and
33 * exceptions in the Java language. Only objects that are instances of this
34 * class (or one of its subclasses) are thrown by the Java Virtual Machine or
35 * can be thrown by the Java {@code throw} statement. Similarly, only
36 * this class or one of its subclasses can be the argument type in a
37 * {@code catch} clause.
38 *
39 * For the purposes of compile-time checking of exceptions, {@code
40 * Throwable} and any subclass of {@code Throwable} that is not also a
41 * subclass of either {@link RuntimeException} or {@link Error} are
42 * regarded as checked exceptions.
43 *
44 * <p>Instances of two subclasses, {@link java.lang.Error} and
45 * {@link java.lang.Exception}, are conventionally used to indicate
46 * that exceptional situations have occurred. Typically, these instances
808 * a virtual machine that has no stack trace information concerning
809 * this throwable is permitted to return a zero-length array from this
810 * method. Generally speaking, the array returned by this method will
811 * contain one element for every frame that would be printed by
812 * {@code printStackTrace}. Writes to the returned array do not
813 * affect future calls to this method.
814 *
815 * @return an array of stack trace elements representing the stack trace
816 * pertaining to this throwable.
817 * @since 1.4
818 */
819 public StackTraceElement[] getStackTrace() {
820 return getOurStackTrace().clone();
821 }
822
823 private synchronized StackTraceElement[] getOurStackTrace() {
824 // Initialize stack trace field with information from
825 // backtrace if this is the first call to this method
826 if (stackTrace == UNASSIGNED_STACK ||
827 (stackTrace == null && backtrace != null) /* Out of protocol state */) {
828 stackTrace = StackTraceElement.of(this, depth);
829 } else if (stackTrace == null) {
830 return UNASSIGNED_STACK;
831 }
832 return stackTrace;
833 }
834
835 /**
836 * Sets the stack trace elements that will be returned by
837 * {@link #getStackTrace()} and printed by {@link #printStackTrace()}
838 * and related methods.
839 *
840 * This method, which is designed for use by RPC frameworks and other
841 * advanced systems, allows the client to override the default
842 * stack trace that is either generated by {@link #fillInStackTrace()}
843 * when a throwable is constructed or deserialized when a throwable is
844 * read from a serialization stream.
845 *
846 * <p>If the stack trace of this {@code Throwable} {@linkplain
847 * Throwable#Throwable(String, Throwable, boolean, boolean) is not
848 * writable}, calling this method has no effect other than
860 *
861 * @since 1.4
862 */
863 public void setStackTrace(StackTraceElement[] stackTrace) {
864 // Validate argument
865 StackTraceElement[] defensiveCopy = stackTrace.clone();
866 for (int i = 0; i < defensiveCopy.length; i++) {
867 if (defensiveCopy[i] == null)
868 throw new NullPointerException("stackTrace[" + i + "]");
869 }
870
871 synchronized (this) {
872 if (this.stackTrace == null && // Immutable stack
873 backtrace == null) // Test for out of protocol state
874 return;
875 this.stackTrace = defensiveCopy;
876 }
877 }
878
879 /**
880 * Reads a {@code Throwable} from a stream, enforcing
881 * well-formedness constraints on fields. Null entries and
882 * self-pointers are not allowed in the list of {@code
883 * suppressedExceptions}. Null entries are not allowed for stack
884 * trace elements. A null stack trace in the serial form results
885 * in a zero-length stack element array. A single-element stack
886 * trace whose entry is equal to {@code new StackTraceElement("",
887 * "", null, Integer.MIN_VALUE)} results in a {@code null} {@code
888 * stackTrace} field.
889 *
890 * Note that there are no constraints on the value the {@code
891 * cause} field can hold; both {@code null} and {@code this} are
892 * valid values for the field.
893 */
894 private void readObject(ObjectInputStream s)
895 throws IOException, ClassNotFoundException {
896 s.defaultReadObject(); // read in all fields
897 if (suppressedExceptions != null) {
898 List<Throwable> suppressed = null;
899 if (suppressedExceptions.isEmpty()) {
|