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 }
|