Package com.clumd.projects.java_custom_logging.logging

Class LogRoot

java.lang.Object
com.clumd.projects.java_custom_logging.logging.LogRoot
public final class LogRoot extends Object
This class is a de-facto root for all Extended Logging functionality.

All methods are Static and this class cannot be instantiated.

The INIT method MUST be called before this LogRoot can be used to generate Loggers

  • Field Details

  • Method Details

    • init

      public static LogRoot init(@NonNull @NonNull String discardablePackageIdEndingInDot, @NonNull @NonNull String loggingRootID, String systemID)
      Used to initialise the Log Root with some base parameters.
      Parameters:
      discardablePackageIdEndingInDot - The package name of the application using the logger, which must end in a 'dot' as this is how the package structure in Java is defined. For example 'com.x.y.z.' what this will allow is that any logger messages coming from WITHIN your defined package, will be able to truncate the often unnecessary base package definition in each log message.
      loggingRootID - The ID which we should use as a core prefix, comparable to an 'App reference' for every Log Message created in this application.
      systemID - The ID of the system running this instance of the program using this logger API.
      Returns:
      A LogRoot instance, which can then be enhanced with instances of Log Handlers.

    • init

      public static LogRoot init(@NonNull @NonNull String discardablePackageIdEndingInDot, @NonNull @NonNull String loggingRootID)
      As init(String, String, String), but with systemID defaulting to null, which will use some programmatic ID, involving system hostname.

    • withHandlers

      public void withHandlers(Collection<CustomLogHandler> wantedLogHandlers)
      Used to enhance the LogRoot with instances of Log Handler which will be used to capture all LogRecords written during the runtime of the application using this API.
      Parameters:
      wantedLogHandlers - The Collection of handlers which we want to be given each message in this app.

    • basicConsoleHandler

      public static CustomLogHandler basicConsoleHandler(boolean useSpacerLines)
      Create a basic instance of a Console Handler with various defaults set.
      Parameters:
      useSpacerLines - Used to decide whether we want to add additional spacer lines to messages in the console.
      Returns:
      The instantiated ConsoleHandler instance.

    • basicDenseConsoleHandler

      public static CustomLogHandler basicDenseConsoleHandler()
      Creates a sparse no-fluff Console Handler with dense message output.
      Returns:
      The instantiated ConsoleHandler instance.

    • basicFileHandler

      public static CustomLogHandler basicFileHandler(@NonNull @NonNull String atDir) throws IOException
      Create a basic instance of a File Handler with various defaults set.
      Parameters:
      atDir - The Directory where the system should write its log files to.
      Returns:
      The instantiated FileHandler instance.
      Throws:
      IOException - Thrown if there was a problem creating or writing to the directory/file you intended.

    • basicDenseFileHandler

      public static CustomLogHandler basicDenseFileHandler(@NonNull @NonNull String atDir) throws IOException
      Creates a sparse no-fluff File Handler with dense message output and other defaults set.
      Parameters:
      atDir - The Directory where the system should write its log files to.
      Returns:
      The instantiated FileHandler instance.
      Throws:
      IOException - Thrown if there was a problem creating or writing to the directory/file you intended.

    • basicFileHandler

      public static CustomLogHandler basicFileHandler() throws IOException
      As basicFileHandler(String) but the directory is defaulted to the CURRENT WORKING DIRECTORY WHEN THE JAVA PROCESS WAS STARTED.
      Returns:
      The instantiated FileHandler instance.
      Throws:
      IOException - Thrown if there was a problem creating or writing to the directory/file you intended.

    • basicDenseFileHandler

      public static CustomLogHandler basicDenseFileHandler() throws IOException
      As basicDenseFileHandler(String) but the directory is defaulted to the CURRENT WORKING DIRECTORY WHEN THE JAVA PROCESS WAS STARTED.
      Returns:
      The instantiated FileHandler instance.
      Throws:
      IOException - Thrown if there was a problem creating or writing to the directory/file you intended.

    • createLogger

      public static ExtendedLogger createLogger(@NonNull @NonNull Class<?> forClass)
      Used to create a Logger instance by referencing the Class you want the logger for.
      Parameters:
      forClass - The Class you would like the logger to be created for.
      Returns:
      The instantiated ExtendedLogger

    • createLogger

      public static ExtendedLogger createLogger(@NonNull @NonNull Class<?> forClass, @NonNull @NonNull Set<String> bakedInTags)
      Used to create a Logger instance by referencing the Class you want the logger for. This version of construction also takes a Set of Strings, which will be added to the tags section on every log message executed by the returned logger. This approach is targeted for things like distributed trace IDs.
      Parameters:
      forClass - The Class you would like the logger to be created for.
      bakedInTags - A collection of tags which should be applied to every single log message that the Logger returned by this method will generate.
      Returns:
      The instantiated ExtendedLogger

    • createLogger

      public static ExtendedLogger createLogger(@NonNull @NonNull String loggerIdentifier)
      Used to create a Logger instance by a string name.

      If there is some sort of hierarchy in these loggers, such as going into various sub-packages, then these should be dot-separated.

      Parameters:
      loggerIdentifier - The String name of the class you would like the Logger of.
      Returns:
      The instantiated ExtendedLogger

    • createLogger

      public static ExtendedLogger createLogger(@NonNull @NonNull String loggerIdentifier, @NonNull @NonNull Set<String> bakedInTags)
      Used to create a Logger instance by a string name.

      If there is some sort of hierarchy in these loggers, such as going into various sub-packages, then these should be dot-separated.

      This version of construction also takes a Set of Strings, which will be added to the tags section on every log message executed by the returned logger. This approach is targeted for things like distributed trace IDs

      Parameters:
      loggerIdentifier - The String name of the class you would like the Logger of.
      bakedInTags - A collection of tags which should be applied to every single log message that the Logger returned by this method will generate.
      Returns:
      The instantiated ExtendedLogger

    • buildLogName

      protected static String buildLogName(String prefix, @NonNull @NonNull String loggerIdentifier)

    • createLogger

      public static ExtendedLogger createLogger(String prefix, String loggerIdentifier)
      Used to create a Logger instance by a string name, with a custom prefix.

      This may be useful for classes who require Multiple instances of the same logger, but for slightly different purposes.

      If there is some sort of hierarchy in these loggers, such as going into various sub-packages, then these should be dot-separated on the loggerIdentifier, NOT on the prefix.

      Parameters:
      prefix - The name of the prefix for this Logger instance.
      loggerIdentifier - The String name of the class you would like the Logger of.
      Returns:
      The instantiated ExtendedLogger

    • createLogger

      public static ExtendedLogger createLogger(String prefix, String loggerIdentifier, Set<String> bakedInTags)
      Used to create a Logger instance by a string name, with a custom prefix.

      This may be useful for classes who require Multiple instances of the same logger, but for slightly different purposes.

      If there is some sort of hierarchy in these loggers, such as going into various sub-packages, then these should be dot-separated on the loggerIdentifier, NOT on the prefix.

      This version of construction also takes a Set of Strings, which will be added to the tags section on every log message executed by the returned logger. This approach is targeted for things like distributed trace IDs

      Parameters:
      prefix - The name of the prefix for this Logger instance.
      loggerIdentifier - The String name of the class you would like the Logger of.
      bakedInTags - Collection of tags which should be applied to every single log message that the Logger returned by this method will generate.
      Returns:
      The instantiated ExtendedLogger

    • setBranchLoggingLevel

      public static void setBranchLoggingLevel(@NonNull @NonNull CustomLevel selectedLevel, @NonNull @NonNull Logger viaLogger)
      Used to set the logging level of the indicated branch of package hierarchy.

      This will be SPECIFIC to loggers created within this API.

      Parameters:
      selectedLevel - The level you would like to set the indicated branch to.
      viaLogger - The Logger we should use to determine the Branch of logging hierarchy to update the log level to.

    • setBranchLoggingLevel

      public static void setBranchLoggingLevel(@NonNull @NonNull CustomLevel selectedLevel, @NonNull @NonNull String viaLogIdentifier)
      Used to set the logging level of the indicated branch of package hierarchy.

      This will be SPECIFIC to loggers created within this API.

      Parameters:
      selectedLevel - The level you would like to set the indicated branch to.
      viaLogIdentifier - The Logger reference we should use to determine the Branch of logging hierarchy to update the log level to.

    • setGlobalBranchLoggingLevel

      public static void setGlobalBranchLoggingLevel(@NonNull @NonNull CustomLevel selectedLevel, @NonNull @NonNull String viaLogIdentifier)
      Used to set the logging level of the indicated branch of package hierarchy.

      This operation can apply ACROSS ALL LOGGERS KNOWN TO THE JVM.

      Parameters:
      selectedLevel - The level you would like to set the indicated branch to.
      viaLogIdentifier - The Logger reference we should use to determine the Branch of logging hierarchy to update the log level to.

    • setBranchLoggingLevel

      public static void setBranchLoggingLevel(@NonNull @NonNull CustomLevel selectedLevel, String viaLogPrefix, @NonNull @NonNull String viaLogIdentifier)
      Used to set the logging level of the indicated branch of package hierarchy.

      This will be SPECIFIC to loggers created within this API.

      Parameters:
      selectedLevel - The level you would like to set the indicated branch to.
      viaLogPrefix - The specific prefix necessary to determine an exact Logger instance.
      viaLogIdentifier - The Logger reference we should use to determine the Branch of logging hierarchy to update the log level to.

    • setGlobalLoggingLevel

      public static void setGlobalLoggingLevel(@NonNull @NonNull CustomLevel selectedLevel)
      Set the log level across the entire JVM to the given Custom Level.

      Please note, CUSTOM log levels DO NOT necessarily overlap with the baked in JUL log levels.

      Parameters:
      selectedLevel - The LogLevel you would like to set across the whole application.

    • setApplicationGlobalLevel

      public static void setApplicationGlobalLevel(@NonNull @NonNull CustomLevel selectedLevel)
      Set the log level across every Logger created within this API to the given Custom Level, but do NOT touch loggers used by 3rd party dependencies.
      Parameters:
      selectedLevel - The LogLevel you would like to set for the indicated loggers.

    • updateThreadIdName

      public static void updateThreadIdName(long threadID, @NonNull @NonNull String threadName)