## install4j API documentation

## com.jprofiler.agent
Class Controller

    java.lang.Object
      com.jprofiler.agent.Controller

    public class Controller

extends java.lang.Object

This is JProfiler's profiling API. It is contained in `bin/agent.jar` in your JProfiler installation directory. Call these static methods from your source code to influence the run time behaviour of JProfiler.

When executing your application without JProfiler, all calls into this class will quietly do nothing.

Method Summary
`static void` | `saveSnapshot(java.io.File file)` Save a snapshot of all profiling data to disk.
`static void` | `startAllocRecording(boolean reset)` Start recording of memory allocations.
`static void` | `startCPURecording(boolean reset)` Start recording CPU data.
`static void` | `stopAllocRecording()` Stop recording of memory allocations.
`static void` | `stopCPURecording()` Stop CPU recording.
`static void` | `triggerHeapDump()` Trigger a heap dump.
`static void` | `triggerHeapDump(boolean fullGc)` Trigger a heap dump.
`static void` | `triggerHeapDump(boolean fullGc, boolean onlyRecorded)` Trigger a heap dump.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Method Detail

### startCPURecording

    public static void startCPURecording(boolean reset)

  Start recording CPU data. This method can be called repeatedly and alternatingly with `stopCPURecording()`. With these methods you can restrict CPU profiling to certain regions of your code.

  Parameters:
    `reset` - if `true`, any previously accumulated CPU profiling data will be discarded. If `false`, CPU data will be accumulated accross pairs of invocations of `startCPURecording()` and `stopCPURecording()`.

### stopCPURecording

    public static void stopCPURecording()

  Stop CPU recording. This method can be called after `startCPURecording()` has been called. However, you do not have to call it since CPU profiling can run until the JVM exits.

### startAllocRecording

    public static void startAllocRecording(boolean reset)

  Start recording of memory allocations. This method can be called repeatedly and alternatingly with `stopAllocRecording()`. With these methods you can restrict memory allocation profiling to certain regions of your code. This is especially useful for profiling an application running within an application server.

  Parameters:
    `reset` - if `true`, any previously recorded profiling data will be discarded. If `false`, allocations within all pairs of invocations of `startAllocRecording()` and `stopAllocRecording()` will be recorded.

### stopAllocRecording

    public static void stopAllocRecording()

  Stop recording of memory allocations. This method can be called after `startAllocRecording()` has been called. However, you do not have to call it since memory profiling can run until the JVM exits.

### triggerHeapDump

    public static void triggerHeapDump()

  Trigger a heap dump. Calls triggerHeapDump(false, false) for backwards compatibility purposes.

### triggerHeapDump

    public static void triggerHeapDump(boolean fullGc)

  Trigger a heap dump. Calls triggerHeapDump(fullGc, false) for backwards compatibility purposes.

  Parameters:
    `fullGc` - if `true`, a full garbage collection will be performed.

### triggerHeapDump

    public static void triggerHeapDump(boolean fullGc,
                                       boolean onlyRecorded)

  Trigger a heap dump. If you want to analyze a heap dump with the heap walker in a snapshot saved with the `saveSnapshot` method, you should call this method from your source code at an appropriate time.

  ATTENTION: Taking a heap dump takes a long time (on the order of seconds). If you call this method to often, your application might become unusable or take an excessively long time to finish.

  Parameters:
    `fullGc` - if `true`, a full garbage collection will be performed.
    `onlyRecorded` - if `true`, only objects recorded between startAllocRecording and stopAllocRecording will be inlucded in the dump.

### saveSnapshot

    public static void saveSnapshot(java.io.File file)

  Save a snapshot of all profiling data to disk. This is especially important for offline profiling. You should choose the standard extension `.jps` for the `file` parameter, since JProfiler's GUI frontend filters the corresponding file choosers for that extension. If you want to save several snapshots during one profiling run, please take care to provide unique `file` parameters since snapshot files will be overwritten otherwise.

  ATTENTION: Saving a snapshot takes a long time (on the order of seconds). If you call this method to often, your application might become unusable or take an excessively long time to finish, and your hard disk might run out of space.

  Parameters:
    `file` - the file to which the snapshot should be saved.