Evaluating Software Design Patterns
— the "Gang of Four" patterns implemented in Java 6

dk.rode.thesis.meta.reflect
Class IdentifiedStackTraceElement

java.lang.Object
  extended by dk.rode.thesis.meta.reflect.IdentifiedStackTraceElement
Direct Known Subclasses:
CallerClass

public class IdentifiedStackTraceElement
extends Object

An identified stack trace element is used to identify a stack trace element representing the calling context.

The calling context can be:

  1. A static initialisation block (class);
  2. An initialisation block (instance);
  3. A constructor; or
  4. A method.
An identified stack trace element per default identifies the stack trace element corresponding to the context where an instance of this class was constructed. The element thus represents the immediate calling context, e.g. the static initialisation block, instance initialisation block, constructor, or method from where the constructor of this class was invoked. The identified element is stored in element, and the entire call-stack in stack. The zeroth element of the call-stack represents the top of the stack, corresponding to one of the constructors declared in this class or in a sub-class.

However, a stack offset can be specified at construction time to identify a stack trace element from anywhere within the call-stack (from the top of the stack), corresponding to a relative calling context. The field offset represents the stack offset used, relative to the top of the stack: zero = top of stack, 1 = second element, 2 = third element, etc.

All instances of this class are immutable. If an instance can be created, a stack trace element will have been identified.

Example: a class Foo defined in the Foo.java file:

 01  class Foo {
 02    // Static initialisation block...
 03    static { 
 04      System.out.print(new IdentifiedStackTraceElement().toString());
 05    }
 06
 07    // Instance initialisation block... 
 08    {
 09      System.out.print(new IdentifiedStackTraceElement().toString());
 10    }
 11  
 12    // Constructor... 
 13    public Foo() {
 14      System.out.print(new IdentifiedStackTraceElement().toString());
 15    }  
 16
 17    public void bar() {
 18      System.out.print(new IdentifiedStackTraceElement().toString());
 19      this.barbar();
 20    }
 21
 22    public void barbar() {
 23      System.out.print(new IdentifiedStackTraceElement(1).toString());
 24    }
 25  }
 
Line 4 generates the following output (the precise format of the output is dependent on the JVM):
   "Foo.<clinit>(Foo.java:4)"
 
Line 9 and 14 generates the following output, respectively:
   "Foo.<init>(Foo.java:9)"       and
   "Foo.<init>(Foo.java:14)"
 
Line 18 and 23 generate the same output (provided access through bar()), since a stack offset (1) is specified in barbar():
   "Foo.bar(Foo.java:18)"
 
Note, that a JVM is not required to supply stack traces!

Author:
Gunni Rode / rode.dk

Field Summary
 StackTraceElement element
          The identified stack trace element.
 int offset
          The offset of element from the top of the call-stack stored in stack.
protected  StackTraceElement[] stack
          The call-stack used to identify the stack trace element stored in element.
protected  Throwable throwable
          The throwable that supplied the stack trace stored in stack.
 
Constructor Summary
IdentifiedStackTraceElement()
          No-arg constructor, which identifies the stack trace element corresponding to the calling context that invoked this constructor.
IdentifiedStackTraceElement(IdentifiedStackTraceElement element)
          Copy constructor, which identifies the same stack trace element as element in the same call-stack at the same offset.
IdentifiedStackTraceElement(IdentifiedStackTraceElement element, int offset)
          Constructor, which identifies the stack trace element at offset in the call-stack used by element.
IdentifiedStackTraceElement(int offset)
          Constructor, which identifies the stack trace element at offset from the top of the current call-stack.
IdentifiedStackTraceElement(Throwable throwable, int offset)
          Constructor, which identifies the stack trace element at offset from the top of the call-stack acquired via throwable; hence, this constructor need not be in the call-stack at all!
 
Method Summary
 boolean equals(Object object)
          Returns true if object has the same type as this element, same offset, same element, and same stack trace, otherwise false.
 StackTraceElement[] getStackTrace()
          Returns a copy of the call-stack used by this identified stack trace element.
 int hashCode()
          Returns the hash code of this identified stack trace element.
 void printStackTrace(Log out)
          Prints the call-stack to out with a severity level of error.
 String toString()
          Returns the string representation of this identified stack trace element.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

element

public final StackTraceElement element
The identified stack trace element.

It represents the point of origin where this instance was constructed from relative to the offset supplied at construction time.

Never null.


offset

public final int offset
The offset of element from the top of the call-stack stored in stack.

A value of zero represents the top of the call-stack.

Invariant: stack[offset] == element is always true.


stack

protected final StackTraceElement[] stack
The call-stack used to identify the stack trace element stored in element.

The zeroth element of this call-stack represents the top of the call-stack, corresponding to one of the constructors declared in this class or in a sub-class. Hence, offset zero = top of stack, 1 = second element, 2 = third element, etc.

Never null.


throwable

protected final Throwable throwable
The throwable that supplied the stack trace stored in stack.

Never null.

Constructor Detail

IdentifiedStackTraceElement

public IdentifiedStackTraceElement()
No-arg constructor, which identifies the stack trace element corresponding to the calling context that invoked this constructor.


IdentifiedStackTraceElement

public IdentifiedStackTraceElement(IdentifiedStackTraceElement element)
Copy constructor, which identifies the same stack trace element as element in the same call-stack at the same offset.

Parameters:
element - The identified stack trace element to copy; cannot be null.
Throws:
NullPointerException - If element is null.

IdentifiedStackTraceElement

IdentifiedStackTraceElement(IdentifiedStackTraceElement element,
                            int offset)
Constructor, which identifies the stack trace element at offset in the call-stack used by element.

The offset is used as is.

Parameters:
element - The identified stack trace element; cannot be null.
offset - The offset from the top of the call-stack; must be within bounds.
Throws:
NullPointerException - If element is null.
IndexOutOfBoundsException - If offset does not denote a valid stack element.

IdentifiedStackTraceElement

public IdentifiedStackTraceElement(int offset)
Constructor, which identifies the stack trace element at offset from the top of the current call-stack.

Invoking with a value of zero corresponds to invoking the default constructor, i.e., the identified stack trace element corresponds to the context that invoked this constructor; a value of one will resolve the context to the calling context of this constructor; and so forth.

Parameters:
offset - The offset from the top of the call-stack; must be within bounds.
Throws:
IndexOutOfBoundsException - If offset does not denote a valid stack element.

IdentifiedStackTraceElement

public IdentifiedStackTraceElement(Throwable throwable,
                                   int offset)
Constructor, which identifies the stack trace element at offset from the top of the call-stack acquired via throwable; hence, this constructor need not be in the call-stack at all!

Parameters:
throwable - The throwable to supply the call-stack; cannot be null.
offset - The offset from the top of the call-stack; must be within bounds.
Throws:
NullPointerException - If throwable is null.
IndexOutOfBoundsException - If offset does not denote a valid stack element.
Method Detail

equals

public boolean equals(Object object)
Returns true if object has the same type as this element, same offset, same element, and same stack trace, otherwise false.

Overrides:
equals in class Object
Parameters:
object - The object to test; can be null.
Returns:
True if equal, false if not.

getStackTrace

public StackTraceElement[] getStackTrace()
Returns a copy of the call-stack used by this identified stack trace element.

Returns:
A copy; never null.

hashCode

public int hashCode()
Returns the hash code of this identified stack trace element.

Overrides:
hashCode in class Object
Returns:
The hash code.

printStackTrace

public void printStackTrace(Log out)
Prints the call-stack to out with a severity level of error.

Parameters:
out - The log to use; cannot be null.
Throws:
NullPointerException - If out is null.

toString

public String toString()
Returns the string representation of this identified stack trace element.

The representation is that of the identified StackTraceElement.

Overrides:
toString in class Object
Returns:
The string representation; never null.

Gunni Rode / rode.dk

Feel free to use and/or modify the Java 6 source code developed for this thesis AT YOUR OWN RISK, but note that the source code comes WITHOUT ANY — and I do mean WITHOUT ANY — form of warranty WHAT SO EVER!

The original thesis and source code are available at rode.dk/thesis.