How to use net.digitalid.utility.logging.filter

/**
 * Returns a logging rule with the given threshold.
 */
@Pure
public static @Nonnull LoggingRule with(@Nonnull Level threshold) {
  return new LoggingRule(threshold, null, null, null);
}

/**
 * Returns a logging filter with the given threshold.
 */
@Pure
public static @Nonnull LevelBasedLoggingFilter with(@Nonnull Level threshold) {
  return new LevelBasedLoggingFilter(threshold);
}

/**
 * Initializes the logging filter.
 */
@PureWithSideEffects
@Initialize(target = LoggingFilter.class)
public static void initializeLoggingFilter() {
  final @Nonnull @Absolute File projectDirectory = new File("").getAbsoluteFile();
  final @Nonnull String callerPrefix = "net.digitalid." + projectDirectory.getParentFile().getName() + "." + projectDirectory.getName();
  LoggingFilter.filter.set(ConfigurationBasedLoggingFilter.with(Files.relativeToWorkingDirectory("config/TestingLogging.conf"), LoggingRule.with(Level.VERBOSE, callerPrefix + "."), LoggingRule.with(Level.INFORMATION)));
}

/**
 * Decodes the given line and returns the corresponding rule.
 * 
 * @throws IllegalArgumentException if a rule has an invalid level.
 */
@Pure
public static @Nonnull LoggingRule decode(@Nonnull String line) throws IllegalArgumentException {
  final @Nonnull @NonNullableElements String[] tokens = line.split(";", 4);
  final @Nonnull Level threshold = Level.valueOf(tokens[0].trim().toUpperCase());
  final @Nullable String callerPrefix = getNonEmpty(tokens, 1);
  final @Nullable String threadPrefix = getNonEmpty(tokens, 2);
  final @Nullable String messageRegex = getNonEmpty(tokens, 3);
  return new LoggingRule(threshold, callerPrefix, threadPrefix, messageRegex);
}

protected ConfigurationBasedLoggingFilter(@Nonnull File file, @Nonnull @NonNullableElements LoggingRule... defaultRules) throws IllegalArgumentException {
  super(defaultRules);
  
  this.file = file;
  if (file.exists()) {
    reload();
  } else {
    Files.write(comments.combine(getRules().map(LoggingRule::encode)), file);
  }
}

/**
 * Logs the given message and throwable if the configured filter accepts them.
 * Each dollar sign in the message is replaced with the corresponding argument.
 */
@Impure
public static void log(@Nonnull Level level, @Nonnull CharSequence message, @Nullable Throwable throwable, @NonCaptured @Unmodified @Nonnull @NullableElements Object... arguments) {
  final @Nonnull LoggingFilter filter = LoggingFilter.filter.get();
  if (filter.isPotentiallyLogged(level)) {
    final @Nonnull String caller = Caller.get();
    final @Nonnull String thread = Thread.currentThread().getName();
    final @Nonnull String originalMessage = message.toString();
    final boolean addNoPeriod = originalMessage.endsWith(".") || originalMessage.endsWith(":") || originalMessage.endsWith("\n");
    final @Nonnull String formattedMessage = Strings.format(originalMessage, arguments) + (addNoPeriod ? "" : ".");
    if (filter.isLogged(level, caller, thread, formattedMessage, throwable)) { logger.get().log(level, caller, thread, formattedMessage, throwable); }
  }
}

/**
 * Returns a logging filter with the given configuration file and default rules.
 * 
 * @throws IllegalArgumentException if a rule has an invalid level.
 */
@Pure
public static @Nonnull ConfigurationBasedLoggingFilter with(@Nonnull File file, @Nonnull @NonNullableElements LoggingRule... defaultRules) throws IllegalArgumentException {
  return new ConfigurationBasedLoggingFilter(file, defaultRules);
}

@Pure
@Override
public boolean isLogged(@Nonnull Level level, @Nonnull String caller, @Nonnull String thread, @Nonnull String message, @Nullable Throwable throwable) {
  return rules.matchAny(rule -> rule.accepts(level, caller, thread, message));
}

/**
 * Returns a logging filter with the given rules.
 */
@Pure
public static @Nonnull RuleBasedLoggingFilter with(@Nonnull @NonNullableElements LoggingRule... rules) {
  return new RuleBasedLoggingFilter(rules);
}

@Pure
@Override
public boolean isPotentiallyLogged(@Nonnull Level level) {
  return rules.matchAny(rule -> level.getValue() >= rule.getThreshold().getValue());
}

/**
 * Reloads the logging rules from the configuration file.
 * 
 * @throws IllegalArgumentException if a rule has an invalid level.
 */
@Impure
public void reload() throws IllegalArgumentException {
  setRules(Files.readNonCommentNonEmptyTrimmedLines(file).map(LoggingRule::decode).evaluate());
}

/**
 * Initializes the output file of the logger with the given name.
 */
@Impure
public static void initialize(@Nonnull String name) throws IllegalArgumentException, FileNotFoundException {
  Caller.index.set(6);
  Version.string.set("0.7");
  LoggingFilter.filter.set(ConfigurationBasedLoggingFilter.with(Files.relativeToWorkingDirectory("config/" + name + ".conf"), LoggingRule.with(Level.INFORMATION)));
  Logger.logger.set(FileLogger.with(Files.relativeToWorkingDirectory("target/processor-logs/" + name + ".log")));
}

/**
 * Returns a logging rule with the given threshold, caller prefix, thread prefix and message regex.
 */
@Pure
public static @Nonnull LoggingRule with(@Nonnull Level threshold, @Nullable String callerPrefix, @Nullable String threadPrefix, @Nullable String messageRegex) {
  return new LoggingRule(threshold, callerPrefix, threadPrefix, messageRegex);
}

/**
 * Initializes the logging filter with a configuration-based logging filter.
 * 
 * @throws IllegalArgumentException if a rule has an invalid level.
 */
@PureWithSideEffects
@Initialize(target = LoggingFilter.class, dependencies = Files.class)
public static void initializeLoggingFilter() throws IllegalArgumentException {
  if (LoggingFilter.filter.get() instanceof LevelBasedLoggingFilter) {
    LoggingFilter.filter.set(ConfigurationBasedLoggingFilter.with(Files.relativeToConfigurationDirectory("configs/logging.conf"), LoggingRule.with(Level.INFORMATION)));
    Log.verbose("Replaced the default level-based logging filter with a configuration-based logging filter.");
  } else {
    Log.verbose("Did not replace the non-default logging filter with a configuration-based logging filter.");
  }
}

/**
 * Returns a logging rule with the given threshold and caller prefix.
 */
@Pure
public static @Nonnull LoggingRule with(@Nonnull Level threshold, @Nullable String callerPrefix) {
  return new LoggingRule(threshold, callerPrefix, null, null);
}

/**
 * Returns a logging rule with the given threshold, caller prefix and thread prefix.
 */
@Pure
public static @Nonnull LoggingRule with(@Nonnull Level threshold, @Nullable String callerPrefix, @Nullable String threadPrefix) {
  return new LoggingRule(threshold, callerPrefix, threadPrefix, null);
}