alma.acs.logging

Class RepeatGuardLogger

java.lang.Object

alma.acs.logging.RepeatGuardLogger

public class RepeatGuardLogger
extends java.lang.Object

This class wraps a logger so that logging of records is skipped until a given number of logging attempts or given time has passed. It is based on RepeatGuard. Typically you want to create one RepeatGuardLogger for each guarded kind of log message (= logging line in your code). Only if you want to control the repetition of different kinds of log messages (at different places in your code) using the same counter and timer (which could mean that one kind of log may always be suppressed while another type may always be logged) then you should reuse one instance of this class for different lines of logging in your code.

There seems to be no real use case for passing different loggers to one repeat guard, even though this was described in the original design. Therefore we plan to remove #log(Logger, Level, String) and #logAndIncrement(Logger, Level, String) in the future. If you feel they are useful (because you have a case where the logger cannot or should not be passed in the constructor) then we can keep these methods as alternatives to the recommended passing of the logger in the constructor. Please report this to ACS.

Field Summary

Fields

Modifier and Type	Field and Description
protected RepeatGuard	guard

Constructor Summary

Constructors

Constructor and Description
RepeatGuardLogger(AcsLogger logger, long interval, java.util.concurrent.TimeUnit timeUnit, int maxRepetitions) Constructor for a time and counter based repeat guard logger.

Method Summary

Modifier and Type	Method and Description
static RepeatGuardLogger	createCounterBasedRepeatGuardLogger(AcsLogger logger, int maxRepetitions) Factory method for a repeat guard logger which only uses a counter of skipped logs, regardless of the time passed since the last log.
static RepeatGuardLogger	createTimeBasedRepeatGuardLogger(AcsLogger logger, long interval, java.util.concurrent.TimeUnit timeUnit) Factory method for a repeat guard logger which only uses a timer, regardless of the number of skipped logs.
boolean	isLoggingEnabled() Checks if the internal repeat guard allows a log.
void	log(java.util.logging.Level level, java.lang.String message) Logs the message at the given level, unless the internal RepeatGuard prevents this based on the timer and/or log record counter.
void	log(java.util.logging.Level level, java.lang.String message, java.lang.Throwable thr) Same as log(Level, String) but with additional Throwable to be logged.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

guard

protected final RepeatGuard guard

Constructor Detail

RepeatGuardLogger

public RepeatGuardLogger(AcsLogger logger,
                         long interval,
                         java.util.concurrent.TimeUnit timeUnit,
                         int maxRepetitions)

Constructor for a time and counter based repeat guard logger.

If only time or counter should apply, but not both together, it is better to use the factory methods createTimeBasedRepeatGuardLogger(AcsLogger, long, TimeUnit) or createCounterBasedRepeatGuardLogger(AcsLogger, int). However it is also possible to use negative values for the quantities that should not be considered.

Parameters:

logger - The logger to be used in

interval - Time interval (in timeUnit units).

timeUnit - Time unit of interval parameter.

maxRepetitions - Maximum number of skipped repetitions.

Throws:

java.lang.IllegalArgumentException - if interval <= 0 && maxRepetitions <= 0

Method Detail

createTimeBasedRepeatGuardLogger

public static RepeatGuardLogger createTimeBasedRepeatGuardLogger(AcsLogger logger,
                                                                 long interval,
                                                                 java.util.concurrent.TimeUnit timeUnit)

Factory method for a repeat guard logger which only uses a timer, regardless of the number of skipped logs.

Throws:

java.lang.IllegalArgumentException - if interval <= 0

See Also:

RepeatGuardLogger(AcsLogger, long, TimeUnit, int)

createCounterBasedRepeatGuardLogger

public static RepeatGuardLogger createCounterBasedRepeatGuardLogger(AcsLogger logger,
                                                                    int maxRepetitions)

Factory method for a repeat guard logger which only uses a counter of skipped logs, regardless of the time passed since the last log.

Throws:

java.lang.IllegalArgumentException - if maxRepetitions <= 0

See Also:

RepeatGuardLogger(AcsLogger, long, TimeUnit, int)

log

public void log(java.util.logging.Level level,
                java.lang.String message)

Logs the message at the given level, unless the internal RepeatGuard prevents this based on the timer and/or log record counter. If a log record counter is active, it will be advanced, which corresponds to RepeatGuard.checkAndIncrement(). (Note that following the same terminology as RepeatGuard, this method would have to be called logAndIncrement; it is simply called log though because here we don't support the variant of having a counter enabled without using it.)

Since:

ACS 8.0.0

See Also:

Logger.log(Level, String)

log

public void log(java.util.logging.Level level,
                java.lang.String message,
                java.lang.Throwable thr)

Same as log(Level, String) but with additional Throwable to be logged.

Since:

ACS 8.0.0

See Also:

Logger.log(Level, String, Throwable)

isLoggingEnabled

public boolean isLoggingEnabled()

Checks if the internal repeat guard allows a log. This method is an alternative to the various log methods to be used if

1. You want the repeat guard to skip or enable different log messages together (all or none).
2. You want to use specialized methods of the guarded Logger, such as Logger.log(java.util.logging.LogRecord), which are not exposed by this RepeatGuardLogger

In either of these cases, simply surround a call to the normal logger with an
if (isLoggingEnabled()) {myLogger.blabla}.

The internal log counter (if present) will be incremented the same way as for one call to, say, log(Level, String).

Note that you might be better off using RepeatGuard directly if this method is the only one you need from this RepeatGuardLogger. Using this method makes sense though for a mix of logs, some to be made via the RepeatGuardLogger.log methods, and others directly via the logger surrounded by a call to this isLoggingEnabled

Returns:

true if the counter/timer allows a log message (or a batch of log messages that must appear together)