KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > lang > StackTraceElement


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 JavaDoc {
23     // Normally initialized by VM (public constructor added in 1.5)
24 private String JavaDoc declaringClass;
25     private String JavaDoc methodName;
26     private String JavaDoc 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 JavaDoc declaringClass, String JavaDoc methodName,
50                              String JavaDoc fileName, int lineNumber) {
51         if (declaringClass == null)
52             throw new NullPointerException JavaDoc("Declaring class is null");
53         if (methodName == null)
54             throw new NullPointerException JavaDoc("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 JavaDoc 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 JavaDoc 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>&lt;init&gt;</tt> or
109      * <tt>&lt;clinit&gt;</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 JavaDoc 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 JavaDoc 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 JavaDoc obj) {
188         if (obj==this)
189             return true;
190         if (!(obj instanceof StackTraceElement JavaDoc))
191             return false;
192         StackTraceElement JavaDoc e = (StackTraceElement JavaDoc)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 JavaDoc a, Object JavaDoc 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 }
213
Popular Tags