org.jasig.portal.lang
Class StackTrace

java.lang.Object
  extended by org.jasig.portal.lang.StackTrace

public final class StackTrace
extends java.lang.Object

The StackTrace object represents a single stack frame of information. The entire set of stack frames is represented as an array of StackTrace object.

Note: The stack frame information is not always available because some JVMs strip some or all the required information.

Version:
"$Revision: 1.3.4.1 $"
Author:
Jan Nielsen

Nested Class Summary
private static class StackTrace.ParseState
          The ParseState class holds the current parsing state.
 
Field Summary
private static int DEFAULT_STACK_TRACE_ARRAY_SIZE
          Default size of the stack trace array buffer.
private  java.lang.String mClassName
          Holder for the class name.
private  java.lang.String mFileName
          Holder for the source file name.
private  int mLineNumber
          Holder for the line number.
private  java.lang.String mMethodName
          Holder for the method name.
private static int NATIVE_METHOD
          Moniker for native method.
private static int PRIME
          Prime number used to calculate hash code.
 
Constructor Summary
private StackTrace(java.lang.String className, java.lang.String methodName, java.lang.String fileName, int lineNumber)
          Hidden constructor for the StackTrace object.
 
Method Summary
private static StackTrace convertElement(java.lang.Object element)
          Converts a J2SDK 1.4 StackTraceElement object to a StackTrace object.
(package private) static StackTrace[] convertStackTrace(java.lang.Object[] stackTrace)
          Converts a JDK 1.4 stack trace to this object.
private static boolean eq(java.lang.Object a, java.lang.Object b)
          Returns true if the two objects are equal.
 boolean equals(java.lang.Object obj)
          Returns true if the specified object is another StackTrace instance representing the same execution point as this instance.
 java.lang.String getClassName()
          Returns the name of the class.
 java.lang.String getFileName()
          Returns the name of the source file.
 int getLineNumber()
          Returns the line number in the source file.
 java.lang.String getMethodName()
          Returns the name of the method.
static StackTrace[] getStackTrace()
          Returns the stack trace elements of the client.
static StackTrace getStackTrace(int index)
          Returns the specified stack trace element if it exists.
static StackTrace[] getStackTrace(java.lang.Throwable throwable)
          Returns all StackTraces in an array of the specified throwable.
(package private) static StackTrace[] getStackTrace(java.lang.Throwable throwable, java.lang.String stackTrace)
          Returns all StackTraces in an array.
 int hashCode()
          Returns a hash code value for this stack trace element.
 boolean isNativeMethod()
          Returns true if method is implemented natively.
private static StackTrace parseStackTrace(StackTrace.ParseState state)
          Parse the first class name from the specified stack trace starting at the specified index.
private static java.lang.Object[] parseStackTrace(java.lang.String stackTrace)
          Parses a stack trace into individual stack frames.
private static StackTrace[] parseStackTrace(java.lang.Throwable throwable, java.lang.String stackTrace)
          Returns an array of StackTrace objects representing the Throwable argument.
 java.lang.String toString()
          Returns a representation of the stack frame element.
static java.lang.String toString(StackTrace[] elements)
          Returns a string representation of the stack trace elements.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

DEFAULT_STACK_TRACE_ARRAY_SIZE

private static final int DEFAULT_STACK_TRACE_ARRAY_SIZE
Default size of the stack trace array buffer.


NATIVE_METHOD

private static final int NATIVE_METHOD
Moniker for native method.

See Also:
Constant Field Values

PRIME

private static final int PRIME
Prime number used to calculate hash code.

See Also:
Constant Field Values

mFileName

private java.lang.String mFileName
Holder for the source file name.


mClassName

private java.lang.String mClassName
Holder for the class name.


mMethodName

private java.lang.String mMethodName
Holder for the method name.


mLineNumber

private int mLineNumber
Holder for the line number. The value (-2) is used to denote a native method.

Constructor Detail

StackTrace

private StackTrace(java.lang.String className,
                   java.lang.String methodName,
                   java.lang.String fileName,
                   int lineNumber)
Hidden constructor for the StackTrace object.

Parameters:
className - class name in the stack frame
methodName - method name in the stack frame
fileName - file name in the stack frame
lineNumber - line number in the stack frame
Method Detail

getFileName

public final java.lang.String getFileName()
Returns the name of the source file. If the parser failed to find the source file name the value "Unknown" will be returned.

Returns:
name of the source file

getClassName

public final java.lang.String getClassName()
Returns the name of the class. The parser should always be able to identify the calling class.

Returns:
name of the class

getMethodName

public final java.lang.String getMethodName()
Returns the name of the method. The parser should alwas be able to identify the calling method name.

Returns:
name of the method

getLineNumber

public final int getLineNumber()
Returns the line number in the source file. If the parser is unable to determine the line number the value -1 will be returned. If the parser determines the method is a native, a -2 is returned.

Returns:
source code line number, or -1 or -2

isNativeMethod

public final boolean isNativeMethod()
Returns true if method is implemented natively.

Returns:
true is native method; otherwise false

getStackTrace

public static final StackTrace[] getStackTrace(java.lang.Throwable throwable)
Returns all StackTraces in an array of the specified throwable.

Parameters:
throwable - throwable being parsed
Returns:
array of StackTraces
Throws:
java.lang.NullPointerException - if throwable is null
java.lang.NullPointerException - if stackTrace is null
java.lang.IllegalArgumentException - if stackTrace is an empty string

getStackTrace

static final StackTrace[] getStackTrace(java.lang.Throwable throwable,
                                        java.lang.String stackTrace)
Returns all StackTraces in an array. This method is used by the Chained* concrete classes to avoid a circular dependency. The throwable, and its string output must both be specified. Both are required because the throwable could be a com.sct.pipeline.lang.ChainedException which would result in a circular dependency if a printStackTrace was used in this method to retrieve the trace information. Invoke this method in the following fashion:
    StringWriter stringWriter = new StringWriter();

    PrintWriter printWriter = new PrintWriter(
        stringWriter
        );

    Throwable t = new Throwable();

    t.printStackTrace(
        printWriter
        );

    printWriter.close();

    StackTrace[] frames = getStackTraceElements(
        t,
        stringWriter.toString()
        );
 

Parameters:
throwable - throwable being parsed
stackTrace - string output of throwable.printStackTrace
Returns:
array of StackTraces
Throws:
java.lang.NullPointerException - if throwable is null
java.lang.NullPointerException - if stackTrace is null
java.lang.IllegalArgumentException - if stackTrace is an empty string

getStackTrace

public static final StackTrace[] getStackTrace()
Returns the stack trace elements of the client. The array of stack trace elements start with the client's invoking frame in the zeroth element.

Returns:
array of stack trace elements of the client

getStackTrace

public static final StackTrace getStackTrace(int index)
Returns the specified stack trace element if it exists. If an invalid, either too large or too small, index is specified null is returned.

Parameters:
index - index of the stack trace element to return
Returns:
stack trace element at the index or null

convertStackTrace

static final StackTrace[] convertStackTrace(java.lang.Object[] stackTrace)
Converts a JDK 1.4 stack trace to this object.

Parameters:
stackTrace - array of JDK 1.4 stack trace objects
Returns:
array of StackTrace objects

convertElement

private static final StackTrace convertElement(java.lang.Object element)
Converts a J2SDK 1.4 StackTraceElement object to a StackTrace object.

Parameters:
element - StackTraceElement object
Returns:
corresponding StackTrace object

parseStackTrace

private static final StackTrace[] parseStackTrace(java.lang.Throwable throwable,
                                                  java.lang.String stackTrace)
Returns an array of StackTrace objects representing the Throwable argument.

Parameters:
throwable -
stackTrace -
Returns:
array of StackTrace objects

parseStackTrace

private static final java.lang.Object[] parseStackTrace(java.lang.String stackTrace)
Parses a stack trace into individual stack frames.

Parameters:
stackTrace - stack trace to parse
Returns:
array of stack trace objects

toString

public final java.lang.String toString()
Returns a representation of the stack frame element. The format of the information may vary but the following examples are typical:

Overrides:
toString in class java.lang.Object
Returns:
string presentation of the stack frame.

toString

public static final java.lang.String toString(StackTrace[] elements)
Returns a string representation of the stack trace elements.

Parameters:
elements - stack trace elements to stringify
Returns:
string representation of the stack trace array

equals

public boolean equals(java.lang.Object obj)
Returns true if the specified object is another StackTrace instance representing the same execution point as this instance. Two stack trace elements a and b are equal if and only if:

     equals(a.getFileName(), b.getFileName()) &&
     a.getLineNumber() == b.getLineNumber()) &&
     equals(a.getClassName(), b.getClassName()) &&
     equals(a.getMethodName(), b.getMethodName())
 
where equals is defined as:

     static boolean equals(Object a, Object b) {
         return a==b || (a != null && a.equals(b));
     }
 

Overrides:
equals in class java.lang.Object
Parameters:
obj - the object to be compared with this stack trace element
Returns:
true if the specified object is another StackTrace instance representing the same execution point as this instance; otherwise false

eq

private static final boolean eq(java.lang.Object a,
                                java.lang.Object b)
Returns true if the two objects are equal. Equality is defined as either object identity or if a.equals(b) if a is not null.

Parameters:
a - left hand side argument
b - right hand side argument
Returns:
true if the two are equal; otherwise false

hashCode

public int hashCode()
Returns a hash code value for this stack trace element.

Overrides:
hashCode in class java.lang.Object
Returns:
hash code value

parseStackTrace

private static final StackTrace parseStackTrace(StackTrace.ParseState state)
Parse the first class name from the specified stack trace starting at the specified index.

Parameters:
state - parsing state
Returns:
parsed stack trace element