PIRL

PIRL.Viewers
Class Memory_Chart

java.lang.Object
  extended by java.awt.Component
      extended by java.awt.Container
          extended by javax.swing.JComponent
              extended by PIRL.Viewers.Memory_Chart
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, EventListener, ChangeListener

public class Memory_Chart
extends JComponent
implements ChangeListener

A Memory_Chart provides a self-updating graphical display of the Java runtime environment (JRE) memory usage.

The JRE reports three categories of memory: the total amount of available memory in the JRE heap space, the amount of allocated memory used by objects, and the amount of free memory that is no longer in use by objects which can be garbage collected.

Memory use over time is stored in a Memory_History that samples the JRE memory categories at a user specified rate and stores the values in history arrays up to some maximum number of values. When the maximum number of samples has been accumulated the next sample causes the oldest value to be dropped before the new value is added. Obtaining a sample also results in the component display to be updated by displaying all current memory history values as a horizontally time-ordered (oldest on the left) chart with one vertical bar per sample. Each sample bar is divided into three sections; from top to bottom: the amount of unallocated memory (available memory minus allocated memory) in blue, the amount of free memory in green, and the amount of memory in use (@link #Allocated_Memory() allocated memory} minus free memory) in red. The visual effect is a memory use chart that automatically scrolls from right to left as new samples are acquired.

Below the memory use bars a seconds scale is optionally displayed with short tick marks every fifth bar and long tick marks every tenth bar. Also, if the sampling rate is more often than every 20 seconds a thick long mark is provided for each minute. The total duration, in seconds, of the history chart is written at the left end of the seconds scale. If annotations are enabled and the sampling rate is not once per second the scale multiplication factor is shown.

To the right of the chart annotation may be optionally displayed. This will list the most recent memory sample using the same values and colors as used in the chart bars.

Memory sampling may be stopped and restarted. When sampling is restarted the memory history is cleared. The sampling rate may be changed at any time which will also clear the current memory history.

The component will automatically manage the Memory_History by ensuring that there is always enough memory history for the chart display width.

N.B.: The Memory_History sampling can not be guaranteed to always occur at the selected rate; other activity on the system may prevent a sampling timer event from occurring at the intended time. Nevertheless, there will still be the correct number of samples generated for the overall amount of elapsed time. To achieve this there may be occasional bursts of catch-up sampling events that will result in memory values that have not been sampled at the expected time; but no sampling events will be dropped. Thus overall the memory chart will be a reasonable reflection of the JRE memory use profile with any particular sample occurring as close to the expected time as the system allows.

Version:
1.5
Author:
Bradford Castalia - idaeim
See Also:
Memory_History, Serialized Form

Nested Class Summary
 
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
 
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
 
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
 
Field Summary
static Font ANNOTATION_FONT
          The text font that will be used to provide chart annotations.
static Dimension DEFAULT_SIZE
          The initial size of the component.
static String ID
          Class identification name with source code version and date.
 
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
Memory_Chart()
          Construct an idle Memory_Chart.
Memory_Chart(int sampling_rate)
          Construct a Memory_Chart that samples at a specified rate.
 
Method Summary
static long Allocated_Memory()
          Get the amount of memory currently in use by the Java runtime environment.
 int Annotation_Area_Width()
          Get the width of the annotation display area.
 int Annotation_Text_Height()
          Get the height of the annotation text.
 boolean Annotation()
          Check if the annotation display is enabled.
 Memory_Chart Annotation(boolean enabled)
          Enable or disable the display of memory values annotation.
static long Available_Memory()
          Get the total amount of memory available to the Java runtime environment.
static long Free_Memory()
          Get the amount of memory allocated by the Java runtime environment but not currently in use.
 Memory_History getModel()
          Get the Memory_History model bound to the component.
 String getUIClassID()
          Get the ComponentUI class identification for this component.
 int Previous_Rate()
          Get the previous memory sampling rate.
 int Rate()
          Get the memory sampling rate.
 Memory_Chart Rate(int rate)
          Set the memory history sampling rate.
 int Seconds_Scale_Height()
          Get the height of the seconds scale display area.
 boolean Seconds_Scale()
          Check if the seconds scale display is enabled.
 Memory_Chart Seconds_Scale(boolean enabled)
          Enable or disable the display of the seconds scale.
 void setModel(Memory_History model)
          Set a new Memory_History model for the component.
 void setUI(Memory_ChartUI UI)
          Set the graphical user interface (UI) delegate for the component.
 void Start()
          Start the chart memory sampling.
 void stateChanged(ChangeEvent event)
          The ChangeListener interface method.
 void Stop()
          Stop the memory chart.
 void updateUI()
          Set the user interface delegate to the ComponentUI found by the UIManger for this component.
 
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getAccessibleContext, 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, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, paramString, 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, transferFocusBackward, transferFocusDownCycle, validate, validateTree
 
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, 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, transferFocusUpCycle
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

ID

public static final String ID
Class identification name with source code version and date.

See Also:
Constant Field Values

DEFAULT_SIZE

public static final Dimension DEFAULT_SIZE
The initial size of the component.


ANNOTATION_FONT

public static final Font ANNOTATION_FONT
The text font that will be used to provide chart annotations.

Constructor Detail

Memory_Chart

public Memory_Chart(int sampling_rate)
Construct a Memory_Chart that samples at a specified rate.

Parameters:
sampling_rate - The number of seconds between memory samples. A sampling rate of zero constructs an inactive chart.

Memory_Chart

public Memory_Chart()
Construct an idle Memory_Chart.

A sampling rate must be set before the chart will become active.

Method Detail

Annotation

public Memory_Chart Annotation(boolean enabled)
Enable or disable the display of memory values annotation.

When enabled an area on the right side of the memory chart will be used to display, from top to bottom: the total amount of available memory in black, the amount of unallocated memory (available memory minus allocated memory) in blue, the amount of free memory (allocated but not used by any objects; i.e. subject to garbage collection) in green, and the amount of memory in use (@link #Allocated_Memory() allocated memory} minus free memory) in red. Each value is in the range 0-1023 with a magnitude suffix character - "K" for kilobytes, "M" for megabytes, "G" for gigabytes - as appropriate.

Parameters:
enabled - If true (the default) the annotation display will be enabled. If false, annoation will not be displayed.
Returns:
This Memory_Chart.
See Also:
Annotation_Area_Width()

Annotation

public boolean Annotation()
Check if the annotation display is enabled.

Returns:
true if the annotation display is enabled; false otherwise.

Annotation_Area_Width

public int Annotation_Area_Width()
Get the width of the annotation display area.

The annotation display occupies the right end of the component area. The value will be zero if the annotation display is not enabled. If the appropriate size can not be determined from the annotation font (because a component rendering graphics device has not yet been assigned) the width will be a guesstimate based on a typical display device of approximately 100 pixels per inch.

Returns:
The width, in pixels, of the a annotation display area, or zero if annotation is disabled.

Annotation_Text_Height

public int Annotation_Text_Height()
Get the height of the annotation text.

If the appropriate size can not be determined from the annotation font (because a component rendering graphics device has not yet been assigned) the text height will be a guesstimate based on a typical display device of approximately 100 pixels per inch.

Returns:
The height, in pixels, of the a annotation text.

Seconds_Scale

public Memory_Chart Seconds_Scale(boolean enabled)
Enable or disable the display of the seconds scale.

When enabled the seconds scale an area at the bottom of the memory chart will be used to display tick marks to aid in counting the number of memory samples in the chart. Short tick marks will occur every fifth sample measured from the most recent sample on the right end of the chart. Long tick marks will occur every tenth sample. If the sampling rate is more often than every 20 seconds a thick long mark is provided for each minute in the sampling history. The total duration, in seconds, of the history chart is written at the left end of the seconds scale when there is sufficient space. If annotation is enabled "secs" will be written to the right of the seconds scale in the annotation area. However, if the sampling rate is not once per second the annotation is the scale multiplication factor preceeded by "x" and followed by " s".

Parameters:
enabled - If true (the default) the seconds scale display will be enabled. If false, the seconds scale will not be displayed.
Returns:
This Memory_Chart.
See Also:
Seconds_Scale_Height()

Seconds_Scale

public boolean Seconds_Scale()
Check if the seconds scale display is enabled.

Returns:
true if the seconds scale display is enabled; false otherwise.

Seconds_Scale_Height

public int Seconds_Scale_Height()
Get the height of the seconds scale display area.

If the appropriate size can not be determined from the annotation font (because a component rendering graphics device has not yet been assigned) the height will be a guesstimate based on a typical display device of approximately 100 pixels per inch.

Returns:
The height, in pixels, of the seonds scale display area.

setModel

public void setModel(Memory_History model)
Set a new Memory_History model for the component.

Parameters:
model - A Memory_History object.

getModel

public Memory_History getModel()
Get the Memory_History model bound to the component.

Returns:
A Memory_History object.

Rate

public Memory_Chart Rate(int rate)
Set the memory history sampling rate.

If the new samping rate is different than the current sampling rate the rate is changed and a "rate" property change event is fired. The previous rate, if non-zero, is remembered.

N.B.: If the rate is less than or equal to zero the chart will be stopped.

Parameters:
rate - The memory history sampling rate to be used.
Returns:
This Memory_Chart.

Stop

public void Stop()
Stop the memory chart.

Memory sampling will be stopped. This is the same as setting the sampling rate to zero.


Start

public void Start()
Start the chart memory sampling.

If the current sampling rate is zero and the previous rate was non-zero, the memory history is cleared and its sampling rate is reset to the previous rate.


Rate

public int Rate()
Get the memory sampling rate.

Returns:
The current memory history sampling rate.

Previous_Rate

public int Previous_Rate()
Get the previous memory sampling rate.

Returns:
The previous memory history sampling rate. This will be zero only if there was no non-zero previous sampling rate.

stateChanged

public void stateChanged(ChangeEvent event)
The ChangeListener interface method.

The action is to repaint the component.

Specified by:
stateChanged in interface ChangeListener

Free_Memory

public static long Free_Memory()
Get the amount of memory allocated by the Java runtime environment but not currently in use.

Returns:
The amount, in bytes, of allocated but free memory.
See Also:
Memory_History.Available_Memory()

Allocated_Memory

public static long Allocated_Memory()
Get the amount of memory currently in use by the Java runtime environment.

Returns:
The amount, in bytes, of allocated memory.
See Also:
Memory_History.Available_Memory()

Available_Memory

public static long Available_Memory()
Get the total amount of memory available to the Java runtime environment.

Returns:
The total amount of memory, in bytes, available to the Java runtime environment.
See Also:
Memory_History.Available_Memory()

setUI

public void setUI(Memory_ChartUI UI)
Set the graphical user interface (UI) delegate for the component.

Parameters:
UI - A Memory_ChartUI object that will paint the component and handle other user interface events.
See Also:
JComponent.setUI(ComponentUI)

updateUI

public void updateUI()
Set the user interface delegate to the ComponentUI found by the UIManger for this component.

This component is invalidated.

Overrides:
updateUI in class JComponent
See Also:
getUIClassID()

getUIClassID

public String getUIClassID()
Get the ComponentUI class identification for this component.

Overrides:
getUIClassID in class JComponent
Returns:
The String "Memory_ChartUI".

PIRL

Copyright (C) \ 2003-2009 Bradford Castalia, University of Arizona