alma::acs::logging::RepeatGuardLogger Class Reference

Collaboration diagram for alma::acs::logging::RepeatGuardLogger:

Public Member Functions
	RepeatGuardLogger (long interval, TimeUnit timeUnit, int maxRepetitions)
	RepeatGuardLogger (AcsLogger logger, long interval, TimeUnit timeUnit, int maxRepetitions)
void	log (Logger logger, Level priority, String message)
void	logAndIncrement (Logger logger, Level priority, String message)
void	log (Level level, String message)
void	log (Level level, String message, Throwable thr)
boolean	isLoggingEnabled ()
Static Public Member Functions
static RepeatGuardLogger	createTimeBasedRepeatGuardLogger (AcsLogger logger, long interval, TimeUnit timeUnit)
static RepeatGuardLogger	createCounterBasedRepeatGuardLogger (AcsLogger logger, int maxRepetitions)
Protected Attributes
final RepeatGuard	guard
Private Attributes
AcsLogger	logger

Detailed Description

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.

Note about deprecated methods: In order to get correct file and line-of-code information in the logs, we need to configure the Logger so that it skips the methods of this class when going upward on the call stack to determine the real method name where the log originates from. The normal JDK Logger cannot do this, which is why we changed the API to use AcsLogger in ACS 8.0.0. It will be more performant to instruct the AcsLogger only once about which class's methods to skip on the call stack, which is why we now pass that logger in the constructor instead of passing it for every invocation of the log methods of this class.

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.

Constructor & Destructor Documentation

alma::acs::logging::RepeatGuardLogger::RepeatGuardLogger	(	long	interval,
		TimeUnit	timeUnit,
		int	maxRepetitions
	)			`[inline]`

Constructor.

Parameters:

	interval	Time interval (in `timeUnit` units).
	timeUnit	Time unit of `interval` parameter.
	maxRepetitions	Maximum number of skipped repetitions.

Deprecated:: since ACS 8.0.0. Use RepeatGuardLogger(AcsLogger, long, TimeUnit, int) instead.

References guard.

Referenced by createCounterBasedRepeatGuardLogger(), and createTimeBasedRepeatGuardLogger().

alma::acs::logging::RepeatGuardLogger::RepeatGuardLogger	(	AcsLogger	logger,
		long	interval,
		TimeUnit	timeUnit,
		int	maxRepetitions
	)			`[inline]`

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.

Exceptions:

IllegalArgumentException

if interval <= 0 && maxRepetitions <= 0

References alma::acs::logging::AcsLogger::addLoggerClass(), and guard.

Member Function Documentation

static RepeatGuardLogger alma::acs::logging::RepeatGuardLogger::createCounterBasedRepeatGuardLogger	(	AcsLogger	logger,
		int	maxRepetitions
	)			`[inline, static]`

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

Exceptions:

IllegalArgumentException

if maxRepetitions <= 0

See also:: RepeatGuardLogger(AcsLogger, long, TimeUnit, int)

References RepeatGuardLogger().

static RepeatGuardLogger alma::acs::logging::RepeatGuardLogger::createTimeBasedRepeatGuardLogger	(	AcsLogger	logger,
		long	interval,
		TimeUnit	timeUnit
	)			`[inline, static]`

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

Exceptions:

IllegalArgumentException

if interval <= 0

See also:: RepeatGuardLogger(AcsLogger, long, TimeUnit, int)

References RepeatGuardLogger().

boolean alma::acs::logging::RepeatGuardLogger::isLoggingEnabled ( ) [inline]

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

You want the repeat guard to skip or enable different log messages together (all or none).
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)

References alma::acs::logging::RepeatGuard::checkAndIncrement(), and guard.

void alma::acs::logging::RepeatGuardLogger::log	(	Level	level,
		String	message,
		Throwable	thr
	)			`[inline]`

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

See also:: Logger::log(Level, String, Throwable)

Since:: ACS 8.0.0

References alma::acs::logging::RepeatGuard::checkAndIncrement(), guard, alma::acs::logging::AcsLogger::log(), and logger.

void alma::acs::logging::RepeatGuardLogger::log	(	Level	level,
		String	message
	)			`[inline]`

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.)

Requires the logger to be set in the ctor RepeatGuardLogger(AcsLogger, long, TimeUnit, int) or in one of the static factory methods, which will become the only choice once the deprecated methods are removed.

See also:: Logger::log(Level, String)

Since:: ACS 8.0.0

References alma::acs::logging::RepeatGuard::checkAndIncrement(), guard, alma::acs::logging::AcsLogger::log(), and logger.

void alma::acs::logging::RepeatGuardLogger::log	(	Logger	logger,
		Level	priority,
		String	message
	)			`[inline]`

Logs a message without incrementing the repeat counter. This method is only useful if this repeat guard is based only on the timer but not the counter (i.e. if maxRepetitions <= 0), or if you want to cheat and log something without advancing the counter which does not really make sense as you could just as well use the logger directly.

Deprecated:: since ACS 8.0.0. Use log(Level, String) instead, or isLoggingEnabled() if you need to log a batch of messages together controlled by one repeat guard.

References alma::acs::logging::RepeatGuard::check(), and guard.

Referenced by alma::acs::logging::RepeatGuardLoggerTest::testRepeatGuardLogger().