mondrian.util
Interface MemoryMonitor

All Known Implementing Classes:

AbstractMemoryMonitor, FauxMemoryMonitor, NotificationMemoryMonitor

public interface MemoryMonitor

API for Mondrian's memory monitors.

For Java4, the available monitors do nothing since there is no reliable way of detecting that memory is running low using such a JVM (you are welcome to try to create one, but I believe you will fail - some such candidates only make it more likely that an OutOfMemory condition will occur).

For Java5 one can optionally enable a monitor which is based upon the Java5 memory classes locate in java.lang.management.

A client must implement the MemoryMonitor.Listener interface and register with the MemoryMonitor.

The MemoryMonitor supports having multiple Listener clients. The clients can have the same threshold percentage or different values. The threshold percentage value is used by the MemoryMonitor to determine when to notify a client. It is the percentage of the total memory:

100 * free-memory / total-memory (0 ≤ free-memory ≤ total-memory).

Since:

Feb 01 2007

Author:

Richard M. Emberson

Nested Class Summary

static interface	MemoryMonitor.Listener A MemoryMonitor client implements the Listener interface and registers with the MemoryMonitor.
static interface	MemoryMonitor.Test This is an interface that a MemoryMonitor may optionally implement.

Method Summary

boolean	addListener(MemoryMonitor.Listener listener) Adds a Listener using the default threshold percentage.
boolean	addListener(MemoryMonitor.Listener listener, int thresholdPercentage) Adds a Listener to the MemoryMonitor with a given threshold percentage.
long	getMaxMemory() Returns the maximum memory usage.
long	getUsedMemory() Returns the current memory used.
void	removeAllListener() Clear out all Listeners and turnoff JVM memory notification.
boolean	removeListener(MemoryMonitor.Listener listener) Removes a Listener from the MemoryMonitor.
void	updateListenerThreshold(MemoryMonitor.Listener listener, int percentage) Changes the threshold percentage of a given Listener.

Method Detail

addListener

boolean addListener(MemoryMonitor.Listener listener,
                    int thresholdPercentage)

Adds a Listener to the MemoryMonitor with a given threshold percentage.

If the threshold is below the Java5 memory managment system's threshold, then the Listener is notified from within this method.

Parameters:

listener - the Listener to be added.

thresholdPercentage - the threshold percentage for this Listener.

Returns:

true if the Listener was added and false otherwise.

addListener

boolean addListener(MemoryMonitor.Listener listener)

Adds a Listener using the default threshold percentage.

If the threshold is below the Java5 memory managment system's threshold, then the Listener is notified from within this method.

Parameters:

listener - the Listener to be added.

Returns:

true if the Listener was added and false otherwise.

updateListenerThreshold

void updateListenerThreshold(MemoryMonitor.Listener listener,
                             int percentage)

Changes the threshold percentage of a given Listener.

If the new value is below the system's current value, then the Listener will have its notification callback called while in this method - so a client should always check if its notification method was called immediately after calling this method.

This method can be used if, for example, an algorithm has different approaches that result in different memory usage profiles; one, large memory but fast and a second which is low-memory but slow. The algorithm starts with the large memory approach, receives a low memory notification, switches to the low memory approach and changes when it should be notified for this new approach. The first approach need to be notified at a lower percentage because it uses lots of memory, possibly quickly; while the second approach, possibly a file based algorithm, has smaller memory requirements and uses memory less quickly thus one can live with a higher notification threshold percentage.

Parameters:

listener - the Listener being updated.

percentage - new percentage threshold.

removeListener

boolean removeListener(MemoryMonitor.Listener listener)

Removes a Listener from the MemoryMonitor. Returns true if listener was removed and false otherwise.

Parameters:

listener - the listener to be removed

Returns:

true if listener was removed.

removeAllListener

void removeAllListener()

Clear out all Listeners and turnoff JVM memory notification.

getMaxMemory

long getMaxMemory()

Returns the maximum memory usage.

Returns:

the maximum memory usage.

getUsedMemory

long getUsedMemory()

Returns the current memory used.

Returns:

the current memory used.