com.jrockit.memleak
Interface IMemLeak

All Known Implementing Classes:

AbstractMemLeak, MemLeakAdapter, MemLeakR26, MemLeakR28

public interface IMemLeak

Public API for the memory leak detection system in JRockit.

Author:

Staffan Larsen, Helena Åberg Östlund, Markus Persson

Field Summary

static int	FOREVER Used as timeout when no timeout is wanted.
static java.lang.String	META_IGNORED_REPLY_BYTES Key for getMetaData(Object) to obtain the number of bytes that was ignored or skipped while parsing replies, as a Long.
static java.lang.String	META_KNOWN_KEYS Key for getMetaData(Object) to obtain a Collection of all known keys.
static java.lang.String	META_READ_BYTES Key for getMetaData(Object) to obtain the number of read bytes as a Long.
static java.lang.String	META_SERVER_PORT Key for getMetaData(Object) to obtain the server port as an Integer.
static java.lang.String	META_SHORT_PROTOCOL_NAME Key for getMetaData(Object) to obtain the protocol name as a String.
static int	OBJECT_ID_INVALID An object id that is invalid.
static int	OBJECT_ID_NULL An object reference that is null gets this id.
static int	UNLIMITED_DEPTH Used as maximum depth for path to root when wanting to go as far back as the implementation can handle.
static int	UNLIMITED_INSTANCES Used as maximum number of instances/relations when all are wanted.
static long	UNLIMITED_SIZE Used as maximum size in bytes, for example as keep-alive-size, when no limit is wanted.

Method Summary

void	deleteAllObjectIds() Delete all object IDs.
void	deleteObjectId(int objectId) Delete the given object ID.
void	deleteObjectId(IObjectSpecifier objectSpec) FIXME: Fix comments, rename to dropRef() or similar.
IResult<java.lang.Void>	deleteObjectIds(int... objectIds) Delete the object IDs in objectIds.
void	destroy() Destroy the MemLeak.
void	disableAllocTraces() Stop sending allocation traces.
void	doFullGC() Cause a full Garbage Collect to happen on the server.
void	enableAllocTracesForClass(ITypeSpecifier type, int bufferSize, int interval, AllocTraceCallback callback) Enable traces for allocations of a certain type.
void	enableAllocTracesForClass(java.lang.String type, int bufferSize, int interval, AllocTraceCallback callback) Enable traces for allocations of a certain type.
int	getAllocTraceFrequency() Get the current allocation trace report interval.
IResult<IValue[]>	getArrayData(IObjectSpecifier objectSpec, int from, int len) Get the data from an array.
int	getArrayLength(IObjectSpecifier objectSpec) Get the length of an array.
IClassRef[]	getClasses(ITypeSpecifier specifier, Policy policy) Requires Feature.CLASS_IDS.
IClassRef[]	getClasses(java.lang.String className, Policy policy) Requires Feature.CLASS_IDS.
IClassInfo	getClassInfo(IClassRef classRef) Requires Feature.CLASS_NAME_OF_OBJECT.
java.util.Set<Feature>	getFeatures()
IResult<IFieldValue[]>	getFieldValues(IObjectSpecifier objectSpec) Get values and names for all fields in the object identified by objectSpec.
IHeapHistogram	getHeapHistogram() Get a histogram of the heap.
double	getHistogramCutoff() Get the cutoff point for types in the heap histograms.
ITruncatable<IRelationshipInfo>	getInstanceRelationships(ITypeSpecifier fromType, ITypeSpecifier toType, int maxRelations, long stopAt, int maxMillis) Get all instances of fromType that points to instances of toType.
ITruncatable<IRelationshipInfo>	getInstanceRelationships(java.lang.String fromType, java.lang.String toType, int maxRelations, long stopAt, int maxMillis) Get all instances of fromType that points to instances of toType.
ITruncatable<IObjectInfo>	getInstances(IClassRef classRef, int maxInstances) Requires Feature.INSTANCES_OF_TYPE.
IInstanceReferrers	getInstancesPointingTo(IObjectSpecifier objectSpec, Policy policy) Find all instances pointing to this object id.
IResult<LimitedNumber>	getKeepAliveSizeOf(IObjectSpecifier objectSpec, long stopAt) Get the total size of all objects held on to by this object (the transitive closure).
ITruncatable<IArraySizeInfo>	getLargestArrays(ITypeSpecifier type) Get the 10 largest arrays on the heap.
ITruncatable<IArraySizeInfo>	getLargestArrays(java.lang.String type) Get the 10 largest arrays on the heap.
ITypeHeapInfo<IClassInfo>	getLastTypeHeapInfo(IClassInfo classInfo, Policy policy)
ITypeHeapInfo<?>	getLastTypeHeapInfo(java.lang.String refType, Policy policy)
java.lang.Object	getMetaData(java.lang.Object key) Obtain meta data for this connection.
IResult<IObjectInfo>	getObjectInfo(IObjectSpecifier objectSpec) Requires Feature.CLASS_NAME_OF_OBJECT.
ITruncatable<IInstanceReferrers>	getPathPointingTo(IObjectSpecifier objectSpec, int maxDepth, int maxMillis) Find a path from a GC root to the object denoted by objectSpec.
<S> S	getService(java.lang.Class<S> interfaceClass) Return the service interface of type interfaceClass, if supported.
IResult<IFieldValue[]>	getStaticFields(IClassRef classRef) Get values and names for all static fields in the class identified by classRef.
IPointToTypeInfo[]	getTypesPointingTo(ITypeSpecifier type, Policy policy) Find which types contain references to another type.
IPointToTypeInfo[]	getTypesPointingTo(java.lang.String type, Policy policy) Find which types contain references to another type.
boolean	hasFeatures(Feature... features)
boolean	isAllocTracesEnabled() Check if allocation traces are already enabled.
boolean	isConnected() Returns true if we're connected to a (JRockit) server, false otherwise.
boolean	isTrendAnalysisEnabled() Check whether trend analysis is enabled on the server.
void	pollAllocationTraces() If allocation traces is enabled, poll the buffer on the server for any traces not yet sent to the client.
boolean	pollDiscardedObjects() If supported, poll the server for objects (and classes) that have been garbage collected.
void	setAllocTraceFrequency(int reportInterval) Changes the number of allocations that has to occur before an allocation trace will be reported.
void	setDisconnectCallback(DisconnectCallback disconnectCallback) Sets the callback called if we're disconnected because communication with the server fails.
void	setHistogramCutoff(double histogramCutoff) Set the cutoff point for types in the heap histograms (applicable both to getHeapHistogram and setTrendAnalysisEnabled).
void	setTrendAnalysisCallback(TrendAnalysisCallback cb) Sets the callback that will be called, with the latest trend analysis, for each Garbage Collect that occurs when trend analysis is enabled.
void	setTrendAnalysisEnabled(boolean enabled) Enable or disable trend analysis.

Field Detail

UNLIMITED_DEPTH

static final int UNLIMITED_DEPTH

Used as maximum depth for path to root when wanting to go as far back as the implementation can handle.

See Also:

Constant Field Values

UNLIMITED_INSTANCES

static final int UNLIMITED_INSTANCES

Used as maximum number of instances/relations when all are wanted.

See Also:

Constant Field Values

UNLIMITED_SIZE

static final long UNLIMITED_SIZE

Used as maximum size in bytes, for example as keep-alive-size, when no limit is wanted.

See Also:

Constant Field Values

FOREVER

static final int FOREVER

Used as timeout when no timeout is wanted.

See Also:

Constant Field Values

OBJECT_ID_INVALID

static final int OBJECT_ID_INVALID

An object id that is invalid. Can be returned instead of an object id if the object id has been deleted. (Or instead of a class id if class IDs are unsupported or the class ID is not known. Subject to change.)

See Also:

Constant Field Values

OBJECT_ID_NULL

static final int OBJECT_ID_NULL

An object reference that is null gets this id.

See Also:

Constant Field Values

META_KNOWN_KEYS

static final java.lang.String META_KNOWN_KEYS

Key for getMetaData(Object) to obtain a Collection of all known keys.

See Also:

Constant Field Values

META_SHORT_PROTOCOL_NAME

static final java.lang.String META_SHORT_PROTOCOL_NAME

Key for getMetaData(Object) to obtain the protocol name as a String.

See Also:

Constant Field Values

META_SERVER_PORT

static final java.lang.String META_SERVER_PORT

Key for getMetaData(Object) to obtain the server port as an Integer.

See Also:

Constant Field Values

META_READ_BYTES

static final java.lang.String META_READ_BYTES

Key for getMetaData(Object) to obtain the number of read bytes as a Long.

See Also:

Constant Field Values

META_IGNORED_REPLY_BYTES

static final java.lang.String META_IGNORED_REPLY_BYTES

Key for getMetaData(Object) to obtain the number of bytes that was ignored or skipped while parsing replies, as a Long. This is mostly a debugging help to detect protocol implementation errors.

See Also:

Constant Field Values

Method Detail

getMetaData

java.lang.Object getMetaData(java.lang.Object key)
                             throws SpiException

Obtain meta data for this connection. The keys are either META_* constants of this interface or implementation specific. Implementations unaware of the given key (including META_* constants) should return null. Used mainly for diagnostic purposes.

Parameters:

key - The kind of meta data to return

Returns:

the meta data of that kind or null

Throws:

SpiException

getFeatures

java.util.Set<Feature> getFeatures()

Returns:

a Set containing the Features this IMemLeak instance supports.

hasFeatures

boolean hasFeatures(Feature... features)

Parameters:

features -

Returns:

true iff all the given features are supported by this instance.

getService

<S> S getService(java.lang.Class<S> interfaceClass)

Return the service interface of type interfaceClass, if supported. (Service interfaces roughly corresponds to Features, and future versions of Memleak may unify these two concepts further.)

Type Parameters:

S -

Parameters:

interfaceClass -

Returns:

an instance of S, or null if the service isn't supported.

setTrendAnalysisCallback

void setTrendAnalysisCallback(TrendAnalysisCallback cb)
                              throws SpiException

Sets the callback that will be called, with the latest trend analysis, for each Garbage Collect that occurs when trend analysis is enabled.

This likely won't have any effect without Feature.TREND_ANALYSIS.

Parameters:

cb - the callback

Throws:

SpiException

setTrendAnalysisEnabled

void setTrendAnalysisEnabled(boolean enabled)
                             throws java.lang.IllegalStateException,
                                    SpiException

Enable or disable trend analysis.

Requires Feature.TREND_ANALYSIS.

Parameters:

enabled -

Throws:

java.lang.IllegalStateException - if no callback has been registered

SpiException

isTrendAnalysisEnabled

boolean isTrendAnalysisEnabled()
                               throws SpiException

Check whether trend analysis is enabled on the server.

Requires Feature.TREND_ANALYSIS to ever return true.

Returns:

whether trend anlysis is enabled on the server

Throws:

SpiException

getHeapHistogram

IHeapHistogram getHeapHistogram()
                                throws SpiException

Get a histogram of the heap. Sum of size and instances for each type.

Returns:

a histogram of the heap

Throws:

SpiException

setHistogramCutoff

void setHistogramCutoff(double histogramCutoff)
                        throws java.lang.IllegalArgumentException

Set the cutoff point for types in the heap histograms (applicable both to getHeapHistogram and setTrendAnalysisEnabled). Types which occupy less than this much of the total heap will not be shown in the histograms. 1.0 cuts off everything. 0 doesn't cut off anything.

Parameters:

histogramCutoff - Which types to leave out of the histograms. 0 means including all types, 0.05 means including types occupying more than 5 percent of the heap, and 1 effectively means disregarding all types.

Throws:

java.lang.IllegalArgumentException - if the cutoff is less than zero or larger than 1.

See Also:

setTrendAnalysisEnabled(boolean), getHeapHistogram()

getHistogramCutoff

double getHistogramCutoff()

Get the cutoff point for types in the heap histograms.

Returns:

the current cutoff point

See Also:

setHistogramCutoff(double)

getTypesPointingTo

IPointToTypeInfo[] getTypesPointingTo(java.lang.String type,
                                      Policy policy)
                                      throws OperationException,
                                             SpiException

Find which types contain references to another type. For example: "which types contain references to [C?".

Note that null may be returned, if the policy allows it.

Parameters:

type - the type to look for

policy - the policy to use

Returns:

information about which types contain references to type , or null according to policy

Throws:

OperationException

SpiException

getTypesPointingTo

IPointToTypeInfo[] getTypesPointingTo(ITypeSpecifier type,
                                      Policy policy)
                                      throws GarbageCollectedException,
                                             OperationException,
                                             SpiException

Find which types contain references to another type. For example: "which types contain references to [C?".

Note that null may be returned, if the policy allows it.

Parameters:

type - the type to look for

policy - the policy to use

Returns:

information about which types contain references to type , or null according to policy

Throws:

GarbageCollectedException

OperationException

SpiException

getLargestArrays

ITruncatable<IArraySizeInfo> getLargestArrays(java.lang.String type)

Get the 10 largest arrays on the heap. If the given array type does not have any instances, but is loaded, a zero length array is returned. If the type isn't loaded, or doesn't exist, a reason of ITruncatable.Reason.EMPTY_REPLY is returned. (Since no classloader is specified, these last two cases are not easily differentiated.) Non-array types may give a NotAnArrayException as reason.

Parameters:

type - the type of the arrays

Returns:

an ITruncatable with IArraySizeInfos on the largest arrays or a reason of ITruncatable.Reason.EMPTY_REPLY if the type isn't loaded

getLargestArrays

ITruncatable<IArraySizeInfo> getLargestArrays(ITypeSpecifier type)

Get the 10 largest arrays on the heap. If the given array type does not have any instances, but is loaded, a zero length array is returned. If the type isn't loaded, or doesn't exist, a reason of ITruncatable.Reason.EMPTY_REPLY is returned. (Since a class loader may or may not be specified, these last two cases are not easily differentiated.) Non-array types may give a NotAnArrayException as reason.

Parameters:

type - the type of the arrays

Returns:

an ITruncatable with IArraySizeInfos on the largest arrays or a reason of ITruncatable.Reason.EMPTY_REPLY if the type isn't loaded

getInstancesPointingTo

IInstanceReferrers getInstancesPointingTo(IObjectSpecifier objectSpec,
                                          Policy policy)
                                          throws GarbageCollectedException,
                                                 SpiException

Find all instances pointing to this object id. The methods in the returned IInstanceReferrers.getThreadRoots() are not accurate but a best guess, considering what is on the stack.

Note that null may be returned, if the policy allows it.

Parameters:

objectSpec - an object specifier

policy - the policy to use

Returns:

information about all instances pointing to this object, or null according to policy

Throws:

GarbageCollectedException

SpiException

getPathPointingTo

ITruncatable<IInstanceReferrers> getPathPointingTo(IObjectSpecifier objectSpec,
                                                   int maxDepth,
                                                   int maxMillis)
                                                   throws GarbageCollectedException,
                                                          OperationException,
                                                          SpiException

Find a path from a GC root to the object denoted by objectSpec. Note that maxDepth is interpreted in such a way that if there's any root at most this many steps away, a root will always be returned. However, roots further away may still be reported due to implementation details. Perhaps minDepth or simply depth would be a better parameter name.

Requires Feature.INSTANCE_PATHS_TO_ROOT.

Parameters:

objectSpec - the object to find a root for

maxDepth - the maximum number of backward steps that will be taken to find a root, use UNLIMITED_DEPTH for no limit

maxMillis - the maximum time in milliseconds to spend finding a root, not including any time required by garbage collection, use FOREVER for no limit

Returns:

an array of IInstanceReferrers denoting a path from a root to the given IObjectSpecifier.

Throws:

GarbageCollectedException

OperationException

SpiException

getInstanceRelationships

ITruncatable<IRelationshipInfo> getInstanceRelationships(java.lang.String fromType,
                                                         java.lang.String toType,
                                                         int maxRelations,
                                                         long stopAt,
                                                         int maxMillis)
                                                         throws OperationException,
                                                                SpiException

Get all instances of fromType that points to instances of toType.

The returned array will be no larger than maxRelations (it may be smaller if there are fewer relations).

The returned array will be sorted on the keep-alive-size. This means that if keep-alive-sizes are calculated, and maxRelations is also set, only the instances with the highest keep-alive-size will be returned.

If stopAt is >= 0 the maximum keep-alive-size reported in each IRelationshipInfo will be stopAt (this is to limit the amount of objects traversed to find the size). Specifying zero will effectively disable the keep-alive-size calculation, and the array will effectively be unsorted.

If stopAt is UNLIMITED_SIZE, there is no max for keep-alive-size, which means the actual keep-alive-size will be returned.

Parameters:

fromType -

toType -

maxRelations - maximum number of relations to return. To return all relations, use UNLIMITED_INSTANCES (this can possibly return a very large array).

stopAt - the limit in bytes for keep alive size calculation, see above

maxMillis - specifies the maximum amount of time (in milliseconds) the server should spend completing the request. If more time has elapsed the server will stop processing the request and return the data as it is at that time. A value of FOREVER means infinite time.

Returns:

an ITruncatable with IRelationshipInfos on all instances of fromType that points to instances of toType.

Throws:

OperationException

SpiException

See Also:

getKeepAliveSizeOf(IObjectSpecifier, long)

getInstanceRelationships

ITruncatable<IRelationshipInfo> getInstanceRelationships(ITypeSpecifier fromType,
                                                         ITypeSpecifier toType,
                                                         int maxRelations,
                                                         long stopAt,
                                                         int maxMillis)
                                                         throws OperationException,
                                                                SpiException

Get all instances of fromType that points to instances of toType.

The returned array will be no larger than maxRelations (it may be smaller if there are fewer relations).

The returned array will be sorted on the keep-alive-size. This means that if keep-alive-sizes are calculated, and maxRelations is also set, only the instances with the highest keep-alive-size will be returned.

If stopAt is >= 0 the maximum keep-alive-size reported in each IRelationshipInfo will be stopAt (this is to limit the amount of objects traversed to find the size). Specifying zero will effectively disable the keep-alive-size calculation, and the array will effectively be unsorted.

If stopAt is UNLIMITED_SIZE, there is no max for keep-alive-size, which means the actual keep-alive-size will be returned.

Parameters:

fromType -

toType -

maxRelations - maximum number of relations to return. To return all relations, use UNLIMITED_INSTANCES (this can possibly return a very large array).

stopAt - the limit in bytes for keep alive size calculation, see above

maxMillis - specifies the maximum amount of time (in milliseconds) the server should spend completing the request. If more time has elapsed the server will stop processing the request and return the data as it is at that time. A value of FOREVER means infinite time.

Returns:

an ITruncatable with IRelationshipInfos on all instances of fromType that points to instances of toType.

Throws:

OperationException

SpiException

See Also:

getKeepAliveSizeOf(IObjectSpecifier, long)

getKeepAliveSizeOf

IResult<LimitedNumber> getKeepAliveSizeOf(IObjectSpecifier objectSpec,
                                          long stopAt)

Get the total size of all objects held on to by this object (the transitive closure). If stopAt >= 0 than counting will stop if the total size is larger than stopAt.

Parameters:

objectSpec - an object id

stopAt - the limit in bytes for keep alive size calculation, see above

Returns:

An IResult whose get() method will give the total size in bytes of all objects held on to by this object, limited by stopAt.

getFieldValues

IResult<IFieldValue[]> getFieldValues(IObjectSpecifier objectSpec)

Get values and names for all fields in the object identified by objectSpec.

Parameters:

objectSpec - an object specifier

Returns:

An IResult whose get() method either will return an array of IFieldValues representing the fields, or throw an exception.

getStaticFields

IResult<IFieldValue[]> getStaticFields(IClassRef classRef)

Get values and names for all static fields in the class identified by classRef.

Parameters:

classRef - a class reference

Returns:

An IResult whose get() method either will return an array of IFieldValues representing the static fields, or throw an exception.

getArrayLength

int getArrayLength(IObjectSpecifier objectSpec)
                   throws GarbageCollectedException,
                          SpiException

Get the length of an array.

Parameters:

objectSpec - the array

Returns:

the length of the array

Throws:

GarbageCollectedException

SpiException

getArrayData

IResult<IValue[]> getArrayData(IObjectSpecifier objectSpec,
                               int from,
                               int len)

Get the data from an array.

Parameters:

objectSpec - the array

from - starting index

len - how many elements to fetch

Returns:

An IResult whose IResult.get() either will return an array of IValues representing the array elements, or throw an exception.

Throws:

java.lang.IllegalArgumentException - if objectId is not valid

java.lang.IndexOutOfBoundsException - if from and/or len are invalid values

enableAllocTracesForClass

void enableAllocTracesForClass(java.lang.String type,
                               int bufferSize,
                               int interval,
                               AllocTraceCallback callback)
                               throws java.lang.IllegalStateException,
                                      SpiException

Enable traces for allocations of a certain type. This will cause all methods that allocate objects of this type to be recompiled with instrumentation. Traces can only be enabled for one type at a time.

Requires Feature.ALLOCATION_TRACES.

Parameters:

type - the type to look for. The type should be in VM format, i.e. dots should be converted to slashes. java.lang.String -> java/lang/String.

bufferSize - how many different traces that should be collected on the server before sending them over.

interval - initial report interval - only every interval allocation is looked at. This can later be changed by calling setAllocTraceFrequency(int).

callback - callback that receives the traces.

Throws:

java.lang.IllegalStateException - if allocation traces is already enabled.

SpiException

See Also:

setAllocTraceFrequency(int)

enableAllocTracesForClass

void enableAllocTracesForClass(ITypeSpecifier type,
                               int bufferSize,
                               int interval,
                               AllocTraceCallback callback)
                               throws java.lang.IllegalStateException,
                                      SpiException

Enable traces for allocations of a certain type. This will cause all methods that allocate objects of this type to be recompiled with instrumentation. Traces can only be enabled for one type at a time.

Requires Feature.ALLOCATION_TRACES.

Parameters:

type - specifier of the type to look for.

bufferSize - how many different traces that should be collected on the server before sending them over.

interval - initial report interval - only every interval allocation is looked at. This can later be changed by calling setAllocTraceFrequency(int).

callback - callback that receives the traces.

Throws:

java.lang.IllegalStateException - if allocation traces is already enabled.

SpiException

See Also:

setAllocTraceFrequency(int)

pollAllocationTraces

void pollAllocationTraces()
                          throws java.lang.IllegalStateException,
                                 SpiException

If allocation traces is enabled, poll the buffer on the server for any traces not yet sent to the client. The callback set with enableAllocTracesForClass will be called. This will empty the buffer.

Throws:

java.lang.IllegalStateException

SpiException

isAllocTracesEnabled

boolean isAllocTracesEnabled()
                             throws SpiException

Check if allocation traces are already enabled.

Requires Feature.ALLOCATION_TRACES to ever return true.

Returns:

whether allocation traces are already enabled

Throws:

SpiException

disableAllocTraces

void disableAllocTraces()
                        throws SpiException

Stop sending allocation traces. This will cause methods that have been instrumented to revert back to the original code.

Requires Feature.ALLOCATION_TRACES to actually do anything.

Throws:

SpiException

setAllocTraceFrequency

void setAllocTraceFrequency(int reportInterval)
                            throws SpiException

Changes the number of allocations that has to occur before an allocation trace will be reported.

Gathering every allocation trace is sometimes (most times) too expensive. By skipping a number of allocations before reporting, the cost will be reduced. For example, an interval value of 1 will report every allocation, 2 will report every other allocation, and 30 will report every 30th allocation.

Requires Feature.ALLOCATION_TRACES.

Parameters:

reportInterval - the number of allocations that has to occur before an allocation trace will be reported

Throws:

SpiException

getAllocTraceFrequency

int getAllocTraceFrequency()
                           throws SpiException

Get the current allocation trace report interval.

Requires Feature.ALLOCATION_TRACES for the return value to be of any significance.

Returns:

the number of allocations that has to occur before an allocation trace will be reported

Throws:

SpiException

doFullGC

void doFullGC()
              throws SpiException

Cause a full Garbage Collect to happen on the server. This will clear out objects referenced only by soft references.

Requires Feature.GC_TRIGGER to actually do anything.

Throws:

SpiException

deleteObjectId

void deleteObjectId(IObjectSpecifier objectSpec)
                    throws SpiException

FIXME: Fix comments, rename to dropRef() or similar. Delete the given object ID. Every object (or class) ID returned from the other methods must be deleted exactly once. Once deleted, an ID may be reused at any time.

Requires Feature.DELETE_OBJECT_ID.

Parameters:

objectSpec - an object specifier

Throws:

SpiException

deleteObjectId

void deleteObjectId(int objectId)
                    throws SpiException

Delete the given object ID. Every object (or class) ID returned from the other methods must be deleted exactly once. Once deleted, an ID may be reused at any time.

Requires Feature.DELETE_OBJECT_ID.

Parameters:

objectId - an object ID

Throws:

SpiException

deleteObjectIds

IResult<java.lang.Void> deleteObjectIds(int... objectIds)

Delete the object IDs in objectIds. Every object (or class) ID returned from the other methods must be deleted exactly once. Once deleted, an ID may be reused at any time.

Requires Feature.DELETE_OBJECT_ID.

Parameters:

objectIds - an array of object IDs

Returns:

An IResult whose get() method will return null

deleteAllObjectIds

void deleteAllObjectIds()
                        throws SpiException

Delete all object IDs. Every object (or class) ID returned from the other methods must be deleted exactly once. Once deleted, an ID may be reused at any time.

Requires Feature.DELETE_ALL_OBJECT_IDS.

Throws:

SpiException

pollDiscardedObjects

boolean pollDiscardedObjects()

If supported, poll the server for objects (and classes) that have been garbage collected. All INotificationService listeners will be notified with IObjectInfos and IClassInfos for any GC:d objects. This will also prevent those infos from being reachable from this SPI.

Returns:

true if this operation is supported.

destroy

void destroy()
             throws java.io.IOException

Destroy the MemLeak. This will delete all object ids that have not yet been deleted. No calls to MemLeak are allowed after destroy is called.

Throws:

java.io.IOException

setDisconnectCallback

void setDisconnectCallback(DisconnectCallback disconnectCallback)

Sets the callback called if we're disconnected because communication with the server fails. Note that this callback is only called when the communication fails. Normal, client initiated, termination of the communication will not result in the disconnect callback being called.

This likely won't have any effect for implementations that doesn't require any external state.

Parameters:

disconnectCallback - the callback that handles the exception that was thrown due to the communication error.

isConnected

boolean isConnected()

Returns true if we're connected to a (JRockit) server, false otherwise.

Implementations that doesn't require any external state should probably return true here (always).

Returns:

true or false

getObjectInfo

IResult<IObjectInfo> getObjectInfo(IObjectSpecifier objectSpec)

Requires Feature.CLASS_NAME_OF_OBJECT.

Parameters:

objectSpec - an IObjectSpecifier of an instance

Returns:

An IResult whose get() method either will return an IObjectInfo representing the instance, or throw an exception.

getClassInfo

IClassInfo getClassInfo(IClassRef classRef)
                        throws GarbageCollectedException,
                               SpiException

Requires Feature.CLASS_NAME_OF_OBJECT.

Parameters:

classRef - an IClassRef of a class

Returns:

the IClassInfo of the class

Throws:

GarbageCollectedException

SpiException

getClasses

IClassRef[] getClasses(java.lang.String className,
                       Policy policy)
                       throws SpiException

Requires Feature.CLASS_IDS.

Note that null may be returned, if the policy allows it.

Parameters:

className - a class name

policy - the policy to use

Returns:

Class ID:s of all classes with name className in all class loaders, or null according to policy

Throws:

SpiException

getClasses

IClassRef[] getClasses(ITypeSpecifier specifier,
                       Policy policy)
                       throws SpiException

Requires Feature.CLASS_IDS.

Note that null may be returned, if the policy allows it.

Parameters:

specifier - a type specifier

policy - the policy to use

Returns:

Class ID:s of all classes specified by specifier, or null according to policy

Throws:

SpiException

getInstances

ITruncatable<IObjectInfo> getInstances(IClassRef classRef,
                                       int maxInstances)
                                       throws GarbageCollectedException,
                                              SpiException

Requires Feature.INSTANCES_OF_TYPE.

Parameters:

classRef - a type reference

maxInstances - the maximum number of instances to return, use UNLIMITED_INSTANCES to return all instances

Returns:

an ITruncatable with IObjectInfos of all instances of classRef

Throws:

GarbageCollectedException - if the class designated by classRef has been garbage collected.

SpiException

getLastTypeHeapInfo

ITypeHeapInfo<IClassInfo> getLastTypeHeapInfo(IClassInfo classInfo,
                                              Policy policy)

Parameters:

classInfo -

policy - a time stamp in milliseconds

Returns:

the last received heap info, or null if none has been received.

getLastTypeHeapInfo

ITypeHeapInfo<?> getLastTypeHeapInfo(java.lang.String refType,
                                     Policy policy)

Parameters:

refType -

policy - a time stamp in milliseconds

Returns:

the last received heap info, or null if none has been received.