JProfiler API

com.jprofiler.api.platform.connection
Interface Connection


public interface Connection

The primary interface for retrieving profiling data from a profiled JVM or a saved snapshot.

All requests for new profiling data that has to be queried from the profiling agent are done by calling a method on a connection object.

See Also:
ConnectionFactory

Method Summary
 void close()
          Closes the connection and free all resources asscociated with this connection.
 Tree getAllocationHotspotBacktrace(ProfilingValue hotspot)
          Calculates the back traces for an allocation hot spot.
 AllocationHotspots getAllocationHotspots(Aggregation level, Liveness liveness, Descriptor[] classOrArrayDescriptors, boolean resetGc, boolean includeFiltered)
          Calculates the allocation hot spots for recorded objects of selected classes.
 AllocationHotspots getAllocationHotspots(Aggregation level, Liveness liveness, java.lang.String packageName, boolean resetGc, boolean includeFiltered)
          Calculates the allocation hot spots for recorded objects of a selected package.
 Tree getAllocationTree(Aggregation level, Liveness liveness, Descriptor[] classOrArrayDescriptors, boolean resetGc)
          Calculates the allocation tree for recorded objects of selected classes.
 Tree getAllocationTree(Aggregation level, Liveness liveness, java.lang.String packageName, boolean resetGc)
          Calculates the allocation tree for recorded objects of a selected package.
 Tree getCpuHotspotBacktrace(ProfilingValue hotspot)
          Calculates the back traces for a CPU hot spot.
 CpuHotspots getCpuHotspots(java.util.Collection<ThreadInfo> threads, Aggregation level, ThreadStatus status, boolean includeFiltered)
          Calculates CPU hot spots.
 Tree getCpuTree(java.util.Collection<ThreadInfo> threads, Aggregation level, ThreadStatus status)
          Calculates the cumulated call tree.
 InterceptorsInfo getInterceptorsInfo()
          Returns information about registered interceptors.
 Tree getPayloadHotspotBacktrace(ProfilingValue hotspot)
          Calculates the back traces for a payload hot spot.
 java.util.List<ProfilingValue> getPayloadHotspots(int payloadId, java.util.Collection<ThreadInfo> threads, Aggregation level, ThreadStatus status)
          Calculates hot spots for a non-method hot spot type.
 RecordedHeapUsage getRecordedHeapUsage(boolean resetGc)
          Calculates the heap usage for all classes of recorded objects in the JVM.
 java.util.Collection<ThreadInfo> getThreadInfos()
          Returns information about all threads (live and dead) in the JVM.
 java.util.Set<HeapValue> getTotalHeapUsage()
          Calculates the total heap usage for all classes in the JVM.
 void recordAllocations(boolean record)
          Starts or stops recording allocations.
 void recordCpuData(boolean record)
          Starts or stops recording CPU data.
 

Method Detail

close

void close()
Closes the connection and free all resources asscociated with this connection.


recordCpuData

void recordCpuData(boolean record)
Starts or stops recording CPU data. Initially, no CPU data is recorded.

Parameters:
record - whether to record CPU data or not

recordAllocations

void recordAllocations(boolean record)
Starts or stops recording allocations. Initially, no allocations are recorded. However, when profiling a Java 1.5 JVM (JVMTI), you can still use the getTotalHeapUsage() method to get a statistics of all classes and their instances.

Parameters:
record - whether to record allocations or not

getInterceptorsInfo

InterceptorsInfo getInterceptorsInfo()
Returns information about registered interceptors. Interceptors are registered with an InterceptorProvider.

Returns:
the information about registered interceptors
See Also:
Interceptor, InterceptorProvider

getCpuHotspots

CpuHotspots getCpuHotspots(java.util.Collection<ThreadInfo> threads,
                           Aggregation level,
                           ThreadStatus status,
                           boolean includeFiltered)
Calculates CPU hot spots. The result is analogous to the top level entries in the "Hot Spots" view of the JProfiler GUI.

Parameters:
threads - the threads for which to calculate the hot spots (see getThreadInfos()) or null if all threads should be cumulated
level - the aggregation level for the hot spots and the back traces
status - the thread status for the hot spots and the back traces
includeFiltered - whether calls to filtered classes should be separate hot spots (true) or be added to the calling methods (false)
Returns:
the CPU hot spots
See Also:
getCpuHotspotBacktrace(com.jprofiler.api.platform.structures.ProfilingValue)

getCpuHotspotBacktrace

Tree getCpuHotspotBacktrace(ProfilingValue hotspot)
Calculates the back traces for a CPU hot spot. The result is analogous to the back trace tree under a single top level entry in the "Hot Spots" view of the JProfiler GUI. Note that this method only works if the hotspot argument is a method hot spot.

Parameters:
hotspot - the hot spot for which to calculate the back trace
Returns:
the back traces as a tree
See Also:
getCpuHotspots

getPayloadHotspots

java.util.List<ProfilingValue> getPayloadHotspots(int payloadId,
                                                  java.util.Collection<ThreadInfo> threads,
                                                  Aggregation level,
                                                  ThreadStatus status)
Calculates hot spots for a non-method hot spot type. The result is analogous to the the top level entries in the "Hot Spots" view of the JProfiler GUI if you select a hot spot type other than methods.

Payload types are selected by their payload id which is either one of the PAYLOAD_* constants in Payload or the payload id of a registered interceptor, in the latter case the one-based index of the interceptor in the array returned by the InterceptorProvider. You can also get the payload id from InterceptorsInfo.getDescriptionToId().

The descriptor type of the ProfilingValue objects is either a PayloadDescriptor or a URLDescriptor.

Parameters:
payloadId - the id of the payload type for which to calculate the hot spots
threads - the threads for which to calculate the hot spots (see getThreadInfos()) or null if all threads should be cumulated
level - the aggregation level for the hot spots and the back traces
status - the thread status for the hot spots and the back traces
Returns:
the payload hot spots
See Also:
getPayloadHotspotBacktrace(com.jprofiler.api.platform.structures.ProfilingValue)

getPayloadHotspotBacktrace

Tree getPayloadHotspotBacktrace(ProfilingValue hotspot)
Calculates the back traces for a payload hot spot. The result is analogous to the back trace tree under a single top level entry in the "Hot Spots" view of the JProfiler GUI. Note that this method only works if the hotspot argument is a payload hot spot.

Parameters:
hotspot - the hot spot for which to calculate the back trace
Returns:
the back traces as a tree
See Also:
getPayloadHotspots

getCpuTree

Tree getCpuTree(java.util.Collection<ThreadInfo> threads,
                Aggregation level,
                ThreadStatus status)
Calculates the cumulated call tree. The result is analogous to the "Call Tree" view of the JProfiler GUI.

Parameters:
threads - the threads for which to calculate the call tree (see getThreadInfos()) or null if all threads should be cumulated
level - the aggregation level for the call tree
status - the thread status for the call tree
Returns:
the call tree

getThreadInfos

java.util.Collection<ThreadInfo> getThreadInfos()
Returns information about all threads (live and dead) in the JVM.

Returns:
the thread infos

getTotalHeapUsage

java.util.Set<HeapValue> getTotalHeapUsage()
Calculates the total heap usage for all classes in the JVM. The result is analogous to the "All Objects" view of the JProfiler GUI.

Returns:
the heap usage statistics

getRecordedHeapUsage

RecordedHeapUsage getRecordedHeapUsage(boolean resetGc)
Calculates the heap usage for all classes of recorded objects in the JVM. The result is analogous to the "Recorded Objects" view of the JProfiler GUI. You can also get information about garbage collected objects with this method if the allocation recording options in the profiling settings include GCed objects.

Parameters:
resetGc - whether to reset information about garbage collected objects after the requested information is retrieved.
Returns:
the recorded heap usage statistics

getAllocationTree

Tree getAllocationTree(Aggregation level,
                       Liveness liveness,
                       Descriptor[] classOrArrayDescriptors,
                       boolean resetGc)
Calculates the allocation tree for recorded objects of selected classes. The result is analogous to the "Allocation Tree" view of the JProfiler GUI.

Liveness types that include garbage collected objects only work correctly if allocation recording options in the profiling settings include GCed objects.

Parameters:
level - the aggregation level for the allocation tree
liveness - the object liveness for which the allocation tree should be calculated
classOrArrayDescriptors - the descriptors for the selected classes. You can get those descriptors from the HeapValue objects. If null, the allocation tree is calculated for all classes.
resetGc - whether to reset information about garbage collected objects after the requested information is retrieved.
Returns:
the allocation tree

getAllocationTree

Tree getAllocationTree(Aggregation level,
                       Liveness liveness,
                       java.lang.String packageName,
                       boolean resetGc)
Calculates the allocation tree for recorded objects of a selected package. The result is analogous to the "Allocation Tree" view of the JProfiler GUI.

Liveness types that include garbage collected objects only work correctly if allocation recording options in the profiling settings include GCed objects.

Parameters:
level - the aggregation level for the allocation tree
liveness - the object liveness for which the allocation tree should be calculated
packageName - the name of the selected package. If null, the allocation tree is calculated for all classes.
resetGc - whether to reset information about garbage collected objects after the requested information is retrieved.
Returns:
the allocation tree

getAllocationHotspots

AllocationHotspots getAllocationHotspots(Aggregation level,
                                         Liveness liveness,
                                         Descriptor[] classOrArrayDescriptors,
                                         boolean resetGc,
                                         boolean includeFiltered)
Calculates the allocation hot spots for recorded objects of selected classes. The result is analogous to the "Allocation Hot Spots" view of the JProfiler GUI.

Liveness types that include garbage collected objects only work correctly if allocation recording options in the profiling settings include GCed objects.

Parameters:
level - the aggregation level for the allocation hot spots and back traces
liveness - the object liveness for which the allocation hot spots should be calculated
classOrArrayDescriptors - the descriptors for the selected classes. You can get those descriptors from the HeapValue objects. If null, the allocation hot spots are calculated for all classes.
resetGc - whether to reset information about garbage collected objects after the requested information is retrieved.
includeFiltered - whether calls to filtered classes should be separate hot spots (true) or be added to the calling methods (false)
Returns:
the allocation hot spots
See Also:
getAllocationHotspotBacktrace(com.jprofiler.api.platform.structures.ProfilingValue)

getAllocationHotspots

AllocationHotspots getAllocationHotspots(Aggregation level,
                                         Liveness liveness,
                                         java.lang.String packageName,
                                         boolean resetGc,
                                         boolean includeFiltered)
Calculates the allocation hot spots for recorded objects of a selected package. The result is analogous to the "Allocation Hot Spots" view of the JProfiler GUI.

Liveness types that include garbage collected objects only work correctly if allocation recording options in the profiling settings include GCed objects.

Parameters:
level - the aggregation level for the allocation hot spots and back traces
liveness - the object liveness for which the allocation hot spots should be calculated
packageName - the name of the selected package. If null, the allocation hot spots are calculated for all classes.
resetGc - whether to reset information about garbage collected objects after the requested information is retrieved.
includeFiltered - whether calls to filtered classes should be separate hot spots (true) or be added to the calling methods (false)
Returns:
the allocation hot spots
See Also:
getAllocationHotspotBacktrace(com.jprofiler.api.platform.structures.ProfilingValue)

getAllocationHotspotBacktrace

Tree getAllocationHotspotBacktrace(ProfilingValue hotspot)
Calculates the back traces for an allocation hot spot. The result is analogous to the back trace tree under a single top level entry in the "Allocation Hot Spots" view of the JProfiler GUI. Note that this method if the hotspot argument is an allocation hot spot.

Parameters:
hotspot - the allocation hot spot for which to calculate the back trace
Returns:
the back traces as a tree
See Also:
getAllocationHotspots for selected classes, getAllocationHotspots for a selected package

JProfiler API