home *** CD-ROM | disk | FTP | other *** search
/ Apple Developer Connection Student Program / ADC Tools Sampler CD Disk 3 1999.iso / Metrowerks CodeWarrior / Java Support / Java_Source / Java2 / src / java / lang / Throwable.java < prev    next >
Encoding:
Java Source  |  1999-05-28  |  7.8 KB  |  236 lines  |  [TEXT/CWIE]
  1. /*
  2.  * @(#)Throwable.java    1.38 98/08/24
  3.  *
  4.  * Copyright 1994-1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  *
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.lang;
  16.  
  17. /**
  18.  * The <code>Throwable</code> class is the superclass of all errors 
  19.  * and exceptions in the Java language. Only objects that are 
  20.  * instances of this class (or of one of its subclasses) are thrown 
  21.  * by the Java Virtual Machine or can be thrown by the Java 
  22.  * <code>throw</code> statement. Similarly, only this class or one of 
  23.  * its subclasses can be the argument type in a <code>catch</code> 
  24.  * clause. 
  25.  * <p>
  26.  * Instances of two subclasses, {@link java.lang.Error} and 
  27.  * {@link java.lang.Exception}, are conventionally used to indicate 
  28.  * that exceptional situations have occurred. Typically, these instances 
  29.  * are freshly created in the context of the exceptional situation so 
  30.  * as to include relevant information (such as stack trace data).
  31.  * <p>
  32.  * By convention, class <code>Throwable</code> and its subclasses have 
  33.  * two constructors, one that takes no arguments and one that takes a 
  34.  * <code>String</code> argument that can be used to produce an error 
  35.  * message.
  36.  * <p>
  37.  * A <code>Throwable</code> class contains a snapshot of the 
  38.  * execution stack of its thread at the time it was created. It can 
  39.  * also contain a message string that gives more information about 
  40.  * the error. 
  41.  * <p>
  42.  * Here is one example of catching an exception: 
  43.  * <p><blockquote><pre>
  44.  *     try {
  45.  *         int a[] = new int[2];
  46.  *         a[4];
  47.  *     } catch (ArrayIndexOutOfBoundsException e) {
  48.  *         System.out.println("exception: " + e.getMessage());
  49.  *         e.printStackTrace();
  50.  *     }
  51.  * </pre></blockquote>
  52.  *
  53.  * @author  unascribed
  54.  * @version 1.31, 01/26/97
  55.  * @since   JDK1.0
  56.  */
  57. public class Throwable implements java.io.Serializable {
  58.     /**
  59.      * Native code saves some indication of the stack backtrace in this
  60.      * slot.
  61.      */
  62.     private transient Object backtrace;    
  63.  
  64.     /**
  65.      * Specific details about the Throwable.  For example,
  66.      * for FileNotFoundThrowables, this contains the name of
  67.      * the file that could not be found.
  68.      *
  69.      * @serial
  70.      */
  71.     private String detailMessage;
  72.  
  73.     /** use serialVersionUID from JDK 1.0.2 for interoperability */
  74.     private static final long serialVersionUID = -3042686055658047285L;
  75.  
  76.     /**
  77.      * Constructs a new <code>Throwable</code> with <code>null</code> as 
  78.      * its error message string. Also, the method 
  79.      * {@link #fillInStackTrace()} is called for this object. 
  80.      */
  81.     public Throwable() {
  82.     fillInStackTrace();
  83.     }
  84.  
  85.     /**
  86.      * Constructs a new <code>Throwable</code> with the specified error 
  87.      * message. Also, the method {@link @fillInStackTrace()} is called for 
  88.      * this object.
  89.      *
  90.      * @param   message   the error message. The error message is saved for 
  91.      *          later retrieval by the {@link @getMessage()} method.
  92.      */
  93.     public Throwable(String message) {
  94.     fillInStackTrace();
  95.     detailMessage = message;
  96.     }
  97.  
  98.     /**
  99.      * Returns the errort message string of this throwable object.
  100.      *
  101.      * @return  the error message string of this <code>Throwable</code> 
  102.      *          object if it was {@link #Throwable(String) created} with an 
  103.      *          error message string; or <code>null</code> if it was 
  104.      *          {@link #Throwable() created} with no error message. 
  105.      *            
  106.      */
  107.     public String getMessage() {
  108.     return detailMessage;
  109.     }
  110.  
  111.     /**
  112.      * Creates a localized description of this <code>Throwable</code>.
  113.      * Subclasses may override this method in order to produce a
  114.      * locale-specific message.  For subclasses that do not override this
  115.      * method, the default implementation returns the same result as
  116.      * <code>getMessage()</code>.
  117.      *
  118.      * @since   JDK1.1
  119.      */
  120.     public String getLocalizedMessage() {
  121.     return getMessage();
  122.     }
  123.  
  124.     /**
  125.      * Returns a short description of this throwable object.
  126.      * If this <code>Throwable</code> object was 
  127.      * {@link #Throwable(String) created} with an error message string, 
  128.      * then the result is the concatenation of three strings: 
  129.      * <ul>
  130.      * <li>The name of the actual class of this object 
  131.      * <li>": " (a colon and a space) 
  132.      * <li>The result of the {@link #getMessage} method for this object 
  133.      * </ul>
  134.      * If this <code>Throwable</code> object was {@link #Throwable() created} 
  135.      * with no error message string, then the name of the actual class of 
  136.      * this object is returned.
  137.      *
  138.      * @return  a string representation of this <code>Throwable</code>.
  139.      */
  140.     public String toString() {
  141.     String s = getClass().getName();
  142.     String message = getLocalizedMessage();
  143.     return (message != null) ? (s + ": " + message) : s;
  144.     }
  145.  
  146.     /**
  147.      * Prints this <code>Throwable</code> and its backtrace to the 
  148.      * standard error stream. This method prints a stack trace for this 
  149.      * <code>Throwable</code> object on the error output stream that is 
  150.      * the value of the field <code>System.err</code>. The first line of 
  151.      * output contains the result of the {@link #toString()} method for 
  152.      * this object. Remaining lines represent data previously recorded by 
  153.      * the method {@link #fillInStackTrace()}. The format of this 
  154.      * information depends on the implementation, but the following 
  155.      * example may be regarded as typical: 
  156.      * <blockquote><pre>
  157.      * java.lang.NullPointerException
  158.      *         at MyClass.mash(MyClass.java:9)
  159.      *         at MyClass.crunch(MyClass.java:6)
  160.      *         at MyClass.main(MyClass.java:3)
  161.      * </pre></blockquote>
  162.      * This example was produced by running the program: 
  163.      * <blockquote><pre>
  164.      * 
  165.      * class MyClass {
  166.      * 
  167.      *     public static void main(String[] argv) {
  168.      *         crunch(null);
  169.      *     }
  170.      *     static void crunch(int[] a) {
  171.      *         mash(a);
  172.      *     }
  173.      * 
  174.      *     static void mash(int[] b) {
  175.      *         System.out.println(b[0]);
  176.      *     }
  177.      * }
  178.      * </pre></blockquote>
  179.      *
  180.      * @see     java.lang.System#err
  181.      */
  182.     public void printStackTrace() { 
  183.     synchronized (System.err) {
  184.         System.err.println(this);
  185.         printStackTrace0(System.err);
  186.     }
  187.     }
  188.  
  189.     /**
  190.      * Prints this <code>Throwable</code> and its backtrace to the 
  191.      * specified print stream. 
  192.      */
  193.     public void printStackTrace(java.io.PrintStream s) { 
  194.     synchronized (s) {
  195.         s.println(this);
  196.         printStackTrace0(s);
  197.     }
  198.     }
  199.  
  200.     /**
  201.      * Prints this <code>Throwable</code> and its backtrace to the specified
  202.      * print writer.
  203.      *
  204.      * @since   JDK1.1
  205.      */
  206.     public void printStackTrace(java.io.PrintWriter s) { 
  207.     synchronized (s) {
  208.         s.println(this);
  209.         printStackTrace0(s);
  210.     }
  211.     }
  212.  
  213.     /* The given object must have a void println(char[]) method */
  214.     private native void printStackTrace0(Object s);
  215.  
  216.     /**
  217.      * Fills in the execution stack trace. This method records within this 
  218.      * <code>Throwable</code> object information about the current state of 
  219.      * the stack frames for the current thread. This method is useful when 
  220.      * an application is re-throwing an error or exception. For example: 
  221.      * <p><blockquote><pre>
  222.      *     try {
  223.      *         a = b / c;
  224.      *     } catch(ArithmeticThrowable e) {
  225.      *         a = Number.MAX_VALUE;
  226.      *         throw e.fillInStackTrace();
  227.      *     }
  228.      * </pre></blockquote>
  229.      *
  230.      * @return  this <code>Throwable</code> object.
  231.      * @see     java.lang.Throwable#printStackTrace()
  232.      */
  233.     public native Throwable fillInStackTrace();
  234.  
  235. }
  236.