PIRL.Viewers

## Class Memory_Chart

- java.lang.Object
- - java.awt.Component
  - - java.awt.Container
    - - javax.swing.JComponent
      - - 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.

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

Fields
`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

Constructors
Constructor and Description
`Memory_Chart()` Construct an idle Memory_Chart.
`Memory_Chart(int sampling_rate)` Construct a Memory_Chart that samples at a specified rate.

### Method Summary

Methods
`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, isPaintingOrigin, 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, 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, transferFocusBackward, 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".