alma.acs.logging.RepeatGuard Class Reference

List of all members.

Public Types
enum	Logic { AND, OR, TIMER, COUNTER }
Public Member Functions
	RepeatGuard (long interval, TimeUnit timeUnit, int maxRepetitions, Logic logic)
	RepeatGuard (long interval, TimeUnit timeUnit, int maxRepetitions)
synchronized boolean	check ()
synchronized boolean	checkAndIncrement ()
void	reset (long interval, TimeUnit timeUnit, int maxRepetitions)
synchronized void	reset (long interval, TimeUnit timeUnit, int maxRepetitions, Logic logic)
synchronized void	reset ()
synchronized void	increment ()
synchronized int	counter ()
synchronized int	counterAtLastExecution ()

---

Detailed Description

This class can be used to reduce the repeated execution of any kind of code, by keeping track of the number of intended executions and the time passed since the last actual execution, and comparing these against configured values (see details below).

A reduction of the number of executions can be useful if that code is resource intensive (e.g. DB access, remote calls, logging) or has other unwanted side effects if executed too often (e.g. annoying the user with too frequent error or confirmation dialogues). Of course this only makes sense if the nature of the problem allows skipping some of these executions.

This class is so general that it does not actually execute any code; it simply keeps track of counters and timer. It can be used directly to manage decisions about skipping or executing some code. For example, the application can instantiate a RepeatGuard with the timer set to one second. Then whenever the repetitive action would be called, the application first calls check(); for every timer interval, only the first call to check() will return true, while the subsequent calls will return false, and the application should skip the repeated block of code. Alternatively this class can be extended or wrapped to become easier to use for specific purposes. Then typically the code to be executed (e.g. logging a message) becomes part of the specialized repeat guard class, as in RepeatGuardLogger.

The concept of repeat guards in ACS is discussed at http://almasw.hq.eso.org/almasw/bin/view/ACS/LoggingRepetitionControl

Repetitions can be reduced using

1. the number of times that code execution should be skipped before the code can be executed again
2. a timer which allows only one execution per time interval, no matter how many execution attempts have been made in the meantime,
3. OR combination of the above: either enough attempts were made or enough time has passed, whatever happens first
4. AND combination: enough skipped execution attempts, and enough time passed.

see also the Logic enum.

---

Member Enumeration Documentation

enum alma::acs::logging::RepeatGuard::Logic

Enumerator:

AND
OR
TIMER
COUNTER

---

Constructor & Destructor Documentation

alma.acs.logging.RepeatGuard.RepeatGuard	(	long	interval,
		TimeUnit	timeUnit,
		int	maxRepetitions,
		Logic	logic
	)

Constructor.

Parameters:

	interval	Time interval (in timeUnit units).
	timeUnit	Time unit of interval parameter.
	maxRepetitions	Maximum number of repetitions.
	logic	Evaluation logic for interval and maxRepetitions. The logic will be "reduced" automatically if interval or maxRepetitions have a value <= 0, so as to be based only on the other positive value.

Exceptions:

IllegalArgumentException

if maxRepetitions <= 0 && interval <= 0

References alma.acs.logging.RepeatGuard.reset().

alma.acs.logging.RepeatGuard.RepeatGuard	(	long	interval,
		TimeUnit	timeUnit,
		int	maxRepetitions
	)

Constructor, convenience for the above, using Logic.OR evaluation method if both interval and maxRepetitions are positive values, otherwise {.TIMER} or {.COUNTER} to make sure that only the respective parameter with a positive value gets used.

Parameters:

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

Exceptions:

IllegalArgumentException

if maxRepetitions <= 0 && interval <= 0

---

Member Function Documentation

synchronized boolean alma.acs.logging.RepeatGuard.check

(

)

This method checks if the guarded activity is due for execution, or if it should be skipped instead.

For the first call, it always returns true. Later it returns true if the last call to check()was longer ago than the interval given in the constructor or in the reset methods, and/or if the internal counter has been incremented more than maxRepetitions by calls to increment() or checkAndIncrement().

Returns:

true if guarded activity should be run, false if it should be skipped.

References alma.acs.logging.RepeatGuard.counter(), and alma.acs.logging.RepeatGuard.counterAtLastExecution().

Referenced by alma.acs.logging.MultipleRepeatGuard.check(), and alma.acs.logging.RepeatGuard.checkAndIncrement().

synchronized boolean alma.acs.logging.RepeatGuard.checkAndIncrement

(

)

Increments the counter and checks (see check()).

Returns:

true if OK, false if should be guarded

See also:

check()

References alma.acs.logging.RepeatGuard.check(), and alma.acs.logging.RepeatGuard.counter().

Referenced by alma.acs.logging.MultipleRepeatGuard.checkAndIncrement(), alma.acs.logging.RepeatGuardLogger.isLoggingEnabled(), alma.acs.logging.RepeatGuardLogger.log(), alma.acs.nc.refactored.NCSubscriber.push_structured_event(), and alma.acs.nc.Consumer.push_structured_event().

synchronized int alma.acs.logging.RepeatGuard.counter

(

)

Get current counter value.

Returns:

current counter value.

Referenced by alma.acs.logging.RepeatGuard.check(), alma.acs.logging.RepeatGuard.checkAndIncrement(), alma.acs.logging.RepeatGuard.increment(), and alma.acs.logging.RepeatGuard.reset().

synchronized int alma.acs.logging.RepeatGuard.counterAtLastExecution

(

)

Gets the value of the counter that it had when the check() or checkAndIncrement() method returned true the last time, which corresponds to the number of times the activity was skipped before it got executed.

Calling this method does not make sense if only timer logic was used (no counters configured nor incremented)

Referenced by alma.acs.logging.RepeatGuard.check(), and alma.acs.logging.RepeatGuard.reset().

synchronized void alma.acs.logging.RepeatGuard.increment

(

)

Increase counter value.

References alma.acs.logging.RepeatGuard.counter().

Referenced by alma.acs.logging.MultipleRepeatGuard.increment().

synchronized void alma.acs.logging.RepeatGuard.reset	(	long	interval,
		TimeUnit	timeUnit,
		int	maxRepetitions,
		Logic	logic
	)

Resets and reconfigures logic of guard.

Parameters:

	interval	Time interval (in timeUnit units).
	timeUnit	Time unit of interval parameter.
	maxRepetitions	Maximum number of skipped repetitions.
	logic	Evaluation logic for interval and maxRepetitions. The logic will be "reduced" automatically if interval or maxRepetitions have a value <= 0, so as to be based only on the other positive value.

Exceptions:

IllegalArgumentException

if maxRepetitions <= 0 && interval <= 0 or required arg == null

References alma.acs.logging.RepeatGuard.reset().

synchronized void alma.acs.logging.RepeatGuard.reset

(

)

Resets this guard without changing the configuration for timer, counter and logic.

References alma.acs.logging.RepeatGuard.counter(), and alma.acs.logging.RepeatGuard.counterAtLastExecution().

Referenced by alma.acs.logging.RepeatGuard.RepeatGuard(), and alma.acs.logging.RepeatGuard.reset().

void alma.acs.logging.RepeatGuard.reset	(	long	interval,
		TimeUnit	timeUnit,
		int	maxRepetitions
	)

Resets and reconfigures this guard using the given interval, maxRepetitions, and Logic.OR logic.

Parameters:

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

Exceptions:

IllegalArgumentException

if maxRepetitions <= 0 && interval <= 0

See also:

RepeatGuard(long, TimeUnit, int, Logic)

References alma.acs.logging.RepeatGuard.reset().

---

The documentation for this class was generated from the following file:

• RepeatGuard.java