org.x4juli.handlers.rolling
Class FixedWindowRollingPolicy

java.lang.Object
  org.x4juli.global.components.AbstractComponent
      org.x4juli.handlers.rolling.AbstractRollingPolicy
          org.x4juli.handlers.rolling.FixedWindowRollingPolicy

All Implemented Interfaces:

Component, OptionHandler, RollingPolicy

public class FixedWindowRollingPolicy

extends AbstractRollingPolicy

When rolling over, FixedWindowRollingPolicy renames files according to a fixed window algorithm as described below.

The active file is specified by the using RollingFileHandler fileName property, which is required. It represents the name of the file where current logging output will be written. The filenamePattern (required) option represents the file name pattern for the archived (rolled over) log files. If present, the FileNamePattern option must include an integer token, that is the string "%i" somewhere within the pattern.

Let max and min represent the values of respectively the MaxIndex and MinIndex options. Let "foo.log" be the value of the ActiveFile option and "foo.%i.log" the value of FileNamePattern. Then, when rolling over, the file foo.max.log will be deleted, the file foo.max-1.log will be renamed as foo.max.log, the file foo.max-2.log renamed as foo.max-1.log, and so on, the file foo.min+1.log renamed as foo.min+2.log. Lastly, the active file foo.log will be renamed as foo.min.log and a new active file name foo.log will be created.

Given that this rollover algorithm requires as many file renaming operations as the window size, large window sizes are discouraged. The current implementation will automatically reduce the window size to 12 when larger values are specified by the user.

Logging API as a whole was originally done for Apache log4j. Juli is a port of main parts of that to complete the Java Logging APIs. All credits for initial idea, design, implementation, documentation belong to the log4j crew. This file was originally published by Ceki Gülcü. Please use exclusively the appropriate mailing lists for questions, remarks and contribution.

Since:

0.5

Author:

Boris Unckel

Field Summary

private boolean	explicitActiveFile if true, then an explicit name for the active file was specified using RollingFileHandler.filename
private static int	MAX_WINDOW_SIZE It's almost always a bad idea to have a large window size, say over 12.
private int	maxIndex Index for oldest retained log file.
private int	minIndex Index for most recent log file.

Fields inherited from class org.x4juli.handlers.rolling.AbstractRollingPolicy

activeFileName

Fields inherited from class org.x4juli.global.components.AbstractComponent

manager, repository

Constructor Summary

FixedWindowRollingPolicy()
Constructor for use with file based configuration.

FixedWindowRollingPolicy(java.lang.String fileNamePattern)
Constructor for use in programmatically configuration.

Method Summary

void	activateOptions() Activate the options that were previously set with calls to option setters. This allows to defer activiation of the options until all options have been set. This is required for components which have related options that remain ambigous until all are set.
void	configure() Configure all properties of the object. Subclasses should call super.configure() to ensure proper configuration.
int	getMaxIndex() Get index of oldest log file to be retained.
int	getMinIndex() Get index of most recent log file.
RolloverDescription	initialize(java.lang.String file, boolean append) Initialize the policy and return any initial actions for rolling file appender..
private boolean	purge(int lowIndex, int highIndex) Purge and rename old log files in preparation for rollover
RolloverDescription	rollover(java.lang.String currentFileName) Prepare for a rollover. This method is called prior to closing the active log file, performs any necessary preliminary actions and describes actions needed after close of current log file.
void	setMaxIndex(int maxIndex) Set index of oldest log file to be retained.
void	setMinIndex(int minIndex) Set index of most recent log file.

Methods inherited from class org.x4juli.handlers.rolling.AbstractRollingPolicy

formatFileName, getDatePatternConverter, getFileNamePattern, getIntegerPatternConverter, getMessageProperties, parseFileNamePattern, setFileNamePattern, toString

Methods inherited from class org.x4juli.global.components.AbstractComponent

getLogger, getLoggerRepository, getNonFloodingLogger, getProperty, getProperty, getProperty, getProperty, resetErrorCount, setObjectStore

Methods inherited from class java.lang.Object

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

Field Detail

MAX_WINDOW_SIZE

private static final int MAX_WINDOW_SIZE

It's almost always a bad idea to have a large window size, say over 12.

See Also:

Constant Field Values

maxIndex

private int maxIndex

Index for oldest retained log file.

minIndex

private int minIndex

Index for most recent log file.

explicitActiveFile

private boolean explicitActiveFile

if true, then an explicit name for the active file was specified using RollingFileHandler.filename

Constructor Detail

FixedWindowRollingPolicy

public FixedWindowRollingPolicy()

Constructor for use with file based configuration.

FixedWindowRollingPolicy

public FixedWindowRollingPolicy(java.lang.String fileNamePattern)

Constructor for use in programmatically configuration.

Parameters:

fileNamePattern - pattern to determine the filename.

Method Detail

initialize

public RolloverDescription initialize(java.lang.String file,
                                      boolean append)
                               throws java.lang.SecurityException

Initialize the policy and return any initial actions for rolling file appender..

Parameters:

file - current value of RollingFileHandler.getFile().

append - current value of RollingFileHandler.getAppend().

Returns:

Description of the initialization, may be null to indicate no initialization needed.

Throws:

java.lang.SecurityException - if denied access to log files.

Since:

rollover

public RolloverDescription rollover(java.lang.String currentFileName)
                             throws java.lang.SecurityException

Prepare for a rollover. This method is called prior to closing the active log file, performs any necessary preliminary actions and describes actions needed after close of current log file.

Parameters:

currentFileName - file name for current active log file.

Returns:

Description of pending rollover, may be null to indicate no rollover at this time.

Throws:

java.lang.SecurityException - if denied access to log files.

Since:

activateOptions

public void activateOptions()

Activate the options that were previously set with calls to option setters.

This allows to defer activiation of the options until all options have been set. This is required for components which have related options that remain ambigous until all are set.

Specified by:

activateOptions in interface OptionHandler

Overrides:

activateOptions in class AbstractRollingPolicy

Since:

0.5

configure

public void configure()

Configure all properties of the object. Subclasses should call super.configure() to ensure proper configuration.

Overrides:

configure in class AbstractRollingPolicy

Since:

0.5

getMaxIndex

public int getMaxIndex()

Get index of oldest log file to be retained.

Returns:

index of oldest log file.

getMinIndex

public int getMinIndex()

Get index of most recent log file.

Returns:

index of oldest log file.

setMaxIndex

public void setMaxIndex(int maxIndex)

Set index of oldest log file to be retained.

Parameters:

maxIndex - index of oldest log file to be retained.

setMinIndex

public void setMinIndex(int minIndex)

Set index of most recent log file.

Parameters:

minIndex - Index of most recent log file.

purge

private boolean purge(int lowIndex,
                      int highIndex)

Purge and rename old log files in preparation for rollover

Parameters:

lowIndex - low index

highIndex - high index. Log file associated with high index will be deleted if needed.

Returns:

true if purge was successful and rollover should be attempted.