001: /*
002: * Copyright 2000-2004 Sun Microsystems, Inc. All Rights Reserved.
003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004: *
005: * This code is free software; you can redistribute it and/or modify it
006: * under the terms of the GNU General Public License version 2 only, as
007: * published by the Free Software Foundation. Sun designates this
008: * particular file as subject to the "Classpath" exception as provided
009: * by Sun in the LICENSE file that accompanied this code.
010: *
011: * This code is distributed in the hope that it will be useful, but WITHOUT
012: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014: * version 2 for more details (a copy is included in the LICENSE file that
015: * accompanied this code).
016: *
017: * You should have received a copy of the GNU General Public License version
018: * 2 along with this work; if not, write to the Free Software Foundation,
019: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022: * CA 95054 USA or visit www.sun.com if you need additional information or
023: * have any questions.
024: */
025:
026: package java.lang;
027:
028: /**
029: * An element in a stack trace, as returned by {@link
030: * Throwable#getStackTrace()}. Each element represents a single stack frame.
031: * All stack frames except for the one at the top of the stack represent
032: * a method invocation. The frame at the top of the stack represents the
033: * execution point at which the stack trace was generated. Typically,
034: * this is the point at which the throwable corresponding to the stack trace
035: * was created.
036: *
037: * @since 1.4
038: * @author Josh Bloch
039: */
040: public final class StackTraceElement implements java.io.Serializable {
041: // Normally initialized by VM (public constructor added in 1.5)
042: private String declaringClass;
043: private String methodName;
044: private String fileName;
045: private int lineNumber;
046:
047: /**
048: * Creates a stack trace element representing the specified execution
049: * point.
050: *
051: * @param declaringClass the fully qualified name of the class containing
052: * the execution point represented by the stack trace element
053: * @param methodName the name of the method containing the execution point
054: * represented by the stack trace element
055: * @param fileName the name of the file containing the execution point
056: * represented by the stack trace element, or <tt>null</tt> if
057: * this information is unavailable
058: * @param lineNumber the line number of the source line containing the
059: * execution point represented by this stack trace element, or
060: * a negative number if this information is unavailable. A value
061: * of -2 indicates that the method containing the execution point
062: * is a native method
063: * @throws NullPointerException if <tt>declaringClass</tt> or
064: * <tt>methodName</tt> is null
065: * @since 1.5
066: */
067: public StackTraceElement(String declaringClass, String methodName,
068: String fileName, int lineNumber) {
069: if (declaringClass == null)
070: throw new NullPointerException("Declaring class is null");
071: if (methodName == null)
072: throw new NullPointerException("Method name is null");
073:
074: this .declaringClass = declaringClass;
075: this .methodName = methodName;
076: this .fileName = fileName;
077: this .lineNumber = lineNumber;
078: }
079:
080: /**
081: * Returns the name of the source file containing the execution point
082: * represented by this stack trace element. Generally, this corresponds
083: * to the <tt>SourceFile</tt> attribute of the relevant <tt>class</tt>
084: * file (as per <i>The Java Virtual Machine Specification</i>, Section
085: * 4.7.7). In some systems, the name may refer to some source code unit
086: * other than a file, such as an entry in source repository.
087: *
088: * @return the name of the file containing the execution point
089: * represented by this stack trace element, or <tt>null</tt> if
090: * this information is unavailable.
091: */
092: public String getFileName() {
093: return fileName;
094: }
095:
096: /**
097: * Returns the line number of the source line containing the execution
098: * point represented by this stack trace element. Generally, this is
099: * 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><init></tt> or
127: * <tt><clinit></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()
176: + "."
177: + methodName
178: + (isNativeMethod() ? "(Native Method)"
179: : (fileName != null && lineNumber >= 0 ? "("
180: + fileName + ":" + lineNumber + ")"
181: : (fileName != null ? "(" + fileName
182: + ")" : "(Unknown Source)")));
183: }
184:
185: /**
186: * Returns true if the specified object is another
187: * <tt>StackTraceElement</tt> instance representing the same execution
188: * point as this instance. Two stack trace elements <tt>a</tt> and
189: * <tt>b</tt> are equal if and only if:
190: * <pre>
191: * equals(a.getFileName(), b.getFileName()) &&
192: * a.getLineNumber() == b.getLineNumber()) &&
193: * equals(a.getClassName(), b.getClassName()) &&
194: * equals(a.getMethodName(), b.getMethodName())
195: * </pre>
196: * where <tt>equals</tt> is defined as:
197: * <pre>
198: * static boolean equals(Object a, Object b) {
199: * return a==b || (a != null && a.equals(b));
200: * }
201: * </pre>
202: *
203: * @param obj the object to be compared with this stack trace element.
204: * @return true if the specified object is another
205: * <tt>StackTraceElement</tt> instance representing the same
206: * execution point as this instance.
207: */
208: public boolean equals(Object obj) {
209: if (obj == this )
210: return true;
211: if (!(obj instanceof StackTraceElement))
212: return false;
213: StackTraceElement e = (StackTraceElement) obj;
214: return e.declaringClass.equals(declaringClass)
215: && e.lineNumber == lineNumber
216: && eq(methodName, e.methodName)
217: && eq(fileName, e.fileName);
218: }
219:
220: private static boolean eq(Object a, Object b) {
221: return a == b || (a != null && a.equals(b));
222: }
223:
224: /**
225: * Returns a hash code value for this stack trace element.
226: */
227: public int hashCode() {
228: int result = 31 * declaringClass.hashCode()
229: + methodName.hashCode();
230: result = 31 * result
231: + (fileName == null ? 0 : fileName.hashCode());
232: result = 31 * result + lineNumber;
233: return result;
234: }
235:
236: private static final long serialVersionUID = 6992337162326171013L;
237: }
| 