Package io.spine.logging.flogger.context

Class ScopedLoggingContext.Builder

  • Enclosing class:
    ScopedLoggingContext
    public abstract static class ScopedLoggingContext.Builder
extends Object
    A fluent builder API for creating and installing new context scopes. This API should be used whenever the metadata to be added to a scope is known at the time the scope is created.

    This class is intended to be used only as part of a fluent statement, and retaining a reference to a builder instance for any length of time is not recommended.

    • Constructor Detail

      • Builder

        protected Builder()

    • Method Detail

      • withTags

        @CanIgnoreReturnValue
public final ScopedLoggingContext.Builder withTags​(Tags tags)
        Sets the tags to be used with the context. This method can be called at most once per builder.

      • withMetadata

        @CanIgnoreReturnValue
public final <T> ScopedLoggingContext.Builder withMetadata​(FloggerMetadataKey<T> key,
                                                           T value)
        Adds a single metadata key/value pair to the context. This method can be called multiple times on a builder.

      • withLogLevelMap

        @CanIgnoreReturnValue
public final ScopedLoggingContext.Builder withLogLevelMap​(LogLevelMap logLevelMap)
        Sets the log level map to be used with the context being built. This method can be called at most once per builder.

      • wrap

        public final Runnable wrap​(Runnable r)
        Wraps a runnable so it will execute within a new context based on the state of the builder. Note that each time this runnable is executed, a new context will be installed extending from the currently installed context at the time of execution.
        Throws:
        InvalidLoggingScopeStateException - if the context created during this method cannot be closed correctly (e.g. if a nested context has also been opened, but not closed).

      • wrap

        public final <R> Callable<R> wrap​(Callable<R> c)
        Wraps a callable so it will execute within a new context based on the state of the builder. Note that each time this runnable is executed, a new context will be installed extending from the currently installed context at the time of execution.
        Throws:
        InvalidLoggingScopeStateException - if the context created during this method cannot be closed correctly (e.g. if a nested context has also been opened, but not closed).

      • run

        public final void run​(Runnable r)
        Runs a runnable directly within a new context installed from this builder.

      • call

        @CanIgnoreReturnValue
public final <R> R call​(Callable<R> c)
                 throws Exception
        Calls a Callable directly within a new context installed from this builder.
        Throws:
        Exception

      • callUnchecked

        @CanIgnoreReturnValue
public final <R> R callUnchecked​(Callable<R> c)
        Calls a Callable directly within a new context installed from this builder, wrapping any checked exceptions with a RuntimeException.

      • install

        @MustBeClosed
public abstract ScopedLoggingContext.LoggingContextCloseable install()
        Installs a new context based on the state of the builder. The caller is required to invoke close() on the returned instances in the reverse order to which they were obtained. For JDK 1.7 and above, this is best achieved by using a try-with-resources construction in the calling code. 
        
 try (LoggingContextCloseable ctx = ScopedLoggingContext.getInstance()
     .newContext().withTags(Tags.of("my_tag", someValue).install()) {
   // Logging by code called from within this context will contain the additional metadata.
   logger.atInfo().log("Log message should contain tag value...");
 }

        To avoid the need to manage contexts manually, it is strongly recommended that the helper methods, such as wrap(Runnable) or run(Runnable) are used to simplify the handling of contexts. This method is intended primarily to be overridden by context implementations rather than being invoked as a normal part of context use.

        An implementation of scoped contexts must preserve any existing metadata when a context is opened, and restore the previous state when it terminates.

        Note that the returned ScopedLoggingContext.LoggingContextCloseable is not required to enforce the correct closure of nested contexts, and while it is permitted to throw a InvalidLoggingScopeStateException in the face of mismatched or invalid usage, it is not required.

      • getTags

        protected final @Nullable Tags getTags()
        Returns the configured tags, or null. This method may do work and results should be cached by context implementations.

      • getMetadata

        protected final @Nullable ContextMetadata getMetadata()
        Returns the configured context metadata, or null. This method may do work and results should be cached by context implementations.

      • getLogLevelMap

        protected final @Nullable LogLevelMap getLogLevelMap()
        Returns the configured log level map, or null. This method may do work and results should be cached by context implementations.