org.apache.logging.log4j.util

Class StackLocator

java.lang.Object

org.apache.logging.log4j.util.StackLocator

All Implemented Interfaces:

org.apache.logging.log4j.util.IStackLocator

public final class StackLocator
extends Object
implements org.apache.logging.log4j.util.IStackLocator

Consider this class private. Provides various methods to determine the caller class.

Background

This method, available only in the Oracle/Sun/OpenJDK implementations of the Java Virtual Machine, is a much more efficient mechanism for determining the Class of the caller of a particular method. When it is not available, a SecurityManager is the second-best option. When this is also not possible, the StackTraceElement[] returned by Throwable.getStackTrace() must be used, and its String class name converted to a Class using the slow Class.forName(java.lang.String) (which can add an extra microsecond or more for each invocation depending on the runtime ClassLoader hierarchy).

During Java 8 development, the sun.reflect.Reflection.getCallerClass(int) was removed from OpenJDK, and this change was back-ported to Java 7 in version 1.7.0_25 which changed the behavior of the call and caused it to be off by one stack frame. This turned out to be beneficial for the survival of this API as the change broke hundreds of libraries and frameworks relying on the API which brought much more attention to the intended API removal.

After much community backlash, the JDK team agreed to restore getCallerClass(int) and keep its existing behavior for the rest of Java 7. However, the method is deprecated in Java 8, and current Java 9 development has not addressed this API. Therefore, the functionality of this class cannot be relied upon for all future versions of Java. It does, however, work just fine in Sun JDK 1.6, OpenJDK 1.6, Oracle/OpenJDK 1.7, and Oracle/OpenJDK 1.8. Other Java environments may fall back to using Throwable.getStackTrace() which is significantly slower due to examination of every virtual frame of execution.

Method Summary

Modifier and Type	Method and Description
StackTraceElement	calcLocation(String fqcnOfLogger)
Class<?>	getCallerClass(Class<?> anchor)
Class<?>	getCallerClass(Class<?> sentinelClass, Predicate<Class<?>> callerPredicate)
Class<?>	getCallerClass(int depth)
Class<?>	getCallerClass(String fqcn, String pkg)
Stack<Class<?>>	getCurrentStackTrace()
static StackLocator	getInstance()
StackTraceElement	getStackTraceElement(int depth)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getInstance

public static StackLocator getInstance()

getCallerClass

public Class<?> getCallerClass(Class<?> sentinelClass,
                               Predicate<Class<?>> callerPredicate)

Specified by:

getCallerClass in interface org.apache.logging.log4j.util.IStackLocator

getCallerClass

public Class<?> getCallerClass(int depth)

Specified by:

getCallerClass in interface org.apache.logging.log4j.util.IStackLocator

getCallerClass

public Class<?> getCallerClass(String fqcn,
                               String pkg)

Specified by:

getCallerClass in interface org.apache.logging.log4j.util.IStackLocator

getCallerClass

public Class<?> getCallerClass(Class<?> anchor)

Specified by:

getCallerClass in interface org.apache.logging.log4j.util.IStackLocator

getCurrentStackTrace

public Stack<Class<?>> getCurrentStackTrace()

Specified by:

getCurrentStackTrace in interface org.apache.logging.log4j.util.IStackLocator

calcLocation

public StackTraceElement calcLocation(String fqcnOfLogger)

Specified by:

calcLocation in interface org.apache.logging.log4j.util.IStackLocator

getStackTraceElement

public StackTraceElement getStackTraceElement(int depth)

Specified by:

getStackTraceElement in interface org.apache.logging.log4j.util.IStackLocator