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:

• Only GarbageCollectionStrategies returned by getGarbageCollectionStrategies() will be accepted as input to this method.
• This method may trigger a full GC.
• The swap, if possible, will take place during the next full GC. That is, it may not take place at all, depending on the memory profile of your program.
• This call is asynchronous. You need to listen to the StrategyChangeEvent to know that the change has taken place.
• You need to be in dynamic mode to be able to switch GC's.

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.