Package io.spine.logging.flogger.backend

Class Platform

  • public abstract class Platform
extends Object
    Platform abstraction layer required to allow fluent logger implementations to work on differing Java platforms (such as Android or GWT). The Platform class is responsible for providing any platform specific APIs, including the mechanism by which logging backends are created.

    To enable an additional logging platform implementation, the class name should be added to the list of available platforms before the default platform (which must always be at the end). Platform implementation classes must subclass Platform and have a public, no-argument constructor. Platform instances are created on first-use of a fluent logger and platform implementors must take care to avoid cycles during initialization and re-entrant behaviour.

    See Also:
    Original Java code of Google Flogger

    • Constructor Detail

      • Platform

        public Platform()

    • Method Detail

      • getCurrentRecursionDepth

        public static int getCurrentRecursionDepth()
        Returns the current depth of recursion for logging in the current thread.

        This method is intended only for use by logging backends or the core Flogger library and only needs to be called by code which is invoking user code which itself might trigger reentrant logging.

        • A value of 1 means that this thread is currently in a normal log statement. This is the expected state and the caller should behave normally.
        • A value greater than 1 means that this thread is currently performing reentrant logging, and the caller may choose to change behaviour depending on the value if there is a risk that reentrant logging is being caused by the caller's code.
        • A value of zero means that this thread is not currently logging (though since this method should only be called as part of a logging library, this is expected to never happen). It should be ignored.

        When the core Flogger library detects the depth exceeding a preset threshold, it may start to modify its behaviour to attempt to mitigate the risk of unbounded reentrant logging. For example, some or all metadata may be removed from log sites, since processing user provided metadata may itself trigger reentrant logging.

      • getCallerFinder

        public static Platform.LogCallerFinder getCallerFinder()
        Returns the API for obtaining caller information about loggers and logging classes.

      • getBackend

        public static LoggerBackend getBackend​(String className)
        Returns a logger backend of the given class name for use by a Fluent Logger. Note that the returned backend need not be unique; one backend could be used by multiple loggers. The given class name must be in the normal dot-separated form (e.g. "com.example.Foo$Bar") rather than the internal binary format (e.g. "com/example/Foo$Bar").
        Parameters:
        className - the fully-qualified name of the Java class to which the logger is associated. The logger name is derived from this string in a platform specific way.

      • getContextDataProvider

        public static ContextDataProvider getContextDataProvider()
        Returns the singleton ContextDataProvider from which a ScopedLoggingContext can be obtained. Platform implementations are required to always provide the same instance here, since this can be cached by callers.

      • shouldForceLogging

        public static boolean shouldForceLogging​(String loggerName,
                                         Level level,
                                         boolean isEnabled)
        Returns whether the given logger should have logging forced at the specified level. When logging is forced for a log statement it will be emitted regardless or the normal log level configuration of the logger and ignoring any rate limiting or other filtering.

        This method is intended to be invoked unconditionally from a fluent logger's at(Level) method to permit overriding of default logging behavior.

        Parameters:
        loggerName - the fully qualified logger name (e.g. "com.example.SomeClass")
        level - the level of the log statement being invoked
        isEnabled - whether the logger is enabled at the given level (i.e. the result of calling isLoggable() on the backend instance)

      • getInjectedTags

        public static Tags getInjectedTags()
        Returns Tags from with the current context to be injected into log statements.

      • getInjectedMetadata

        public static Metadata getInjectedMetadata()
        Returns Metadata from with the current context to be injected into log statements.

      • getCurrentTimeNanos

        public static long getCurrentTimeNanos()
        Returns the current time from the epoch (00:00 1st Jan, 1970) with nanosecond granularity. This is a non-negative signed 64-bit value, which must be in the range 0 <= timestamp < 2^63, ensuring that the difference between any two timestamps will always yield a valid signed value.

        Warning: Not all Platform implementations will be able to deliver nanosecond precision and code should avoid relying on any implied precision.

      • getCurrentTimeNanosImpl

        protected long getCurrentTimeNanosImpl()

      • getConfigInfo

        public static String getConfigInfo()
        Returns a human readable string describing the platform and its configuration. This should contain everything a human would need to see to check that the Platform was configured as expected. It should contain the platform name along with any configurable elements (e.g. plugin services) and their settings. It is recommended (though not required) that this string is formatted with one piece of configuration per line in a tabular format, such as: 
        
 platform: <human readable name>
 formatter: com.example.logging.FormatterPlugin
 formatter.foo: <"foo" settings for the formatter plugin>
 formatter.bar: <"bar" settings for the formatter plugin>
        It is not required that this string be machine parseable (though it should be stable).

      • getConfigInfoImpl

        protected abstract String getConfigInfoImpl()