Connection (JProfiler API)
Date: 2012-06-30

Overview | Package | Class | Tree | Deprecated | Index | Help
| JProfiler API
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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 addFilteredToCalling)` Calculates the allocation hot spots for recorded objects of selected classes.
`AllocationHotspots` | `getAllocationHotspots(Aggregation level, Liveness liveness, java.lang.String packageName, boolean resetGc, boolean addFilteredToCalling)` 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 addFilteredToCalling)` Calculates CPU hot spots.
`Tree` | `getCpuTree(java.util.Collection<ThreadInfo> threads, Aggregation level, ThreadStatus status)` Calculates the cumulated call tree.
`Tree` | `getPayloadHotspotBacktrace(ProfilingValue hotspot)` Calculates the back traces for a payload hot spot.
`java.util.List<? extends ProfilingValue>` | `getPayloadHotspots(java.lang.String payloadName, java.util.Collection<ThreadInfo> threads, Aggregation level, ThreadStatus status)` Calculates hot spots for a non-method hot spot type.
`ProbeInfo` | `getProbeInfo()` Returns information about registered interceptors.
`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

### getProbeInfo

    ProbeInfo getProbeInfo()

  Returns information about registered interceptors. Interceptors are registered with an `ProbeProvider`.

  Returns:
    the information about registered interceptors
  See Also:
    `InterceptorProbe`, `ProbeProvider`

### getCpuHotspots

    CpuHotspots getCpuHotspots(java.util.Collection<ThreadInfo> threads,
                               Aggregation level,
                               ThreadStatus status,
                               boolean addFilteredToCalling)

  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
    `addFilteredToCalling` - 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<? extends ProfilingValue> getPayloadHotspots(java.lang.String payloadName,
                                                                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 `ProbeInfo.getDescriptionToId()`.

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

  Parameters:
    `payloadName` - the name 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 addFilteredToCalling)

  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.
    `addFilteredToCalling` - 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 addFilteredToCalling)

  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.
    `addFilteredToCalling` - 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`

Overview | Package | Class | Tree | Deprecated | Index | Help
| JProfiler API
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD