Package com.google.common.flogger.backend

Class Platform.LogCallerFinder

  • Enclosing class:
    Platform
    public abstract static class Platform.LogCallerFinder
extends Object
    API for determining the logging class and log statement sites, return from Platform.getCallerFinder(). This classes is immutable and thread safe.

    This functionality is not provided directly by the Platform API because doing so would require several additional levels to be added to the stack before the implementation was reached. This is problematic for Android which has only limited stack analysis. By allowing callers to resolve the implementation early and then call an instance directly (this is not an interface), we reduce the number of elements in the stack before the caller is found.

    Essential Implementation Restrictions

    Any implementation of this API MUST follow the rules listed below to avoid any risk of re-entrant code calling during logger initialization. Failure to do so risks creating complex, hard to debug, issues with Flogger configuration.
    1. Implementations MUST NOT attempt any logging in static methods or constructors.
    2. Implementations MUST NOT statically depend on any unknown code.
    3. Implementations MUST NOT depend on any unknown code in constructors.

    Note that logging and calling arbitrary unknown code (which might log) are permitted inside the instance methods of this API, since they are not called during platform initialization. The easiest way to achieve this is to simply avoid having any non-trivial static fields or any instance fields at all in the implementation.

    While this sounds onerous it's not difficult to achieve because this API is a singleton, and can delay any actual work until its methods are called. For example if any additional state is required in the implementation, it can be held via a "lazy holder" to defer initialization.

    • Constructor Detail

      • LogCallerFinder

        public LogCallerFinder()

    • Method Detail

      • findLoggingClass

        public abstract String findLoggingClass​(Class<? extends AbstractLogger<?>> loggerClass)
        Returns the name of the immediate caller of the given logger class. This is useful when determining the class name with which to create a logger backend.
        Parameters:
        loggerClass - the class containing the log() methods whose caller we need to find.
        Returns:
        the name of the class that called the specified logger.
        Throws:
        IllegalStateException - if there was no caller of the specified logged passed on the stack (which may occur if the logger class was invoked directly by JNI).

      • findLogSite

        public abstract LogSite findLogSite​(Class<?> loggerApi,
                                    int stackFramesToSkip)
        Returns a LogSite found from the current stack trace for the caller of the log() method on the given logging class.
        Parameters:
        loggerApi - the class containing the log() methods whose caller we need to find.
        stackFramesToSkip - the number of method calls which exist on the stack between the log() method and the point at which this method is invoked.
        Returns:
        A log site inferred from the stack, or LogSite.INVALID if no log site can be determined.