de.ipcon.tools.progress

Class ProgressHandler

java.lang.Object

de.ipcon.tools.progress.ProgressHandler

Direct Known Subclasses:

ProgressHandlerWithTotal

public class ProgressHandler
extends java.lang.Object

Class that encapsulates progress notification handling.

This class provides functionality for tracking progress and logging progress updates. It supports scenarios where progress tracking and logging are needed during tasks such as batch processing or iterative operations.

FIXME: Currently, this class is unrelated to GUI progress handling classes. Consider merging functionality in the future.

Example usage with message to a Logger:

 ph = ProgressHandler(300, 500, 600)
 loop ...
    -- Handle an entry
    ph.tickAndProgressToLog(log)
    end
 

Example usage with custom progress display:

 ph = ProgressHandler(300, 500, 600)
 loop ...
    -- Handle an entry
    if ph.tick() then
       say 'Handled 'ph.getCountHandled()' entries; running time 'L10n.formatTimespan(ph.getRunningTime() * 1000, 'HH:mm:ss')'...'
    end
 

Constructor Summary

Constructors

Constructor and Description
ProgressHandler() Constructs a new ProgressHandler with the given parameters for update interval, rounding, maximum update delay, log level, and a default description of the elements being processed.
ProgressHandler(int _updateInterval)
ProgressHandler(int _updateInterval, int _roundTo)
ProgressHandler(int _updateInterval, int _roundTo, int _maxUpdateDelay)
ProgressHandler(int _updateInterval, int _roundTo, int _maxUpdateDelay, org.apache.log4j.Level _logLevel)
ProgressHandler(int _updateInterval, int _roundTo, int _maxUpdateDelay, org.apache.log4j.Level _logLevel, java.lang.String _defaultThingsDesc)
ProgressHandler(int _updateInterval, int _roundTo, int _maxUpdateDelay, org.apache.log4j.Level _logLevel, java.lang.String _defaultThingsDesc, org.apache.log4j.Logger _defaultLogger)
ProgressHandler(int _updateInterval, int _roundTo, int _maxUpdateDelay, org.apache.log4j.Level _logLevel, java.lang.String _defaultThingsDesc, org.apache.log4j.Logger _defaultLogger, java.lang.String _defaultLogPrefix)
ProgressHandler(java.lang.String _defaultThingsDesc, org.apache.log4j.Logger _defaultLogger) Initializes a `ProgressHandler` instance with a default description of the elements being handled, using default values for update interval (15 seconds), roundTo (100 elements), maxUpdateInterval (20 seconds) and logLevel (Level.INFO).
ProgressHandler(java.lang.String _defaultThingsDesc, org.apache.log4j.Logger _defaultLogger, java.lang.String _defaultLogPrefix)

Method Summary

Modifier and Type	Method and Description
void	finalResultToLog() Convenience method that logs a standard final result message to the given Logger with Level INFO.
void	finalResultToLog(boolean evenWhenNoPreviousOutput)
void	finalResultToLog(org.apache.log4j.Logger log)
void	finalResultToLog(org.apache.log4j.Logger log, boolean evenWhenNoPreviousOutput) Logs a final result message to the specified Logger instance with Level INFO.
void	finalResultToLog(org.apache.log4j.Logger log, java.lang.String thingsDesc)
void	finalResultToLog(org.apache.log4j.Logger log, java.lang.String thingsDesc, java.lang.String logPrefix)
void	finalResultToLog(org.apache.log4j.Logger log, java.lang.String thingsDesc, java.lang.String logPrefix, boolean evenWhenNoPreviousOutput)
long	getCountHandled() Returns the current count handled.
org.apache.log4j.Logger	getDefaultLogger()
java.lang.String	getDefaultLogPrefix()
java.lang.String	getDefaultThingsDesc()
org.apache.log4j.Level	getLogLevel() Returns the current log level.
java.lang.String	getMessage(java.lang.String thingsDesc) Returns a standard progress message (FIXME in english only) with all the info from the current state of this ProgressHandler.
java.lang.String	getMessage(java.lang.String thingsDesc, boolean forFinalResult)
java.lang.String	getMessage(java.lang.String thingsDesc, boolean forFinalResult, java.lang.String logPrefix)
long	getRunningTime()
java.util.Date	getStartedAt()
boolean	isDone()
void	printFinalResult() Convenience method that outputs a standard final result message (from getMessage()) to the given PrintStream.
void	printFinalResult(java.io.PrintStream ps)
void	printFinalResult(java.io.PrintStream ps, java.lang.String thingsDesc)
void	printFinalResult(java.io.PrintStream ps, java.lang.String thingsDesc, java.lang.String printPrefix)
void	printFinalResult(java.io.PrintStream ps, java.lang.String thingsDesc, java.lang.String printPrefix, boolean evenWhenNoPreviousOutput)
boolean	printProgress() Convenience method that outputs a standard message (from getMessage()) to the given PrintStream when tick() says to do so.
boolean	printProgress(java.io.PrintStream ps)
boolean	printProgress(java.io.PrintStream ps, java.lang.String thingsDesc)
boolean	printProgress(java.io.PrintStream ps, java.lang.String thingsDesc, java.lang.String printPrefix)
boolean	progressToLog() Convenience method that outputs a standard message (from getMessage()) to the given Logger (Level is current LogLevel) when tick() says to do so.
boolean	progressToLog(org.apache.log4j.Logger log)
boolean	progressToLog(org.apache.log4j.Logger log, java.lang.String thingsDesc)
boolean	progressToLog(org.apache.log4j.Logger log, java.lang.String thingsDesc, java.lang.String logPrefix)
void	setCountHandled(long l) Updates count handled to the passed value.
void	setDefaultLogger(org.apache.log4j.Logger $2)
void	setDefaultLogPrefix(java.lang.String $3)
void	setDefaultThingsDesc(java.lang.String $1)
void	setLogLevel(org.apache.log4j.Level l) Sets the log level to the passed Level.
boolean	tick() Must be called for every handled element.
boolean	tick(boolean countUp)
boolean	tickAndPrintProgress() Convenience method that does a tick() and outputs a standard message (from getMessage()) to the given PrintStream when tick() says to do so.
boolean	tickAndPrintProgress(java.io.PrintStream ps)
boolean	tickAndPrintProgress(java.io.PrintStream ps, java.lang.String thingsDesc)
boolean	tickAndPrintProgress(java.io.PrintStream ps, java.lang.String thingsDesc, java.lang.String printPrefix)
boolean	tickAndProgressToLog() Convenience method that does a tick() and outputs a standard message (from getMessage()) to the given Logger (Level INFO) when tick() says to do so.
boolean	tickAndProgressToLog(org.apache.log4j.Logger log)
boolean	tickAndProgressToLog(org.apache.log4j.Logger log, java.lang.String thingsDesc)
boolean	tickAndProgressToLog(org.apache.log4j.Logger log, java.lang.String thingsDesc, java.lang.String logPrefix)

Methods inherited from class java.lang.Object

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

Constructor Detail

ProgressHandler

public ProgressHandler()

Constructs a new ProgressHandler with the given parameters for update interval, rounding, maximum update delay, log level, and a default description of the elements being processed.

Parameters:

_updateInterval - the interval in which progress notifications should be given, in seconds (defaults to 15).

_roundTo - the number of handled elements that must be reached before giving a progress notification (defaults to 100).

_maxUpdateDelay - the maximum time in seconds to wait until a progress notification is shown. If this time has passed, a notification will be given regardless of whether the "_roundTo compatible value" is reached or not. This can be used to ensure notifications are shown periodically even if progress is extremely slow. If set to 0, this feature will be deactivated. Defaults to 20.

_logLevel - the logging level for progress notifications (e.g., Level.INFO, Level.DEBUG). Defaults to Level.INFO.

_defaultThingsDesc - a default description of the elements being handled. This can be null.

_defaultLogger - the default logger to output messages too; will be used by the output methods that can take a logger as parameter if none is given; may be null

_defaultLogPrefix - a default prefix to prepend to log messages; will be used if no prefix argument is given to the methods which can take one; may be null

ProgressHandler

public ProgressHandler(int _updateInterval)

ProgressHandler

public ProgressHandler(int _updateInterval,
                       int _roundTo)

ProgressHandler

public ProgressHandler(int _updateInterval,
                       int _roundTo,
                       int _maxUpdateDelay)

ProgressHandler

public ProgressHandler(int _updateInterval,
                       int _roundTo,
                       int _maxUpdateDelay,
                       org.apache.log4j.Level _logLevel)

ProgressHandler

public ProgressHandler(int _updateInterval,
                       int _roundTo,
                       int _maxUpdateDelay,
                       org.apache.log4j.Level _logLevel,
                       java.lang.String _defaultThingsDesc)

ProgressHandler

public ProgressHandler(int _updateInterval,
                       int _roundTo,
                       int _maxUpdateDelay,
                       org.apache.log4j.Level _logLevel,
                       java.lang.String _defaultThingsDesc,
                       org.apache.log4j.Logger _defaultLogger)

ProgressHandler

public ProgressHandler(int _updateInterval,
                       int _roundTo,
                       int _maxUpdateDelay,
                       org.apache.log4j.Level _logLevel,
                       java.lang.String _defaultThingsDesc,
                       org.apache.log4j.Logger _defaultLogger,
                       java.lang.String _defaultLogPrefix)

ProgressHandler

public ProgressHandler(java.lang.String _defaultThingsDesc,
                       org.apache.log4j.Logger _defaultLogger)

Initializes a `ProgressHandler` instance with a default description of the elements being handled, using default values for update interval (15 seconds), roundTo (100 elements), maxUpdateInterval (20 seconds) and logLevel (Level.INFO).

Parameters:

_defaultThingsDesc - a description of the elements being handled.

_defaultLogger - the default logger to output messages too; will be used by the output methods that can take a logger as parameter if none is given; may be null

_defaultLogPrefix - a default prefix to prepend to log messages; will be used if no prefix argument is given to the methods which can take one; may be null

ProgressHandler

public ProgressHandler(java.lang.String _defaultThingsDesc,
                       org.apache.log4j.Logger _defaultLogger,
                       java.lang.String _defaultLogPrefix)

Method Detail

getLogLevel

public org.apache.log4j.Level getLogLevel()

Returns the current log level.

setLogLevel

public void setLogLevel(org.apache.log4j.Level l)

Sets the log level to the passed Level.

getCountHandled

public long getCountHandled()

Returns the current count handled.

setCountHandled

public void setCountHandled(long l)

Updates count handled to the passed value.

tick

public boolean tick()

Must be called for every handled element.

Returns:

true if progress notification should be shown.

tick

public boolean tick(boolean countUp)

tickAndProgressToLog

public boolean tickAndProgressToLog()

Convenience method that does a tick() and outputs a standard message (from getMessage()) to the given Logger (Level INFO) when tick() says to do so.

Parameters:

log - the Logger to output too

thingsDesc - an (optional, defaults to null) string with the name of the "things" currently handled; used in the message and defaults to just "entries" when null

logPrefix - will be prepended to the default log output if not null

Returns:

true if progress notification was shown

tickAndProgressToLog

public boolean tickAndProgressToLog(org.apache.log4j.Logger log)

tickAndProgressToLog

public boolean tickAndProgressToLog(org.apache.log4j.Logger log,
                                    java.lang.String thingsDesc)

tickAndProgressToLog

public boolean tickAndProgressToLog(org.apache.log4j.Logger log,
                                    java.lang.String thingsDesc,
                                    java.lang.String logPrefix)

tickAndPrintProgress

public boolean tickAndPrintProgress()

Convenience method that does a tick() and outputs a standard message (from getMessage()) to the given PrintStream when tick() says to do so.

Parameters:

ps - the PrintStream to output too

thingsDesc - an (optional, defaults to null) string with the name of the "things" currently handled; used in the message and defaults to just "entries" when null

printPrefix - will be prepended to the default print output if not null

Returns:

true if progress notification was shown

tickAndPrintProgress

public boolean tickAndPrintProgress(java.io.PrintStream ps)

tickAndPrintProgress

public boolean tickAndPrintProgress(java.io.PrintStream ps,
                                    java.lang.String thingsDesc)

tickAndPrintProgress

public boolean tickAndPrintProgress(java.io.PrintStream ps,
                                    java.lang.String thingsDesc,
                                    java.lang.String printPrefix)

progressToLog

public boolean progressToLog()

Convenience method that outputs a standard message (from getMessage()) to the given Logger (Level is current LogLevel) when tick() says to do so.

Parameters:

log - the Logger to output too

thingsDesc - an (optional, defaults to null) string with the name of the "things" currently handled; used in the message and defaults to just "entries" when null

logPrefix - will be prepended to the default log output if not null

Returns:

true if progress notification was shown

progressToLog

public boolean progressToLog(org.apache.log4j.Logger log)

progressToLog

public boolean progressToLog(org.apache.log4j.Logger log,
                             java.lang.String thingsDesc)

progressToLog

public boolean progressToLog(org.apache.log4j.Logger log,
                             java.lang.String thingsDesc,
                             java.lang.String logPrefix)

printProgress

public boolean printProgress()

Convenience method that outputs a standard message (from getMessage()) to the given PrintStream when tick() says to do so.

Parameters:

ps - the Logger to output to. Defaults to System.out

thingsDesc - an (optional, defaults to null) string with the name of the "things" currently handled; used in the message and defaults to just "entries" when null

printPrefix - will be prepended to the default print output if not null

Returns:

true if progress notification was shown

printProgress

public boolean printProgress(java.io.PrintStream ps)

printProgress

public boolean printProgress(java.io.PrintStream ps,
                             java.lang.String thingsDesc)

printProgress

public boolean printProgress(java.io.PrintStream ps,
                             java.lang.String thingsDesc,
                             java.lang.String printPrefix)

finalResultToLog

public void finalResultToLog()

Convenience method that logs a standard final result message to the given Logger with Level INFO.

This method outputs the message retrieved from getMessage() to the specified Logger instance, prefixed with an optional custom log prefix if provided.

Parameters:

log - the Logger instance to output the message to.

thingsDesc - an optional string representing the name of the items currently being handled. If null, the default value "entries" will be used in the message.

logPrefix - a prefix to prepend to the log message. If null, no prefix will be added.

evenWhenNoPreviousOutput - if true, forces the message to be logged even if no previous output was made.

finalResultToLog

public void finalResultToLog(org.apache.log4j.Logger log)

finalResultToLog

public void finalResultToLog(org.apache.log4j.Logger log,
                             java.lang.String thingsDesc)

finalResultToLog

public void finalResultToLog(org.apache.log4j.Logger log,
                             java.lang.String thingsDesc,
                             java.lang.String logPrefix)

finalResultToLog

public void finalResultToLog(org.apache.log4j.Logger log,
                             java.lang.String thingsDesc,
                             java.lang.String logPrefix,
                             boolean evenWhenNoPreviousOutput)

finalResultToLog

public void finalResultToLog(org.apache.log4j.Logger log,
                             boolean evenWhenNoPreviousOutput)

Logs a final result message to the specified Logger instance with Level INFO.

This method logs a standard final result message to the provided Logger instance. The message is always logged with INFO level. If evenWhenNoPreviousOutput is true, the message will be logged even if no previous output was made.

Parameters:

log - the Logger instance to log the message to.

evenWhenNoPreviousOutput - if true, the message will be logged even if no previous output was made.

finalResultToLog

public void finalResultToLog(boolean evenWhenNoPreviousOutput)

printFinalResult

public void printFinalResult()

Convenience method that outputs a standard final result message (from getMessage()) to the given PrintStream.

Parameters:

ps - the PrintStream to output too

thingsDesc - an (optional, defaults to null) string with the name of the "things" currently handled; used in the message and defaults to just "entries" when null

printPrefix - will be prepended to the default print output if not null

printFinalResult

public void printFinalResult(java.io.PrintStream ps)

printFinalResult

public void printFinalResult(java.io.PrintStream ps,
                             java.lang.String thingsDesc)

printFinalResult

public void printFinalResult(java.io.PrintStream ps,
                             java.lang.String thingsDesc,
                             java.lang.String printPrefix)

printFinalResult

public void printFinalResult(java.io.PrintStream ps,
                             java.lang.String thingsDesc,
                             java.lang.String printPrefix,
                             boolean evenWhenNoPreviousOutput)

getMessage

public java.lang.String getMessage(java.lang.String thingsDesc)

Returns a standard progress message (FIXME in english only) with all the info from the current state of this ProgressHandler.

Parameters:

thingsDesc - a string with the name of the "things" currently handled; used in the message

Returns:

standard progress message (FIXME in english only) with all the info from the current state of this ProgressHandler

getMessage

public java.lang.String getMessage(java.lang.String thingsDesc,
                                   boolean forFinalResult)

getMessage

public java.lang.String getMessage(java.lang.String thingsDesc,
                                   boolean forFinalResult,
                                   java.lang.String logPrefix)

getStartedAt

public java.util.Date getStartedAt()

getRunningTime

public long getRunningTime()

Returns:

Time from start in seconds.

isDone

public boolean isDone()

getDefaultThingsDesc

public java.lang.String getDefaultThingsDesc()

setDefaultThingsDesc

public void setDefaultThingsDesc(java.lang.String $1)

getDefaultLogger

public org.apache.log4j.Logger getDefaultLogger()

setDefaultLogger

public void setDefaultLogger(org.apache.log4j.Logger $2)

getDefaultLogPrefix

public java.lang.String getDefaultLogPrefix()

setDefaultLogPrefix

public void setDefaultLogPrefix(java.lang.String $3)