001: /*
002: *
003: *
004: * Copyright 1990-2007 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: */
026:
027: package java.lang;
028:
029: /**
030: * The <code>Throwable</code> class is the superclass of all errors
031: * and exceptions in the Java language. Only objects that are
032: * instances of this class (or of one of its subclasses) are thrown
033: * by the Java Virtual Machine or can be thrown by the Java
034: * <code>throw</code> statement. Similarly, only this class or one of
035: * its subclasses can be the argument type in a <code>catch</code>
036: * clause.
037: * <p>
038: * Instances of two subclasses, {@link java.lang.Error} and
039: * {@link java.lang.Exception}, are conventionally used to indicate
040: * that exceptional situations have occurred. Typically, these instances
041: * are freshly created in the context of the exceptional situation so
042: * as to include relevant information (such as stack trace data).
043: * <p>
044: * By convention, class <code>Throwable</code> and its subclasses have
045: * two constructors, one that takes no arguments and one that takes a
046: * <code>String</code> argument that can be used to produce an error
047: * message.
048: * <p>
049: * A <code>Throwable</code> class contains a snapshot of the
050: * execution stack of its thread at the time it was created. It can
051: * also contain a message string that gives more information about
052: * the error.
053: * <p>
054: * Here is one example of catching an exception:
055: * <p><blockquote><pre>
056: * try {
057: * int a[] = new int[2];
058: * int b = a[4];
059: * } catch (ArrayIndexOutOfBoundsException e) {
060: * System.out.println("exception: " + e.getMessage());
061: * e.printStackTrace();
062: * }
063: * </pre></blockquote>
064: *
065: * @version 12/17/01 (CLDC 1.1)
066: * @since JDK1.0, CLDC 1.0
067: */
068: public class Throwable {
069:
070: /** WARNING: this must be the first variable.
071: * Specific details about the <code>Throwable</code> object.
072: */
073: private String detailMessage;
074:
075: /** WARNING: this must be the second variable.
076: * Native code saves some indication of the stack backtrace in this
077: * slot.
078: */
079: private transient Object backtrace;
080:
081: /**
082: * Constructs a new <code>Throwable</code> with <code>null</code> as
083: * its error message string.
084: */
085: public Throwable() {
086: fillInStackTrace(); // Added for this VM
087: }
088:
089: /**
090: * Constructs a new <code>Throwable</code> with the specified error
091: * message.
092: *
093: * @param message the error message. The error message is saved for
094: * later retrieval by the {@link #getMessage()} method.
095: */
096: public Throwable(String message) {
097: fillInStackTrace(); // Added for this VM
098: detailMessage = message;
099: }
100:
101: /**
102: * Returns the error message string of this <code>Throwable</code> object.
103: *
104: * @return the error message string of this <code>Throwable</code>
105: * object if it was {@link #Throwable(String) created} with an
106: * error message string; or <code>null</code> if it was
107: * {@link #Throwable() created} with no error message.
108: *
109: */
110: public String getMessage() {
111: return detailMessage;
112: }
113:
114: /**
115: * Returns a short description of this <code>Throwable</code> object.
116: * If this <code>Throwable</code> object was
117: * {@link #Throwable(String) created} with an error message string,
118: * then the result is the concatenation of three strings:
119: * <ul>
120: * <li>The name of the actual class of this object
121: * <li>": " (a colon and a space)
122: * <li>The result of the {@link #getMessage} method for this object
123: * </ul>
124: * If this <code>Throwable</code> object was {@link #Throwable() created}
125: * with no error message string, then the name of the actual class of
126: * this object is returned.
127: *
128: * @return a string representation of this <code>Throwable</code>.
129: */
130: public String toString() {
131: String s = getClass().getName();
132: String message = getMessage();
133: return (message != null) ? (s + ": " + message) : s;
134: }
135:
136: /**
137: * Prints this <code>Throwable</code> and its backtrace to the
138: * standard error stream. This method prints a stack trace for this
139: * <code>Throwable</code> object on the error output stream that is
140: * the value of the field <code>System.err</code>. The first line of
141: * output contains the result of the {@link #toString()} method for
142: * this object. <p>
143: *
144: * The format of the backtrace information depends on the implementation.
145: */
146: /*
147: public void printStackTrace() {
148: java.io.PrintStream err = System.err;
149: String message = getMessage();
150: err.print(this.getClass().getName());
151: if (message != null) {
152: err.print(": ");
153: err.println(message);
154: } else {
155: err.println();
156: }
157: if (backtrace != null) {
158: printStackTrace0(System.err);
159: }
160: }
161: */
162:
163: public native void printStackTrace();
164:
165: /* Added for this VM but made private since */
166: /* the CLDC standard does not support this method */
167:
168: /* Original comments deleted. They referred to a user callable version
169: * of this function that returned a value.
170: */
171:
172: /**
173: * Fills in the execution stack trace. This method records within this
174: * <code>Throwable</code> object information about the current state of
175: * the stack frames for the current thread.
176: */
177: private native void fillInStackTrace();
178: }
|