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 java.io.*;
28 import java.util.*;
29
30 /**
31 * The {@code Throwable} class is the superclass of all errors and
32 * exceptions in the Java language. Only objects that are instances of this
33 * class (or one of its subclasses) are thrown by the Java Virtual Machine or
34 * can be thrown by the Java {@code throw} statement. Similarly, only
35 * this class or one of its subclasses can be the argument type in a
36 * {@code catch} clause.
37 *
38 * For the purposes of compile-time checking of exceptions, {@code
39 * Throwable} and any subclass of {@code Throwable} that is not also a
40 * subclass of either {@link RuntimeException} or {@link Error} are
41 * regarded as checked exceptions.
42 *
43 * <p>Instances of two subclasses, {@link java.lang.Error} and
44 * {@link java.lang.Exception}, are conventionally used to indicate
45 * that exceptional situations have occurred. Typically, these instances
46 * are freshly created in the context of the exceptional situation so
761 void println(Object o) {
762 printWriter.println(o);
763 }
764 }
765
766 /**
767 * Fills in the execution stack trace. This method records within this
768 * {@code Throwable} object information about the current state of
769 * the stack frames for the current thread.
770 *
771 * <p>If the stack trace of this {@code Throwable} {@linkplain
772 * Throwable#Throwable(String, Throwable, boolean, boolean) is not
773 * writable}, calling this method has no effect.
774 *
775 * @return a reference to this {@code Throwable} instance.
776 * @see java.lang.Throwable#printStackTrace()
777 */
778 public synchronized Throwable fillInStackTrace() {
779 if (stackTrace != null ||
780 backtrace != null /* Out of protocol state */ ) {
781 fillInStackTrace(0);
782 stackTrace = UNASSIGNED_STACK;
783 }
784 return this;
785 }
786
787 private native Throwable fillInStackTrace(int dummy);
788
789 /**
790 * Provides programmatic access to the stack trace information printed by
791 * {@link #printStackTrace()}. Returns an array of stack trace elements,
792 * each representing one stack frame. The zeroth element of the array
793 * (assuming the array's length is non-zero) represents the top of the
794 * stack, which is the last method invocation in the sequence. Typically,
795 * this is the point at which this throwable was created and thrown.
796 * The last element of the array (assuming the array's length is non-zero)
797 * represents the bottom of the stack, which is the first method invocation
798 * in the sequence.
799 *
800 * <p>Some virtual machines may, under some circumstances, omit one
801 * or more stack frames from the stack trace. In the extreme case,
802 * a virtual machine that has no stack trace information concerning
803 * this throwable is permitted to return a zero-length array from this
804 * method. Generally speaking, the array returned by this method will
805 * contain one element for every frame that would be printed by
806 * {@code printStackTrace}. Writes to the returned array do not
807 * affect future calls to this method.
808 *
809 * @return an array of stack trace elements representing the stack trace
810 * pertaining to this throwable.
811 * @since 1.4
812 */
813 public StackTraceElement[] getStackTrace() {
814 return getOurStackTrace().clone();
815 }
816
817 private synchronized StackTraceElement[] getOurStackTrace() {
818 // Initialize stack trace field with information from
819 // backtrace if this is the first call to this method
820 if (stackTrace == UNASSIGNED_STACK ||
821 (stackTrace == null && backtrace != null) /* Out of protocol state */) {
822 int depth = getStackTraceDepth();
823 stackTrace = new StackTraceElement[depth];
824 for (int i=0; i < depth; i++)
825 stackTrace[i] = getStackTraceElement(i);
826 } else if (stackTrace == null) {
827 return UNASSIGNED_STACK;
828 }
829 return stackTrace;
830 }
831
832 /**
833 * Sets the stack trace elements that will be returned by
834 * {@link #getStackTrace()} and printed by {@link #printStackTrace()}
835 * and related methods.
836 *
837 * This method, which is designed for use by RPC frameworks and other
838 * advanced systems, allows the client to override the default
839 * stack trace that is either generated by {@link #fillInStackTrace()}
840 * when a throwable is constructed or deserialized when a throwable is
841 * read from a serialization stream.
842 *
843 * <p>If the stack trace of this {@code Throwable} {@linkplain
844 * Throwable#Throwable(String, Throwable, boolean, boolean) is not
845 * writable}, calling this method has no effect other than
|
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 sun.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
48 * are freshly created in the context of the exceptional situation so
763 void println(Object o) {
764 printWriter.println(o);
765 }
766 }
767
768 /**
769 * Fills in the execution stack trace. This method records within this
770 * {@code Throwable} object information about the current state of
771 * the stack frames for the current thread.
772 *
773 * <p>If the stack trace of this {@code Throwable} {@linkplain
774 * Throwable#Throwable(String, Throwable, boolean, boolean) is not
775 * writable}, calling this method has no effect.
776 *
777 * @return a reference to this {@code Throwable} instance.
778 * @see java.lang.Throwable#printStackTrace()
779 */
780 public synchronized Throwable fillInStackTrace() {
781 if (stackTrace != null ||
782 backtrace != null /* Out of protocol state */ ) {
783 if (backtrace == null && StackStreamFactory.useStackTrace(this)) {
784 backtrace = StackStreamFactory.makeStackTrace(this);
785 } else {
786 fillInStackTrace(0);
787 }
788 stackTrace = UNASSIGNED_STACK;
789 }
790 return this;
791 }
792
793 private native Throwable fillInStackTrace(int dummy);
794
795 /**
796 * Provides programmatic access to the stack trace information printed by
797 * {@link #printStackTrace()}. Returns an array of stack trace elements,
798 * each representing one stack frame. The zeroth element of the array
799 * (assuming the array's length is non-zero) represents the top of the
800 * stack, which is the last method invocation in the sequence. Typically,
801 * this is the point at which this throwable was created and thrown.
802 * The last element of the array (assuming the array's length is non-zero)
803 * represents the bottom of the stack, which is the first method invocation
804 * in the sequence.
805 *
806 * <p>Some virtual machines may, under some circumstances, omit one
807 * or more stack frames from the stack trace. In the extreme case,
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 if (backtrace instanceof StackStreamFactory.StackTrace) {
829 stackTrace = ((StackStreamFactory.StackTrace)backtrace).getStackTraceElements();
830 } else {
831 int depth = getStackTraceDepth();
832 stackTrace = new StackTraceElement[depth];
833 for (int i = 0; i < depth; i++)
834 stackTrace[i] = getStackTraceElement(i);
835 }
836 } else if (stackTrace == null) {
837 return UNASSIGNED_STACK;
838 }
839 return stackTrace;
840 }
841
842 /**
843 * Sets the stack trace elements that will be returned by
844 * {@link #getStackTrace()} and printed by {@link #printStackTrace()}
845 * and related methods.
846 *
847 * This method, which is designed for use by RPC frameworks and other
848 * advanced systems, allows the client to override the default
849 * stack trace that is either generated by {@link #fillInStackTrace()}
850 * when a throwable is constructed or deserialized when a throwable is
851 * read from a serialization stream.
852 *
853 * <p>If the stack trace of this {@code Throwable} {@linkplain
854 * Throwable#Throwable(String, Throwable, boolean, boolean) is not
855 * writable}, calling this method has no effect other than
|