Source for java.lang.StackTraceElement

   1: /* StackTraceElement.java -- One function call or call stack element
   2:    Copyright (C) 2001, 2002, 2004, 2005, 2006  Free Software Foundation, Inc.
   3: 
   4: This file is part of GNU Classpath.
   5: 
   6: GNU Classpath is free software; you can redistribute it and/or modify
   7: it under the terms of the GNU General Public License as published by
   8: the Free Software Foundation; either version 2, or (at your option)
   9: any later version.
  10: 
  11: GNU Classpath is distributed in the hope that it will be useful, but
  12: WITHOUT ANY WARRANTY; without even the implied warranty of
  13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14: General Public License for more details.
  15: 
  16: You should have received a copy of the GNU General Public License
  17: along with GNU Classpath; see the file COPYING.  If not, write to the
  18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19: 02110-1301 USA.
  20: 
  21: Linking this library statically or dynamically with other modules is
  22: making a combined work based on this library.  Thus, the terms and
  23: conditions of the GNU General Public License cover the whole
  24: combination.
  25: 
  26: As a special exception, the copyright holders of this library give you
  27: permission to link this library with independent modules to produce an
  28: executable, regardless of the license terms of these independent
  29: modules, and to copy and distribute the resulting executable under
  30: terms of your choice, provided that you also meet, for each linked
  31: independent module, the terms and conditions of the license of that
  32: module.  An independent module is a module which is not derived from
  33: or based on this library.  If you modify this library, you may extend
  34: this exception to your version of the library, but you are not
  35: obligated to do so.  If you do not wish to do so, delete this
  36: exception statement from your version. */
  37: 
  38: 
  39: package java.lang;
  40: 
  41: import java.io.Serializable;
  42: 
  43: /**
  44:  * One function call or stack trace element. Gives information about
  45:  * the execution point such as the source file name, the line number,
  46:  * the fully qualified class name, the method name and whether this method
  47:  * is native, if this information is known.
  48:  *
  49:  * @author Mark Wielaard (mark@klomp.org)
  50:  * @author Eric Blake (ebb9@email.byu.edu)
  51:  * @since 1.4
  52:  * @status updated to 1.5
  53:  */
  54: public final class StackTraceElement implements Serializable
  55: {
  56:   /**
  57:    * Compatible with JDK 1.4+.
  58:    */
  59:   private static final long serialVersionUID = 6992337162326171013L;
  60: 
  61:   /**
  62:    * The name of the file, null if unknown.
  63:    *
  64:    * @serial the source code filename, if known
  65:    */
  66:   private final String fileName;
  67: 
  68:   /**
  69:    * The line number in the file, negative if unknown.
  70:    *
  71:    * @serial the source code line number, if known
  72:    */
  73:   private final int lineNumber;
  74: 
  75:   /**
  76:    * The fully qualified class name, null if unknown.
  77:    *
  78:    * @serial the enclosing class, if known
  79:    */
  80:   private final String declaringClass;
  81: 
  82:   /**
  83:    * The method name in the class, null if unknown.
  84:    *
  85:    * @serial the enclosing method, if known
  86:    */
  87:   private final String methodName;
  88: 
  89:   /** Whether the method is native. */
  90:   private final transient boolean isNative;
  91: 
  92:   /**
  93:    * A package local constructor for the StackTraceElement class, to be
  94:    * called by the Virtual Machine as part of Throwable.fillInStackTrace.
  95:    * There are no public constructors defined for this class. Creation
  96:    * of new elements is implementation specific.
  97:    *
  98:    * @param fileName the name of the file, null if unknown
  99:    * @param lineNumber the line in the file, negative if unknown
 100:    * @param className the fully qualified name of the class, null if unknown
 101:    * @param methodName the name of the method, null if unknown
 102:    * @param isNative true if native, false otherwise
 103:    */
 104:   StackTraceElement(String fileName, int lineNumber, String className,
 105:                     String methodName, boolean isNative)
 106:   {
 107:     this.fileName = fileName;
 108:     this.lineNumber = lineNumber;
 109:     this.declaringClass = className;
 110:     this.methodName = methodName;
 111:     this.isNative = isNative;
 112:   }
 113: 
 114:   /**
 115:    * Create a new StackTraceElement representing a given source location.
 116:    *
 117:    * @param className the fully qualified name of the class
 118:    * @param methodName the name of the method
 119:    * @param fileName the name of the file, null if unknown
 120:    * @param lineNumber the line in the file, negative if unknown, or -2
 121:    * if this method is native
 122:    * 
 123:    * @since 1.5
 124:    */
 125:   public StackTraceElement(String className, String methodName, String fileName,
 126:                            int lineNumber)
 127:   {
 128:     this(fileName, lineNumber, className, methodName, lineNumber == -2);
 129:     // The public constructor doesn't allow certain values to be null.
 130:     if (className == null || methodName == null)
 131:       throw new NullPointerException("invalid argument to constructor");
 132:   }
 133: 
 134:   /**
 135:    * Returns the name of the file, or null if unknown. This is usually
 136:    * obtained from the <code>SourceFile</code> attribute of the class file
 137:    * format, if present.
 138:    *
 139:    * @return the file name
 140:    */
 141:   public String getFileName()
 142:   {
 143:     return fileName;
 144:   }
 145: 
 146:   /**
 147:    * Returns the line number in the file, or a negative number if unknown.
 148:    * This is usually obtained from the <code>LineNumberTable</code> attribute
 149:    * of the method in the class file format, if present.
 150:    *
 151:    * @return the line number
 152:    */
 153:   public int getLineNumber()
 154:   {
 155:     return lineNumber;
 156:   }
 157: 
 158:   /**
 159:    * Returns the fully qualified class name, or null if unknown.
 160:    *
 161:    * @return the class name
 162:    */
 163:   public String getClassName()
 164:   {
 165:     return declaringClass;
 166:   }
 167: 
 168:   /**
 169:    * Returns the method name in the class, or null if unknown. If the
 170:    * execution point is in a constructor, the name is
 171:    * <code>&lt;init&gt;</code>; if the execution point is in the class
 172:    * initializer, the name is <code>&lt;clinit&gt;</code>.
 173:    *
 174:    * @return the method name
 175:    */
 176:   public String getMethodName()
 177:   {
 178:     return methodName;
 179:   }
 180: 
 181:   /**
 182:    * Returns true if the method is native, or false if it is not or unknown.
 183:    *
 184:    * @return whether the method is native
 185:    */
 186:   public boolean isNativeMethod()
 187:   {
 188:     return isNative;
 189:   }
 190: 
 191:   /**
 192:    * Returns a string representation of this stack trace element. The
 193:    * returned String is implementation specific. This implementation
 194:    * returns the following String: "[class][.][method]([file][:line])".
 195:    * If the fully qualified class name or the method is unknown it is
 196:    * omitted including the point seperator. If the source file name is
 197:    * unknown it is replaced by "Unknown Source" if the method is not native
 198:    * or by "Native Method" if the method is native. If the line number
 199:    * is unknown it and the colon are omitted.
 200:    *
 201:    * @return a string representation of this execution point
 202:    */
 203:   public String toString()
 204:   {
 205:     StringBuffer sb = new StringBuffer();
 206:     if (declaringClass != null)
 207:       {
 208:         sb.append(declaringClass);
 209:         if (methodName != null)
 210:           sb.append('.');
 211:       }
 212:     if (methodName != null)
 213:       sb.append(methodName);
 214:     sb.append("(");
 215:     if (fileName != null)
 216:       sb.append(fileName);
 217:     else
 218:       sb.append(isNative ? "Native Method" : "Unknown Source");
 219:     if (lineNumber >= 0)
 220:       sb.append(':').append(lineNumber);
 221:     sb.append(')');
 222:     return sb.toString();
 223:   }
 224: 
 225:   /**
 226:    * Returns true if the given object is also a StackTraceElement and all
 227:    * attributes, except the native flag, are equal (either the same attribute
 228:    * between the two elments are null, or both satisfy Object.equals).
 229:    *
 230:    * @param o the object to compare
 231:    * @return true if the two are equal
 232:    */
 233:   public boolean equals(Object o)
 234:   {
 235:     if (! (o instanceof StackTraceElement))
 236:       return false;
 237:     StackTraceElement e = (StackTraceElement) o;
 238:     return equals(fileName, e.fileName)
 239:       && lineNumber == e.lineNumber
 240:       && equals(declaringClass, e.declaringClass)
 241:       && equals(methodName, e.methodName);
 242:   }
 243: 
 244:   /**
 245:    * Returns the hashCode of this StackTraceElement. This implementation
 246:    * computes the hashcode by xor-ing the hashcode of all attributes except
 247:    * the native flag.
 248:    *
 249:    * @return the hashcode
 250:    */
 251:   public int hashCode()
 252:   {
 253:     return hashCode(fileName) ^ lineNumber ^ hashCode(declaringClass)
 254:       ^ hashCode(methodName);
 255:   }
 256: 
 257:   /**
 258:    * Compare two objects according to Collection semantics.
 259:    *
 260:    * @param o1 the first object
 261:    * @param o2 the second object
 262:    * @return o1 == null ? o2 == null : o1.equals(o2)
 263:    */
 264:   private static boolean equals(Object o1, Object o2)
 265:   {
 266:     return o1 == null ? o2 == null : o1.equals(o2);
 267:   }
 268: 
 269:   /**
 270:    * Hash an object according to Collection semantics.
 271:    *
 272:    * @param o the object to hash
 273:    * @return o1 == null ? 0 : o1.hashCode()
 274:    */
 275:   private static int hashCode(Object o)
 276:   {
 277:     return o == null ? 0 : o.hashCode();
 278:   }
 279: }