1 /*
   2  * Copyright (c) 2000, 2004, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   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 /**
  29  * An element in a stack trace, as returned by {@link
  30  * Throwable#getStackTrace()}.  Each element represents a single stack frame.
  31  * All stack frames except for the one at the top of the stack represent
  32  * a method invocation.  The frame at the top of the stack represents the
  33  * execution point at which the stack trace was generated.  Typically,
  34  * this is the point at which the throwable corresponding to the stack trace
  35  * was created.
  36  *
  37  * @since  1.4
  38  * @author Josh Bloch
  39  */
  40 public final class StackTraceElement implements java.io.Serializable {
  41     // Normally initialized by VM (public constructor added in 1.5)
  42     private String declaringClass;
  43     private String methodName;
  44     private String fileName;
  45     private int    lineNumber;
  46 
  47     /**
  48      * Creates a stack trace element representing the specified execution
  49      * point.
  50      *
  51      * @param declaringClass the fully qualified name of the class containing
  52      *        the execution point represented by the stack trace element
  53      * @param methodName the name of the method containing the execution point
  54      *        represented by the stack trace element
  55      * @param fileName the name of the file containing the execution point
  56      *         represented by the stack trace element, or <tt>null</tt> if
  57      *         this information is unavailable
  58      * @param lineNumber the line number of the source line containing the
  59      *         execution point represented by this stack trace element, or
  60      *         a negative number if this information is unavailable. A value
  61      *         of -2 indicates that the method containing the execution point
  62      *         is a native method
  63      * @throws NullPointerException if <tt>declaringClass</tt> or
  64      *         <tt>methodName</tt> is null
  65      * @since 1.5
  66      */
  67     public StackTraceElement(String declaringClass, String methodName,
  68                              String fileName, int lineNumber) {
  69         if (declaringClass == null)
  70             throw new NullPointerException("Declaring class is null");
  71         if (methodName == null)
  72             throw new NullPointerException("Method name is null");
  73 
  74         this.declaringClass = declaringClass;
  75         this.methodName     = methodName;
  76         this.fileName       = fileName;
  77         this.lineNumber     = lineNumber;
  78     }
  79 
  80     /**
  81      * Returns the name of the source file containing the execution point
  82      * represented by this stack trace element.  Generally, this corresponds
  83      * to the <tt>SourceFile</tt> attribute of the relevant <tt>class</tt>
  84      * file (as per <i>The Java Virtual Machine Specification</i>, Section
  85      * 4.7.7).  In some systems, the name may refer to some source code unit
  86      * other than a file, such as an entry in source repository.
  87      *
  88      * @return the name of the file containing the execution point
  89      *         represented by this stack trace element, or <tt>null</tt> if
  90      *         this information is unavailable.
  91      */
  92     public String getFileName() {
  93         return fileName;
  94     }
  95 
  96     /**
  97      * Returns the line number of the source line containing the execution
  98      * point represented by this stack trace element.  Generally, this is
  99      * derived from the <tt>LineNumberTable</tt> attribute of the relevant
 100      * <tt>class</tt> file (as per <i>The Java Virtual Machine
 101      * Specification</i>, Section 4.7.8).
 102      *
 103      * @return the line number of the source line containing the execution
 104      *         point represented by this stack trace element, or a negative
 105      *         number if this information is unavailable.
 106      */
 107     public int getLineNumber() {
 108         return lineNumber;
 109     }
 110 
 111     /**
 112      * Returns the fully qualified name of the class containing the
 113      * execution point represented by this stack trace element.
 114      *
 115      * @return the fully qualified name of the <tt>Class</tt> containing
 116      *         the execution point represented by this stack trace element.
 117      */
 118     public String getClassName() {
 119         return declaringClass;
 120     }
 121 
 122     /**
 123      * Returns the name of the method containing the execution point
 124      * represented by this stack trace element.  If the execution point is
 125      * contained in an instance or class initializer, this method will return
 126      * the appropriate <i>special method name</i>, <tt>&lt;init&gt;</tt> or
 127      * <tt>&lt;clinit&gt;</tt>, as per Section 3.9 of <i>The Java Virtual
 128      * Machine Specification</i>.
 129      *
 130      * @return the name of the method containing the execution point
 131      *         represented by this stack trace element.
 132      */
 133     public String getMethodName() {
 134         return methodName;
 135     }
 136 
 137     /**
 138      * Returns true if the method containing the execution point
 139      * represented by this stack trace element is a native method.
 140      *
 141      * @return <tt>true</tt> if the method containing the execution point
 142      *         represented by this stack trace element is a native method.
 143      */
 144     public boolean isNativeMethod() {
 145         return lineNumber == -2;
 146     }
 147 
 148     /**
 149      * Returns a string representation of this stack trace element.  The
 150      * format of this string depends on the implementation, but the following
 151      * examples may be regarded as typical:
 152      * <ul>
 153      * <li>
 154      *   <tt>"MyClass.mash(MyClass.java:9)"</tt> - Here, <tt>"MyClass"</tt>
 155      *   is the <i>fully-qualified name</i> of the class containing the
 156      *   execution point represented by this stack trace element,
 157      *   <tt>"mash"</tt> is the name of the method containing the execution
 158      *   point, <tt>"MyClass.java"</tt> is the source file containing the
 159      *   execution point, and <tt>"9"</tt> is the line number of the source
 160      *   line containing the execution point.
 161      * <li>
 162      *   <tt>"MyClass.mash(MyClass.java)"</tt> - As above, but the line
 163      *   number is unavailable.
 164      * <li>
 165      *   <tt>"MyClass.mash(Unknown Source)"</tt> - As above, but neither
 166      *   the file name nor the line  number are available.
 167      * <li>
 168      *   <tt>"MyClass.mash(Native Method)"</tt> - As above, but neither
 169      *   the file name nor the line  number are available, and the method
 170      *   containing the execution point is known to be a native method.
 171      * </ul>
 172      * @see    Throwable#printStackTrace()
 173      */
 174     public String toString() {
 175         return getClassName() + "." + methodName +
 176             (isNativeMethod() ? "(Native Method)" :
 177              (fileName != null && lineNumber >= 0 ?
 178               "(" + fileName + ":" + lineNumber + ")" :
 179               (fileName != null ?  "("+fileName+")" : "(Unknown Source)")));
 180     }
 181 
 182     /**
 183      * Returns true if the specified object is another
 184      * <tt>StackTraceElement</tt> instance representing the same execution
 185      * point as this instance.  Two stack trace elements <tt>a</tt> and
 186      * <tt>b</tt> are equal if and only if:
 187      * <pre>
 188      *     equals(a.getFileName(), b.getFileName()) &&
 189      *     a.getLineNumber() == b.getLineNumber()) &&
 190      *     equals(a.getClassName(), b.getClassName()) &&
 191      *     equals(a.getMethodName(), b.getMethodName())
 192      * </pre>
 193      * where <tt>equals</tt> is defined as:
 194      * <pre>
 195      *     static boolean equals(Object a, Object b) {
 196      *         return a==b || (a != null && a.equals(b));
 197      *     }
 198      * </pre>
 199      *
 200      * @param  obj the object to be compared with this stack trace element.
 201      * @return true if the specified object is another
 202      *         <tt>StackTraceElement</tt> instance representing the same
 203      *         execution point as this instance.
 204      */
 205     public boolean equals(Object obj) {
 206         if (obj==this)
 207             return true;
 208         if (!(obj instanceof StackTraceElement))
 209             return false;
 210         StackTraceElement e = (StackTraceElement)obj;
 211         return e.declaringClass.equals(declaringClass) && e.lineNumber == lineNumber
 212             && eq(methodName, e.methodName) && eq(fileName, e.fileName);
 213     }
 214 
 215     private static boolean eq(Object a, Object b) {
 216         return a==b || (a != null && a.equals(b));
 217     }
 218 
 219     /**
 220      * Returns a hash code value for this stack trace element.
 221      */
 222     public int hashCode() {
 223         int result = 31*declaringClass.hashCode() + methodName.hashCode();
 224         result = 31*result + (fileName == null ?   0 : fileName.hashCode());
 225         result = 31*result + lineNumber;
 226         return result;
 227     }
 228 
 229     private static final long serialVersionUID = 6992337162326171013L;
 230 }