com.bea.jvm
Interface GarbageCollector

All Superinterfaces:
Describable, JVMComponent

public interface GarbageCollector
extends JVMComponent

This interface represents the Garbage Collector of the JVM. (The GarbageCollection subsystem.)

Author:
Calle Wilund, Marcus Hirt

Method Summary
 void addFinalizationListener(FinalizationListener listener)
          Add listener to be notified whenever an Object has been finalized.
 void addFinalizationListener(FinalizationListener listener, boolean onlyFailed)
          Add listener to be notified whenever an Object has been finalized.
 void addGarbageCollectionListener(GarbageCollectionListener listener)
          Adds a listener to be notified whenever a Garbage Collection run has been performed.
 void addGarbageCollectionStrategyChangeListener(GarbageCollectionStrategyChangeListener listener)
          Adds a listener for the strategy change event (@see GarbageCollectionStrategyChangeEvent).
 java.lang.String getDescription()
          A short description of the GC algorithm in use.
 java.util.Collection getGarbageCollectionStrategies()
          Returns a collection of currently available GarbageCollectionStrategies (@see GarbageCollectionStrategy).
 GarbageCollectionStrategy getGarbageCollectionStrategy()
          Returns the strategy currently being employed by the GarbageCollector.
 long getLastGCEnd()
          Returns the time the last Garbage Collection run started.
 long getLastGCStart()
          Returns the time the last Garbage Collection run started.
 long getNurserySize()
          Returns the size of the nursery/youngspace in bytes.
 long getTotalGarbageCollectionCount()
          Returns the total number of collection runs performed so far.
 long getTotalGarbageCollectionTime()
          Returns the total time spent Garabage Collecting so far.
 boolean hasCompaction()
          Returns true if this Garbage Collector compacts the heap.
 boolean isConcurrent()
          Returns true if this Garbage Collector at some point collects garbage concurrently, i.e. in a separate thread running concurrently with the other threads.
 boolean isDynamic()
          Returns true if the GC system is running in a dynamic mode, i.e. a mode that allows the strategy to change.
 boolean isGenerational()
          Returns true if this memory model at some point uses a nursery/ young-space.
 boolean isIncremental()
          Returns true if this Garbage Collector collects garbage incrementally (in small steps, train algorithm or similar).
 boolean isParallel()
          Returns true if this Garbage Collector at some point runs in parallel on several processors when collecting garbage.
 boolean isSelfOptimizing()
          Returns true if the GC system is running in a mode that will automatically choose GarbageCollectionStrategy for you.
 void removeFinalizationListener(FinalizationListener listener)
          Removes the specified listener.
 void removeGarbageCollectionListener(GarbageCollectionListener listener)
          Removes the specified GarbageCollectionListener.
 void removeGarbageCollectionStrategyChangeListener(GarbageCollectionStrategyChangeListener listener)
          Removes a strategy change listener (@see GarbageCollectionStrategyChangeEvent).
 void setNurserySize(long nurserySize)
          Sets the nursery size.
 void suggestGarbageCollectionStrategy(GarbageCollectionStrategy strategy)
          Suggests a static garbage collector strategy to the system.
 

Method Detail

getDescription

public java.lang.String getDescription()
A short description of the GC algorithm in use. For example 'Generational Concurrent', 'Parallel' etc.

Specified by:
getDescription in interface Describable
Returns:
a short description of the GC.
See Also:
Describable.getDescription()

isGenerational

public boolean isGenerational()
                       throws NotAvailableException
Returns true if this memory model at some point uses a nursery/ young-space.

Returns:
true if this memory model at some point has a nursery.
Throws:
NotAvailableException - if this functionality isn't available in this JVM.

hasCompaction

public boolean hasCompaction()
                      throws NotAvailableException
Returns true if this Garbage Collector compacts the heap.

Returns:
true if this memory model uses compaction.
Throws:
NotAvailableException - if this functionality isn't available in this JVM.

isIncremental

public boolean isIncremental()
                      throws NotAvailableException
Returns true if this Garbage Collector collects garbage incrementally (in small steps, train algorithm or similar).

Returns:
true if this GC is incremental.
Throws:
NotAvailableException - if this functionality isn't available in this JVM.

isConcurrent

public boolean isConcurrent()
                     throws NotAvailableException
Returns true if this Garbage Collector at some point collects garbage concurrently, i.e. in a separate thread running concurrently with the other threads.

Returns:
true if the mark phase or the sweep phase is concurrent.
Throws:
NotAvailableException - if this functionality isn't available in this JVM.

isParallel

public boolean isParallel()
                   throws NotAvailableException
Returns true if this Garbage Collector at some point runs in parallel on several processors when collecting garbage.

Returns:
true if the mark phase or the sweep phase is parallel.
Throws:
NotAvailableException - if this functionality isn't available in this JVM.

getTotalGarbageCollectionCount

public long getTotalGarbageCollectionCount()
                                    throws NotAvailableException
Returns the total number of collection runs performed so far.

Returns:
the total number of GCs perfomed so far.
Throws:
NotAvailableException - if this functionality isn't available in this JVM.

getLastGCStart

public long getLastGCStart()
                    throws NotAvailableException
Returns the time the last Garbage Collection run started.

Returns:
the time the last GC started.
Throws:
NotAvailableException - if this functionality isn't available in this JVM.

getLastGCEnd

public long getLastGCEnd()
                  throws NotAvailableException
Returns the time the last Garbage Collection run started.

Returns:
the time the last GC ended.
Throws:
NotAvailableException - if this functionality isn't available in this JVM.

getTotalGarbageCollectionTime

public long getTotalGarbageCollectionTime()
                                   throws NotAvailableException
Returns the total time spent Garabage Collecting so far.

Returns:
total time spent in GC, in ms, so far.
Throws:
NotAvailableException - if this functionality isn't available in this JVM.

getNurserySize

public long getNurserySize()
                    throws NotAvailableException
Returns the size of the nursery/youngspace in bytes.

Returns:
the size of the nursery in bytes.
Throws:
NotAvailableException - if this functionality isn't available in this Garbage Collector or JVM.

setNurserySize

public void setNurserySize(long nurserySize)
                    throws NotAvailableException
Sets the nursery size. The new size may not be smaller than the minimum allowed nursery size (currently 8 kB) or larger than 95% of the maximum heap size. Also the nursery size will be aligned on full pages. If a too small or too large value is given, the nursery size will be adjusted to a valid value. A non-aligned value will be aligned down to the closest page. Note that the nursery may shrink temporarily in runtime, as at most 95% of the free heap can be allocated for the nursery after an Old Garbage Collection.

Parameters:
nurserySize - the new size of the nursery.
Throws:
NotAvailableException - if the functionality isn't supported in this JVM, or if the current GarbageCollectionStrategy in use lacks a nursery (i.e. isGenerational() == false).

addGarbageCollectionListener

public void addGarbageCollectionListener(GarbageCollectionListener listener)
                                  throws NotAvailableException
Adds a listener to be notified whenever a Garbage Collection run has been performed.

Parameters:
listener - the listener to use.
Throws:
NotAvailableException - if this functionality isn't available in this JVM.

removeGarbageCollectionListener

public void removeGarbageCollectionListener(GarbageCollectionListener listener)
                                     throws NotAvailableException
Removes the specified GarbageCollectionListener. It will no longer be notified about GC events.

Parameters:
listener - the listener to remove.
Throws:
NotAvailableException - if this functionality isn't available in this JVM.

addFinalizationListener

public void addFinalizationListener(FinalizationListener listener)
                             throws NotAvailableException
Add listener to be notified whenever an Object has been finalized.

Parameters:
listener - the listener to receive events whenever an object is finalized.
Throws:
NotAvailableException - if this functionality isn't available in this JVM.

addFinalizationListener

public void addFinalizationListener(FinalizationListener listener,
                                    boolean onlyFailed)
                             throws NotAvailableException
Add listener to be notified whenever an Object has been finalized.

Parameters:
listener - the listener to add.
onlyFailed - whether to only send events for finalizers that fail (i.e. throw an exception).
Throws:
NotAvailableException - if this functionality isn't available in this JVM.

removeFinalizationListener

public void removeFinalizationListener(FinalizationListener listener)
                                throws NotAvailableException
Removes the specified listener.

Parameters:
listener - the listener to remove.
Throws:
NotAvailableException - if this functionality isn't available in this JVM.

getGarbageCollectionStrategies

public java.util.Collection getGarbageCollectionStrategies()
                                                    throws NotAvailableException
Returns a collection of currently available GarbageCollectionStrategies (@see GarbageCollectionStrategy). This can differ depending on the startup parameters and currently selected strategy.

Returns:
a Collection of the currently available GarbageCollectionStrategies.
Throws:
NotAvailableException - if not supported by the VM.

getGarbageCollectionStrategy

public GarbageCollectionStrategy getGarbageCollectionStrategy()
                                                       throws NotAvailableException
Returns the strategy currently being employed by the GarbageCollector.

Returns:
the strategy currently being employed by the GarbageCollector.
NotAvailableException

suggestGarbageCollectionStrategy

public void suggestGarbageCollectionStrategy(GarbageCollectionStrategy strategy)
                                      throws NotAvailableException
Suggests a static garbage collector strategy to the system. You have to be in the dynamic garbage collecting mode in order to call this method. When a valid garbage collector strategy is suggested and accepted, the garbage collector will leave the self-optimizing mode but still be dynamic. (i.e. will not automatically switch garbage collector, but still possible to suggest changes to.) Suggesting the null strategy will make the collector reenter the self-optimizing mode, which in turn will make the garbage collector switch strategy automatically again.

Note that:

Parameters:
strategy - the suggested garbage collector state.
Throws:
NotAvailableException - if this functionality isn't available in this Garbage Collector or JVM.

isDynamic

public boolean isDynamic()
                  throws NotAvailableException
Returns true if the GC system is running in a dynamic mode, i.e. a mode that allows the strategy to change.

Returns:
true if the GC system is running in a dynamic mode, i.e. a mode that allows the strategy to change.
Throws:
NotAvailableException - if this functionality isn't available in this Garbage Collector or JVM.

isSelfOptimizing

public boolean isSelfOptimizing()
                         throws NotAvailableException
Returns true if the GC system is running in a mode that will automatically choose GarbageCollectionStrategy for you. You can force the GC system to switch to this mode by suggesting null as strategy. (@see #suggestGarbageCollectionStrategy(GarbageCollectionStrategy))

Returns:
true if the system is in a self optimizing state.
Throws:
NotAvailableException - if this functionality isn't available in this Garbage Collector or JVM.

addGarbageCollectionStrategyChangeListener

public void addGarbageCollectionStrategyChangeListener(GarbageCollectionStrategyChangeListener listener)
                                                throws NotAvailableException
Adds a listener for the strategy change event (@see GarbageCollectionStrategyChangeEvent).

Parameters:
listener - the listener to add.
Throws:
NotAvailableException - if this functionality isn't available in this Garbage Collector or JVM.

removeGarbageCollectionStrategyChangeListener

public void removeGarbageCollectionStrategyChangeListener(GarbageCollectionStrategyChangeListener listener)
                                                   throws NotAvailableException
Removes a strategy change listener (@see GarbageCollectionStrategyChangeEvent).

Parameters:
listener - the listener to remove.
Throws:
NotAvailableException - if this functionality isn't available in this Garbage Collector or JVM.