MemoryHandler maintains a circular buffer of
* log records.
*
* Configuration: Values of the subsequent
* LogManager properties are taken into consideration
* when a MemoryHandler is initialized.
* If a property is not defined, or if it has an invalid
* value, a default is taken without an exception being thrown.
*
*
java.util.MemoryHandler.level - specifies
* the initial severity level threshold. Default value:
* Level.ALL.java.util.MemoryHandler.filter - specifies
* the name of a Filter class. Default value: No Filter.java.util.MemoryHandler.size - specifies the
* maximum number of log records that are kept in the circular
* buffer. Default value: 1000.java.util.MemoryHandler.push - specifies the
* pushLevel. Default value:
* Level.SEVERE.java.util.MemoryHandler.target - specifies the
* name of a subclass of {@link Handler} that will be used as the
* target handler. There is no default value for this property;
* if it is not set, the no-argument MemoryHandler constructor
* will throw an exception.buffer[position] before position is incremented by
* one. If position becomes greater than the size of the buffer, it
* is reset to zero.
*/
private int position;
/**
* The number of log records which have been published, but not
* pushed yet to the target handler.
*/
private int numPublished;
/**
* The push level threshold for this Handler. When a
* record is published whose severity level is greater than or equal
* to the pushLevel of this MemoryHandler,
* the {@link #push()} method will be invoked for pushing the buffer
* contents to the target Handler.
*/
private Level pushLevel;
/**
* The Handler to which log records are forwarded for actual
* publication.
*/
private final Handler target;
/**
* Constructs a MemoryHandler for keeping a circular
* buffer of LogRecords; the initial configuration is determined by
* the LogManager properties described above.
*/
public MemoryHandler()
{
this((Handler) LogManager.getInstanceProperty(
"java.util.logging.MemoryHandler.target",
Handler.class, /* default */ null),
LogManager.getIntPropertyClamped(
"java.util.logging.MemoryHandler.size",
/* default */ 1000,
/* minimum value */ 1,
/* maximum value */ Integer.MAX_VALUE),
LogManager.getLevelProperty(
"java.util.logging.MemoryHandler.push",
/* default push level */ Level.SEVERE));
}
/**
* Constructs a MemoryHandler for keeping a circular
* buffer of LogRecords, given some parameters. The values of the
* other parameters are taken from LogManager properties, as
* described above.
*
* @param target the target handler that will receive those
* log records that are passed on for publication.
*
* @param size the number of log records that are kept in the buffer.
* The value must be a at least one.
*
* @param pushLevel the push level threshold for this
* MemoryHandler. When a record is published whose
* severity level is greater than or equal to
* pushLevel, the {@link #push()} method will be
* invoked in order to push the bufffer contents to
* target.
*
* @throws java.lang.IllegalArgumentException if size
* is negative or zero. The GNU implementation also throws
* an IllegalArgumentException if target or
* pushLevel are null, but the
* API specification does not prescribe what should happen
* in those cases.
*/
public MemoryHandler(Handler target, int size, Level pushLevel)
{
if ((target == null) || (size <= 0) || (pushLevel == null))
throw new IllegalArgumentException();
buffer = new LogRecord[size];
this.pushLevel = pushLevel;
this.target = target;
setLevel(LogManager.getLevelProperty(
"java.util.logging.MemoryHandler.level",
/* default value */ Level.ALL));
setFilter((Filter) LogManager.getInstanceProperty(
"java.util.logging.MemoryHandler.filter",
/* must be instance of */ Filter.class,
/* default value */ null));
}
/**
* Stores a LogRecord in a fixed-size circular buffer,
* provided the record passes all tests for being loggable. If the
* buffer is full, the oldest record will be discarded.
*
* If the record has a severity level which is greater than or
* equal to the pushLevel of this
* MemoryHandler, the {@link #push()} method will be
* invoked for pushing the buffer contents to the target
* Handler.
*
*
Most applications do not need to call this method directly.
* Instead, they will use use a {@link Logger}, which will create
* LogRecords and distribute them to registered handlers.
*
* @param record the log event to be published.
*/
public void publish(LogRecord record)
{
if (!isLoggable(record))
return;
buffer[position] = record;
position = (position + 1) % buffer.length;
numPublished = numPublished + 1;
if (record.getLevel().intValue() >= pushLevel.intValue())
push();
}
/**
* Pushes the contents of the memory buffer to the target
* Handler and clears the buffer. Note that
* the target handler will discard those records that do
* not satisfy its own severity level threshold, or that are
* not considered loggable by an installed {@link Filter}.
*
*
In case of an I/O failure, the {@link ErrorManager} of the
* target Handler will be notified, but the caller of
* this method will not receive an exception.
*/
public void push()
{
int i;
if (numPublished < buffer.length)
{
for (i = 0; i < position; i++)
target.publish(buffer[i]);
}
else
{
for (i = position; i < buffer.length; i++)
target.publish(buffer[i]);
for (i = 0; i < position; i++)
target.publish(buffer[i]);
}
numPublished = 0;
position = 0;
}
/**
* Forces any data that may have been buffered by the target
* Handler to the underlying output device, but
* does not push the contents of the circular memory
* buffer to the target handler.
*
*
In case of an I/O failure, the {@link ErrorManager} of the
* target Handler will be notified, but the caller of
* this method will not receive an exception.
*
* @see #push()
*/
public void flush()
{
target.flush();
}
/**
* Closes this MemoryHandler and its associated target
* handler, discarding the contents of the memory buffer. However,
* any data that may have been buffered by the target
* Handler is forced to the underlying output device.
*
*
As soon as close has been called,
* a Handler should not be used anymore. Attempts
* to publish log records, to flush buffers, or to modify the
* Handler in any other way may throw runtime
* exceptions after calling close.
In case of an I/O failure, the ErrorManager of
* the associated target Handler will be informed, but
* the caller of this method will not receive an exception.
Handler.
* When a record is published whose severity level is greater
* than or equal to the pushLevel of this
* MemoryHandler, the {@link #push()} method will be
* invoked for pushing the buffer contents to the target
* Handler.
*
* @return the push level threshold for automatic pushing.
*/
public Level getPushLevel()
{
return pushLevel;
}
/**
* Sets the push level threshold for this Handler.
* When a record is published whose severity level is greater
* than or equal to the pushLevel of this
* MemoryHandler, the {@link #push()} method will be
* invoked for pushing the buffer contents to the target
* Handler.
*
* @param pushLevel the push level threshold for automatic pushing.
*
* @exception SecurityException if a security manager exists and
* the caller is not granted the permission to control
* the logging infrastructure.
*
* @exception NullPointerException if pushLevel is
* null.
*/
public void setPushLevel(Level pushLevel)
{
LogManager.getLogManager().checkAccess();
/* Throws a NullPointerException if pushLevel is null. */
pushLevel.getClass();
this.pushLevel = pushLevel;
}
}