1. /*

  2.  * @(#)StackTraceElement.java	1.10 04/02/19

  3.  *

  4.  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.

  5.  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.

  6.  */

  7. 

  8. package java.lang;

  9. 

  10. /**

  11.  * An element in a stack trace, as returned by {@link

  12.  * Throwable#getStackTrace()}.  Each element represents a single stack frame.

  13.  * All stack frames except for the one at the top of the stack represent

  14.  * a method invocation.  The frame at the top of the stack represents the 

  15.  * execution point at which the stack trace was generated.  Typically,

  16.  * this is the point at which the throwable corresponding to the stack trace

  17.  * was created.

  18.  *

  19.  * @since  1.4

  20.  * @author Josh Bloch

  21.  */

  22. public final class StackTraceElement implements java.io.Serializable {

  23.     // Normally initialized by VM (public constructor added in 1.5)

  24.     private String declaringClass;

  25.     private String methodName;

  26.     private String fileName;

  27.     private int    lineNumber;

  28. 

  29.     /**

  30.      * Creates a stack trace element representing the specified execution

  31.      * point.

  32.      *

  33.      * @param declaringClass the fully qualified name of the class containing

  34.      *        the execution point represented by the stack trace element

  35.      * @param methodName the name of the method containing the execution point

  36.      *        represented by the stack trace element

  37.      * @param fileName the name of the file containing the execution point

  38.      *         represented by the stack trace element, or <tt>null</tt> if

  39.      *         this information is unavailable

  40.      * @param lineNumber the line number of the source line containing the

  41.      *         execution point represented by this stack trace element, or

  42.      *         a negative number if this information is unavailable. A value

  43.      *         of -2 indicates that the method containing the execution point

  44.      *         is a native method

  45.      * @throws NullPointerException if <tt>declaringClass</tt> or

  46.      *         <tt>methodName</tt> is null

  47.      * @since 1.5

  48.      */

  49.     public StackTraceElement(String declaringClass, String methodName,

  50.                              String fileName, int lineNumber) {

  51.         if (declaringClass == null)

  52.             throw new NullPointerException("Declaring class is null");

  53.         if (methodName == null)

  54.             throw new NullPointerException("Method name is null");

  55.  

  56.         this.declaringClass = declaringClass;

  57.         this.methodName     = methodName;

  58.         this.fileName       = fileName;

  59.         this.lineNumber     = lineNumber;

  60.     }

  61. 

  62.     /**

  63.      * Returns the name of the source file containing the execution point

  64.      * represented by this stack trace element.  Generally, this corresponds

  65.      * to the <tt>SourceFile</tt> attribute of the relevant <tt>class</tt>

  66.      * file (as per <i>The Java Virtual Machine Specification</i>, Section

  67.      * 4.7.7).  In some systems, the name may refer to some source code unit

  68.      * other than a file, such as an entry in source repository.

  69.      *

  70.      * @return the name of the file containing the execution point

  71.      *         represented by this stack trace element, or <tt>null</tt> if

  72.      *         this information is unavailable.

  73.      */

  74.     public String getFileName() {

  75.         return fileName;

  76.     }

  77. 

  78.     /**

  79.      * Returns the line number of the source line containing the execution

  80.      * point represented by this stack trace element.  Generally, this is

  81.      * derived from the <tt>LineNumberTable</tt> attribute of the relevant

  82.      * <tt>class</tt> file (as per <i>The Java Virtual Machine

  83.      * Specification</i>, Section 4.7.8).

  84.      *

  85.      * @return the line number of the source line containing the execution

  86.      *         point represented by this stack trace element, or a negative

  87.      *         number if this information is unavailable.

  88.      */

  89.     public int getLineNumber() {

  90.         return lineNumber;

  91.     }

  92. 

  93.     /**

  94.      * Returns the fully qualified name of the class containing the

  95.      * execution point represented by this stack trace element.

  96.      *

  97.      * @return the fully qualified name of the <tt>Class</tt> containing

  98.      *         the execution point represented by this stack trace element.

  99.      */

  100.     public String getClassName() {

  101.         return declaringClass;

  102.     }

  103. 

  104.     /**

  105.      * Returns the name of the method containing the execution point

  106.      * represented by this stack trace element.  If the execution point is

  107.      * contained in an instance or class initializer, this method will return

  108.      * the appropriate <i>special method name</i>, <tt><init></tt> or

  109.      * <tt><clinit></tt>, as per Section 3.9 of <i>The Java Virtual

  110.      * Machine Specification</i>.

  111.      *

  112.      * @return the name of the method containing the execution point

  113.      *         represented by this stack trace element.

  114.      */

  115.     public String getMethodName() {

  116.         return methodName;

  117.     }

  118. 

  119.     /**

  120.      * Returns true if the method containing the execution point

  121.      * represented by this stack trace element is a native method.

  122.      *

  123.      * @return <tt>true</tt> if the method containing the execution point

  124.      *         represented by this stack trace element is a native method.

  125.      */

  126.     public boolean isNativeMethod() {

  127.         return lineNumber == -2;

  128.     }

  129. 

  130.     /**

  131.      * Returns a string representation of this stack trace element.  The

  132.      * format of this string depends on the implementation, but the following

  133.      * examples may be regarded as typical:

  134.      * <ul>

  135.      * <li>

  136.      *   <tt>"MyClass.mash(MyClass.java:9)"</tt> - Here, <tt>"MyClass"</tt>

  137.      *   is the <i>fully-qualified name</i> of the class containing the

  138.      *   execution point represented by this stack trace element,

  139.      *   <tt>"mash"</tt> is the name of the method containing the execution

  140.      *   point, <tt>"MyClass.java"</tt> is the source file containing the

  141.      *   execution point, and <tt>"9"</tt> is the line number of the source

  142.      *   line containing the execution point.

  143.      * <li>

  144.      *   <tt>"MyClass.mash(MyClass.java)"</tt> - As above, but the line

  145.      *   number is unavailable.

  146.      * <li>

  147.      *   <tt>"MyClass.mash(Unknown Source)"</tt> - As above, but neither

  148.      *   the file name nor the line  number are available.

  149.      * <li>

  150.      *   <tt>"MyClass.mash(Native Method)"</tt> - As above, but neither

  151.      *   the file name nor the line  number are available, and the method

  152.      *   containing the execution point is known to be a native method.

  153.      * </ul>

  154.      * @see    Throwable#printStackTrace()

  155.      */

  156.     public String toString() {

  157.         return getClassName() + "." + methodName +

  158.             (isNativeMethod() ? "(Native Method)" :

  159.              (fileName != null && lineNumber >= 0 ?

  160.               "(" + fileName + ":" + lineNumber + ")" :

  161.               (fileName != null ?  "("+fileName+")" : "(Unknown Source)")));

  162.     }

  163. 

  164.     /**

  165.      * Returns true if the specified object is another

  166.      * <tt>StackTraceElement</tt> instance representing the same execution

  167.      * point as this instance.  Two stack trace elements <tt>a</tt> and

  168.      * <tt>b</tt> are equal if and only if:

  169.      * <pre>

  170.      *     equals(a.getFileName(), b.getFileName()) &&

  171.      *     a.getLineNumber() == b.getLineNumber()) &&

  172.      *     equals(a.getClassName(), b.getClassName()) &&

  173.      *     equals(a.getMethodName(), b.getMethodName())

  174.      * </pre>

  175.      * where <tt>equals</tt> is defined as:

  176.      * <pre>

  177.      *     static boolean equals(Object a, Object b) {

  178.      *         return a==b || (a != null && a.equals(b));

  179.      *     }

  180.      * </pre>

  181.      * 

  182.      * @param  obj the object to be compared with this stack trace element.

  183.      * @return true if the specified object is another

  184.      *         <tt>StackTraceElement</tt> instance representing the same

  185.      *         execution point as this instance.

  186.      */

  187.     public boolean equals(Object obj) {

  188.         if (obj==this)

  189.             return true;

  190.         if (!(obj instanceof StackTraceElement))

  191.             return false;

  192.         StackTraceElement e = (StackTraceElement)obj;

  193.         return e.declaringClass.equals(declaringClass) && e.lineNumber == lineNumber

  194.             && eq(methodName, e.methodName) && eq(fileName, e.fileName);

  195.     }

  196. 

  197.     private static boolean eq(Object a, Object b) {

  198.         return a==b || (a != null && a.equals(b));

  199.     }

  200. 

  201.     /**

  202.      * Returns a hash code value for this stack trace element.

  203.      */

  204.     public int hashCode() {

  205.         int result = 31*declaringClass.hashCode() + methodName.hashCode();

  206.         result = 31*result + (fileName == null ?   0 : fileName.hashCode());

  207.         result = 31*result + lineNumber;

  208.         return result;

  209.     }

  210. 

  211.     private static final long serialVersionUID = 6992337162326171013L;

  212. }