libjava/java/lang/StackTraceElement.java

   1 /* StackTraceElement.java -- One function call or call stack element
   2    Copyright (C) 2001, 2002, 2004, 2005  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., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 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.4
  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    * Returns the name of the file, or null if unknown. This is usually
 116    * obtained from the <code>SourceFile</code> attribute of the class file
 117    * format, if present.
 118    *
 119    * @return the file name
 120    */
 121   public String getFileName()
 122   {
 123     return fileName;
 124   }
 125
 126   /**
 127    * Returns the line number in the file, or a negative number if unknown.
 128    * This is usually obtained from the <code>LineNumberTable</code> attribute
 129    * of the method in the class file format, if present.
 130    *
 131    * @return the line number
 132    */
 133   public int getLineNumber()
 134   {
 135     return lineNumber;
 136   }
 137
 138   /**
 139    * Returns the fully qualified class name, or null if unknown.
 140    *
 141    * @return the class name
 142    */
 143   public String getClassName()
 144   {
 145     return declaringClass;
 146   }
 147
 148   /**
 149    * Returns the method name in the class, or null if unknown. If the
 150    * execution point is in a constructor, the name is
 151    * <code>&lt;init&gt;</code>; if the execution point is in the class
 152    * initializer, the name is <code>&lt;clinit&gt;</code>.
 153    *
 154    * @return the method name
 155    */
 156   public String getMethodName()
 157   {
 158     return methodName;
 159   }
 160
 161   /**
 162    * Returns true if the method is native, or false if it is not or unknown.
 163    *
 164    * @return whether the method is native
 165    */
 166   public boolean isNativeMethod()
 167   {
 168     return isNative;
 169   }
 170
 171   /**
 172    * Returns a string representation of this stack trace element. The
 173    * returned String is implementation specific. This implementation
 174    * returns the following String: "[class][.][method]([file][:line])".
 175    * If the fully qualified class name or the method is unknown it is
 176    * omitted including the point seperator. If the source file name is
 177    * unknown it is replaced by "Unknown Source" if the method is not native
 178    * or by "Native Method" if the method is native. If the line number
 179    * is unknown it and the colon are omitted.
 180    *
 181    * @return a string representation of this execution point
 182    */
 183   public String toString()
 184   {
 185     StringBuffer sb = new StringBuffer();
 186     if (declaringClass != null)
 187       {
 188         sb.append(declaringClass);
 189         if (methodName != null)
 190           sb.append('.');
 191       }
 192     if (methodName != null)
 193       sb.append(methodName);
 194     sb.append(" (");
 195     if (fileName != null)
 196       sb.append(fileName);
 197     else
 198       sb.append(isNative ? "Native Method" : "Unknown Source");
 199     if (lineNumber >= 0)
 200       sb.append(':').append(lineNumber);
 201     sb.append(')');
 202     return sb.toString();
 203   }
 204
 205   /**
 206    * Returns true if the given object is also a StackTraceElement and all
 207    * attributes, except the native flag, are equal (either the same attribute
 208    * between the two elments are null, or both satisfy Object.equals).
 209    *
 210    * @param o the object to compare
 211    * @return true if the two are equal
 212    */
 213   public boolean equals(Object o)
 214   {
 215     if (! (o instanceof StackTraceElement))
 216       return false;
 217     StackTraceElement e = (StackTraceElement) o;
 218     return equals(fileName, e.fileName)
 219       && lineNumber == e.lineNumber
 220       && equals(declaringClass, e.declaringClass)
 221       && equals(methodName, e.methodName);
 222   }
 223
 224   /**
 225    * Returns the hashCode of this StackTraceElement. This implementation
 226    * computes the hashcode by xor-ing the hashcode of all attributes except
 227    * the native flag.
 228    *
 229    * @return the hashcode
 230    */
 231   public int hashCode()
 232   {
 233     return hashCode(fileName) ^ lineNumber ^ hashCode(declaringClass)
 234       ^ hashCode(methodName);
 235   }
 236
 237   /**
 238    * Compare two objects according to Collection semantics.
 239    *
 240    * @param o1 the first object
 241    * @param o2 the second object
 242    * @return o1 == null ? o2 == null : o1.equals(o2)
 243    */
 244   private static boolean equals(Object o1, Object o2)
 245   {
 246     return o1 == null ? o2 == null : o1.equals(o2);
 247   }
 248
 249   /**
 250    * Hash an object according to Collection semantics.
 251    *
 252    * @param o the object to hash
 253    * @return o1 == null ? 0 : o1.hashCode()
 254    */
 255   private static int hashCode(Object o)
 256   {
 257     return o == null ? 0 : o.hashCode();
 258   }
 259 }