com.lf.commons.gui

Class MemoryController

java.lang.Object

java.awt.Component

java.awt.Container

javax.swing.JComponent

javax.swing.JPanel

com.lf.commons.gui.MemoryController

All Implemented Interfaces:

java.awt.event.ActionListener, java.awt.image.ImageObserver, java.awt.MenuContainer, java.io.Serializable, java.util.EventListener, javax.accessibility.Accessible

public class MemoryController
extends javax.swing.JPanel
implements java.awt.event.ActionListener

Monitors the memory consumption (heap) of a JVM and allows to run the gc.

This is a component which should be part of each Java application which may encounter problems with memory consumption. Since KAT applications require much memory if large input files are processed this is an absolutely necessary component for the system.

The design was adapted to the functionality found in the Java IDE IntelliJ IDEA which seems pretty adequate for most Java applications. If you plan to use an icon other than the default recycle_16.png take care about the image size. It should be exactly 14x14 pixels in size.

The controller offers the possibility to automatically run the garbage collector if the used memory exceeds a certain threshold. This threshold is specified as percentage of the maximum heap size. Common values for this parameter are 80 - 90 %. The garbage collector is called only once if the used memory exceeds the threshold value and not again and again if the threshold is constantly exceeded. The automatic garbage collecting functionality will additionally make a pause of certain seconds then so that there will not be any blocking (penalty parameter in seconds).

Threshold values must be in the range between 10 and 100 % (default is 80 %). The penalty must be a value at least of 1 second (default is 5 seconds). The timeout for the controller update is passed in milliseconds and must be a value greater equal 100 milliseconds.

If the auto-gc functionality is activated each manual garbage collection initiated by the user will reset the auto-gc counter. This keeps the garbage collector from doing unnecessary work.

Since:

1.5

Version:

$Revision: 1.17 $, $Date: 2012/12/28 11:44:25 $

Author:

Axel Schwolow

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class javax.swing.JPanel

javax.swing.JPanel.AccessibleJPanel

Nested classes/interfaces inherited from class javax.swing.JComponent

javax.swing.JComponent.AccessibleJComponent

Nested classes/interfaces inherited from class java.awt.Container

java.awt.Container.AccessibleAWTContainer

Nested classes/interfaces inherited from class java.awt.Component

java.awt.Component.AccessibleAWTComponent, java.awt.Component.BaselineResizeBehavior, java.awt.Component.BltBufferStrategy, java.awt.Component.FlipBufferStrategy

Field Summary

Fields

Modifier and Type	Field and Description
static java.net.URL	ICON_CANCEL Icon representing a memory controller button to cancel the operation (external use).
static java.net.URL	ICON_GO Icon representing an functional memory controller button.
static int	IDLE_CONTROLLER Idle mode where the memory controller is displayed.
static int	IDLE_PROGRESS Idle mode where the (empty) progress bar without gc button is displayed.
protected java.util.Vector<ThresholdListener>	thresholdListeners Container holding the external threshold listeners.

Fields inherited from class javax.swing.JComponent

accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW

Fields inherited from class java.awt.Component

BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT

Fields inherited from interface java.awt.image.ImageObserver

ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH

Constructor Summary

Constructors

Constructor and Description
MemoryController() Constructor of this form.

Method Summary

Methods

Modifier and Type	Method and Description
void	actionPerformed(java.awt.event.ActionEvent e) This method is called automatically if an event comes along.
void	addMouseListener(java.awt.event.MouseListener listener) Adds a mouse listener for the status bar (only labels on the left side).
void	addThresholdListener(ThresholdListener listener) Adds a listener to be informed when a certain threshold was reached.
protected void	finalize() Clean-up method to help the gc.
javax.swing.JButton	getAndRemoveButtonGC() Provides the JVM garbage collector button, component is removed from layout.
javax.swing.JProgressBar	getAndRemoveProgressBar() Provides the progress bar, component is removed from layout.
javax.swing.JButton	getButtonGC() Provides the JVM garbage collector button.
int	getIdleMode() Determines the current display mode for the component.
int	getPenalty() Gets the penalty value on-the-fly (in seconds).
int	getPriority() Gets the priority for the update task.
javax.swing.JProgressBar	getProgressBar() Provides the progress bar.
java.lang.Runnable	getTask(boolean infinite) Provides the instance doing the controller update task.
int	getThreshold() Allows to get the timeout interval on-the-fly (in milliseconds).
int	getTimeout() Allows to get the timeout interval on-the-fly (in milliseconds).
int	getVisibilityThreshold() Provides the percentage which must be reached to make the memory controller be shown.
boolean	isAutogc() Gets the auto garbage collecting functionality setting.
void	removeThresholdListener(ThresholdListener listener) Removes a listener to be informed when a certain threshold was reached.
void	runGC() Explicitely runs the JVM garbage collector by clicking the button.
boolean	setAutoGC(boolean autogc) Allows to (de)activate the auto garbage collecting functionality.
boolean	setPenalty(int penalty) Allows to set the penalty value on-the-fly (in seconds).
boolean	setPriority(int priority) Sets the priority for the update task.
boolean	setThreshold(int threshold) Allows to set the auto-gc threshold on-the-fly (percentage).
boolean	setTimeout(int timeout) Allows to set the timeout interval on-the-fly (in milliseconds).
boolean	setVisibilityThreshold(int threshold) Sets the percentage which must be reached to make the memory controller be shown.
void	startController() Starts the update thread based on the current configuration.
void	startExternalOp() Configures the component to be utilized externally as progress bar.
void	startExternalOp(java.awt.event.ActionListener listener) Configures the component to be utilized externally as progress bar.
void	startExternalOp(javax.swing.ImageIcon icon, java.lang.String tooltip, java.awt.event.ActionListener listener) Configures the component to be utilized externally as progress bar.
void	stopController() Call this method if you like the update thread be terminated properly.
void	stopExternalOp() Configures the component not to be utilized externally as progress bar any longer.
void	updateController() Performs an explicit update of the data presented by the controller.

Methods inherited from class javax.swing.JPanel

getAccessibleContext, getUI, getUIClassID, paramString, setUI, updateUI

Methods inherited from class javax.swing.JComponent

addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingOrigin, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update

Methods inherited from class java.awt.Container

add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusDownCycle, validate, validateTree

Methods inherited from class java.awt.Component

action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusBackward, transferFocusUpCycle

Methods inherited from class java.lang.Object

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

Field Detail

ICON_GO

public static final java.net.URL ICON_GO

Icon representing an functional memory controller button.

ICON_CANCEL

public static final java.net.URL ICON_CANCEL

Icon representing a memory controller button to cancel the operation (external use).

IDLE_CONTROLLER

public static final int IDLE_CONTROLLER

Idle mode where the memory controller is displayed.

See Also:

Constant Field Values

IDLE_PROGRESS

public static final int IDLE_PROGRESS

Idle mode where the (empty) progress bar without gc button is displayed.

See Also:

Constant Field Values

thresholdListeners

protected java.util.Vector<ThresholdListener> thresholdListeners

Container holding the external threshold listeners.

Constructor Detail

MemoryController

public MemoryController()

Constructor of this form.

Since:

1.5

Method Detail

finalize

protected void finalize()
                 throws java.lang.Throwable

Clean-up method to help the gc.

Overrides:

finalize in class java.lang.Object

Throws:

java.lang.Throwable

Since:

1.5

updateController

public void updateController()

Performs an explicit update of the data presented by the controller.

If available the installed ThresholdListener instances are informed if the given threshold values have been reached.

Since:

1.5

startController

public void startController()

Starts the update thread based on the current configuration.

Since:

1.5

stopController

public void stopController()

Call this method if you like the update thread be terminated properly.

Since:

1.5

getTask

public java.lang.Runnable getTask(boolean infinite)

Provides the instance doing the controller update task.

Normally the memory controller itself cares for its update if the application calls startController() and stopController() at the right times. Applications can delegate this regularly task to other threads like the status bar which updates date and time. This allows for saving JVM memory and performance since the dedicated thread must not be installed.

Parameters:

infinite - Update task never returns except for errors

Returns:

The controller instance

Since:

1.5

runGC

public void runGC()

Explicitely runs the JVM garbage collector by clicking the button.

Since:

1.5

getButtonGC

public javax.swing.JButton getButtonGC()

Provides the JVM garbage collector button.

Returns:

The garbage collector button

Since:

1.5

getAndRemoveButtonGC

public javax.swing.JButton getAndRemoveButtonGC()

Provides the JVM garbage collector button, component is removed from layout.

This method allows for rearranging the button e.g. as part of a tool bar. Remember that the component is still coupled with the memory controller!

Returns:

The garbage collector button

Since:

1.5

getProgressBar

public javax.swing.JProgressBar getProgressBar()

Provides the progress bar.

Returns:

The progress bar

Since:

1.5

getAndRemoveProgressBar

public javax.swing.JProgressBar getAndRemoveProgressBar()

Provides the progress bar, component is removed from layout.

This method allows for rearranging the progress e.g. as part of a tool bar. Remember that the component is still coupled with the recycle button!

Returns:

The progress bar

Since:

1.5

setTimeout

public boolean setTimeout(int timeout)

Allows to set the timeout interval on-the-fly (in milliseconds).

Don't pass timeout values <100! This will cause the timeout not to be updated.

Parameters:

timeout - The new timeout for controller refresh

Returns:

Setting succeeded?

Since:

1.5

getTimeout

public int getTimeout()

Allows to get the timeout interval on-the-fly (in milliseconds).

Returns:

The timeout for controller refresh

Since:

1.5

setThreshold

public boolean setThreshold(int threshold)

Allows to set the auto-gc threshold on-the-fly (percentage).

Don't pass values <10 or >100! This will cause the threshold not to be updated.

Parameters:

threshold - The new threshold for the auto-gc functionality

Returns:

Setting succeeded?

Since:

1.5

getThreshold

public int getThreshold()

Allows to get the timeout interval on-the-fly (in milliseconds).

Returns:

The threshold for the auto-gc functionality

Since:

1.5

setPenalty

public boolean setPenalty(int penalty)

Allows to set the penalty value on-the-fly (in seconds).

Don't pass values < 1 seconds! This will cause the penalty not to be updated.

Parameters:

penalty - The new penalty for the auto-gc functionality

Returns:

Setting succeeded?

Since:

1.5

getPenalty

public int getPenalty()

Gets the penalty value on-the-fly (in seconds).

Returns:

The penalty for the auto-gc functionality

Since:

1.5

setAutoGC

public boolean setAutoGC(boolean autogc)

Allows to (de)activate the auto garbage collecting functionality.

Parameters:

autogc - Shall garbage collecting be automated?

Returns:

Setting succeeded?

Since:

1.5

isAutogc

public boolean isAutogc()

Gets the auto garbage collecting functionality setting.

Returns:

Shall garbage collecting be automated?

Since:

1.5

setPriority

public boolean setPriority(int priority)

Sets the priority for the update task.

Parameters:

priority - Thread priority

Returns:

Setting succeeded?

Since:

1.5

getPriority

public int getPriority()

Gets the priority for the update task.

Returns:

Thread priority

Since:

1.5

setVisibilityThreshold

public boolean setVisibilityThreshold(int threshold)

Sets the percentage which must be reached to make the memory controller be shown.

As long as the threshold is not reached or exceeded the component only shown a default progress bar and an empty icon (no gc button).

Parameters:

threshold - The new threshold value (percentage in the range from 0 to 100)

Returns:

Setting succeeded?

Since:

1.5

getVisibilityThreshold

public int getVisibilityThreshold()

Provides the percentage which must be reached to make the memory controller be shown.

As long as the threshold is not reached or exceeded the component only shown a default progress bar and an empty icon (no gc button).

Returns:

The threshold for the visibility (percentage in the range from 0 to 100)

Since:

1.5

startExternalOp

public void startExternalOp()

Configures the component to be utilized externally as progress bar.

After the operation is finished it must be released with stopExternalOp() in order to switch back to idle mode showing either the controller or the progress bar.

Since:

1.5

startExternalOp

public void startExternalOp(java.awt.event.ActionListener listener)

Configures the component to be utilized externally as progress bar.

After the operation is finished it must be released with stopExternalOp() in order to switch back to idle mode showing either the controller or the progress bar.

Parameters:

listener - The callback object, may be null

Since:

1.5

startExternalOp

public void startExternalOp(javax.swing.ImageIcon icon,
                   java.lang.String tooltip,
                   java.awt.event.ActionListener listener)

Configures the component to be utilized externally as progress bar.

After the operation is finished it must be released with stopExternalOp() in order to switch back to idle mode showing either the controller or the progress bar.

Parameters:

icon - The icon to be displayed instead of gc icon, null deactivates button

tooltip - The tooltip of the button, may be null

listener - The callback object, may be null

Since:

1.5

stopExternalOp

public void stopExternalOp()

Configures the component not to be utilized externally as progress bar any longer.

Since:

1.5

addMouseListener

public void addMouseListener(java.awt.event.MouseListener listener)

Adds a mouse listener for the status bar (only labels on the left side).

Overrides:

addMouseListener in class java.awt.Component

Parameters:

listener - Listener for the component

Since:

1.6

getIdleMode

public int getIdleMode()

Determines the current display mode for the component.

Returns:

IDLE_CONTROLLER | IDLE_PROGRESS

Since:

1.6

addThresholdListener

public void addThresholdListener(ThresholdListener listener)

Adds a listener to be informed when a certain threshold was reached.

Parameters:

listener - The listener instance

Throws:

java.lang.NullPointerException - If parameter is null

java.lang.IllegalArgumentException - If threshold is not between 10% and 100%

Since:

1.6

removeThresholdListener

public void removeThresholdListener(ThresholdListener listener)

Removes a listener to be informed when a certain threshold was reached.

Parameters:

listener - The listener instance

Throws:

java.lang.NullPointerException - If parameter is null

Since:

1.6

actionPerformed

public void actionPerformed(java.awt.event.ActionEvent e)

This method is called automatically if an event comes along.

This may be the case after clicking the gc button.

Specified by:

actionPerformed in interface java.awt.event.ActionListener

Parameters:

e - Event object reference

Since:

1.5