001: /*
002: * @(#)StackTraceElement.java 1.13 06/10/10
003: *
004: * Copyright 1990-2006 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: * An element in a stack trace, as returned by {@link
031: * Throwable#getStackTrace()}. Each element represents a single stack frame.
032: * All stack frames except for the one at the top of the stack represent
033: * a method invocation. The frame at the top of the stack represents the
034: * the execution point at which the stack trace was generated. Typically,
035: * this is the point at which the throwable corresponding to the stack trace
036: * was created.
037: *
038: * @since 1.4
039: * @author Josh Bloch
040: */
041: public final class StackTraceElement implements java.io.Serializable {
042: // Initialized by VM
043: private String declaringClass;
044: private String methodName;
045: private String fileName;
046: private int lineNumber;
047:
048: private boolean isCompiled;
049: private String methodSignature;
050:
051: /**
052: * Prevent inappropriate instantiation. Only the VM creates these.
053: * It creates them "magically" without invoking this constructor.
054: */
055: private StackTraceElement() { /* assert false; */
056: }
057:
058: /**
059: * Returns the name of the source file containing the execution point
060: * represented by this stack trace element. Generally, this corresponds
061: * to the <tt>SourceFile</tt> attribute of the relevant <tt>class</tt>
062: * file (as per <i>The Java Virtual Machine Specification</i>, Section
063: * 4.7.7). In some systems, the name may refer to some source code unit
064: * other than a file, such as an entry in source repository.
065: *
066: * @return the name of the file containing the execution point
067: * represented by this stack trace element, or <tt>null</tt> if
068: * this information is unavailable.
069: */
070: public String getFileName() {
071: return fileName;
072: }
073:
074: /**
075: * Returns the line number of the source line containing the execution
076: * point represented by this stack trace element. Generally, this is
077: * derived from the <tt>LineNumberTable</tt> attribute of the relevant
078: * <tt>class</tt> file (as per <i>The Java Virtual Machine
079: * Specification</i>, Section 4.7.8).
080: *
081: * @return the line number of the source line containing the execution
082: * point represented by this stack trace element, or a negative
083: * number if this information is unavailable.
084: */
085: public int getLineNumber() {
086: return lineNumber;
087: }
088:
089: /**
090: * Returns the fully qualified name of the class containing the
091: * execution point represented by this stack trace element.
092: *
093: * @return the fully qualified name of the <tt>Class</tt> containing
094: * the execution point represented by this stack trace element.
095: */
096: public String getClassName() {
097: return declaringClass;
098: }
099:
100: /**
101: * Returns the name of the method containing the execution point
102: * represented by this stack trace element. If the execution point is
103: * contained in an instance or class initializer, this method will return
104: * the appropriate <i>special method name</i>, <tt><init></tt> or
105: * <tt><clinit></tt>, as per Section 3.9 of <i>The Java Virtual
106: * Machine Specification</i>.
107: *
108: * @return the name of the method containing the execution point
109: * represented by this stack trace element.
110: */
111: public String getMethodName() {
112: return methodName;
113: }
114:
115: /**
116: * Returns true if the method containing the execution point
117: * represented by this stack trace element is a native method.
118: *
119: * @return <tt>true</tt> if the method containing the execution point
120: * represented by this stack trace element is a native method.
121: */
122: public boolean isNativeMethod() {
123: return lineNumber == -2;
124: }
125:
126: /**
127: * Returns a string representation of this stack trace element. The
128: * format of this string depends on the implementation, but the following
129: * examples may be regarded as typical:
130: * <ul>
131: * <li>
132: * <tt>"MyClass.mash(MyClass.java:9)"</tt> - Here, <tt>"MyClass"</tt>
133: * is the <i>fully-qualified name</i> of the class containing the
134: * execution point represented by this stack trace element,
135: * <tt>"mash"</tt> is the name of the method containing the execution
136: * point, <tt>"MyClass.java"</tt> is the source file containing the
137: * execution point, and <tt>"9"</tt> is the line number of the source
138: * line containing the execution point.
139: * <li>
140: * <tt>"MyClass.mash(MyClass.java)"</tt> - As above, but the line
141: * number is unavailable.
142: * <li>
143: * <tt>"MyClass.mash(Unknown Source)"</tt> - As above, but neither
144: * the file name nor the line number are available.
145: * <li>
146: * <tt>"MyClass.mash(Native Method)"</tt> - As above, but neither
147: * the file name nor the line number are available, and the method
148: * containing the execution point is known to be a native method.
149: * </ul>
150: * @see Throwable#printStackTrace()
151: */
152: public String toString() {
153: return getClassName()
154: + "."
155: + methodName
156: + ((methodSignature == null) ? "" : methodSignature)
157: + ((isCompiled == true) ? "(Compiled Method)" : "")
158: + (isNativeMethod() ? "(Native Method)"
159: : (fileName != null && lineNumber >= 0 ? "("
160: + fileName + ":" + lineNumber + ")"
161: : (fileName != null ? "(" + fileName
162: + ")" : "(Unknown Source)")));
163: }
164:
165: /**
166: * Returns true if the specified object is another
167: * <tt>StackTraceElement</tt> instance representing the same execution
168: * point as this instance. Two stack trace elements <tt>a</tt> and
169: * <tt>b</tt> are equal if and only if:
170: * <pre>
171: * equals(a.getFileName(), b.getFileName()) &&
172: * a.getLineNumber() == b.getLineNumber()) &&
173: * equals(a.getClassName(), b.getClassName()) &&
174: * equals(a.getMethodName(), b.getMethodName())
175: * </pre>
176: * where <tt>equals</tt> is defined as:
177: * <pre>
178: * static boolean equals(Object a, Object b) {
179: * return a==b || (a != null && a.equals(b));
180: * }
181: * </pre>
182: *
183: * @param obj the object to be compared with this stack trace element.
184: * @return true if the specified object is another
185: * <tt>StackTraceElement</tt> instance representing the same
186: * execution point as this instance.
187: */
188: public boolean equals(Object obj) {
189: if (obj == this )
190: return true;
191: if (!(obj instanceof StackTraceElement))
192: return false;
193: StackTraceElement e = (StackTraceElement) obj;
194: return e.declaringClass.equals(declaringClass)
195: && e.lineNumber == lineNumber
196: && eq(methodName, e.methodName)
197: && eq(fileName, e.fileName);
198: }
199:
200: private static boolean eq(Object a, Object b) {
201: return a == b || (a != null && a.equals(b));
202: }
203:
204: /**
205: * Returns a hash code value for this stack trace element.
206: */
207: public int hashCode() {
208: int result = 31 * declaringClass.hashCode()
209: + methodName.hashCode();
210: result = 31 * result
211: + (fileName == null ? 0 : fileName.hashCode());
212: result = 31 * result + lineNumber;
213: return result;
214: }
215:
216: private static final long serialVersionUID = 6992337162326171013L;
217: }
|