ProbeMetaData (JProfiler help)
Date: 2012-06-30

## JProfiler API documentation

## com.jprofiler.api.agent.probe
Class ProbeMetaData

    java.lang.Object
      com.jprofiler.api.agent.probe.ProbeMetaData

    public abstract class ProbeMetaData

extends java.lang.Object

The meta data defines the capabilities of a probe. At startup, each probe is queried once for its meta data via a call to `Probe.getMetaData()`. In that method, you create an instance with `create(String)` and call its methods to configure the probe. The meta data provides a fluent interface, so you can append method calls like in `ProbeMetaData.create("Test").events(true).recordOnStartup(false)`.

The help topic on custom probes in the bundled documentation explains how to develop custom probes.

Constructor Summary
`ProbeMetaData()`

Method Summary
`abstract ProbeMetaData` | `addAdditionalControlObjectData(java.lang.String name, DataType dataType, boolean nested)` Configures an additional data column for control objects.
`abstract ProbeMetaData` | `addAdditionalData(java.lang.String name, DataType dataType)` Configures an additional data column for probe events.
`abstract ProbeMetaData` | `addCustomTelemetry(java.lang.String name, Unit unit, float factor)` Configures a custom telemetry.
`abstract ProbeMetaData` | `addOpenControlObjectTelemetry(java.lang.String name)` Configures a telemetry that shows the number of open control objects.
`abstract ProbeMetaData` | `annotatePayloads(boolean annotatePayloads)` Configures if the probe should annotate data into the call tree view.
`abstract ProbeMetaData` | `closeTypeName(java.lang.String name)` Sets the name of the automatic event type for the closing of a control object.
`abstract ProbeMetaData` | `controlObjectView(boolean controlObjectView)` Configures if the probe publishes control objects.
`static ProbeMetaData` | `create(java.lang.String name)` Creates an meta-data instance.
`abstract ProbeMetaData` | `customColors(int[] customColors)` Configures the colors of the custom events in the time line view.
`abstract ProbeMetaData` | `customTypeNames(java.lang.String[] typeNames)` Configures the custom event types and their names.
`abstract ProbeMetaData` | `description(java.lang.String description)` Sets the description of the probe.
`abstract ProbeMetaData` | `events(boolean events)` Configures if probe retain single events.
`abstract ProbeMetaData` | `openTypeName(java.lang.String name)` Sets the name of the automatic event type for the opening of a control object.
`abstract ProbeMetaData` | `payload(boolean payload)` Configures if the probe collects payload information.
`abstract ProbeMetaData` | `payloadName(java.lang.String payloadName)` Sets the name of the payload.
`abstract ProbeMetaData` | `recordOnStartup(boolean startRecording)` Configures if the probe should record data on startup.
`abstract ProbeMetaData` | `startTelemetryGroup(java.lang.String name)` Starts a group of telemetries that can be displayed in the same graph.
`abstract ProbeMetaData` | `telemetry(boolean telemetry)` Configures if the probe collects telemetry data.

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

Constructor Detail

### ProbeMetaData

    public ProbeMetaData()

Method Detail

### create

    public static ProbeMetaData create(java.lang.String name)

  Creates an meta-data instance. For custom probes defined the JProfiler GUI, you should not call this method, since a meta data instance is already passed to the meta-data script. In that case, the name and description of the probe are already set.

  Parameters:
    `name` - the name of the probe. This name is displayed in the JProfiler GUI.
  Returns:
    the meta-data instance

### description

    public abstract ProbeMetaData description(java.lang.String description)

  Sets the description of the probe. The description is displayed in the probes view and the custom probe configuration or the session settings. If this method is not called, a default description will be displayed.

  Parameters:
    `description` - the description
  Returns:
    this instance

### payload

    public abstract ProbeMetaData payload(boolean payload)

  Configures if the probe collects payload information. The default value is `false`. If set to `true`, the hot spots view will be shown. The `InterceptorContext.createPayloadInfo(String)` and `InterceptorContext.createPayloadInfo(String, Object)` and published via `InterceptorContext.addPayloadInfo(PayloadInfo)` for standalone payloads or via `create` methods in the `InterceptorContext` that take a `PayloadInfo` argument.

  This only makes sense for `interceptor probes`.

  Parameters:
    `payload` - the value
  Returns:
    this instance

### events

    public abstract ProbeMetaData events(boolean events)

  Configures if probe retain single events. The default value is `false`. If set to `true`, the events view will be shown. If the event count exceeds 100000, events will be consolidated. Events are created with the `create` methods in `ProbeContext` and `InterceptorContext` and are published with `ProbeContext.addEvent(ProbeEvent)`.

  Parameters:
    `events` - the value
  Returns:
    this instance

### telemetry

    public abstract ProbeMetaData telemetry(boolean telemetry)

  Configures if the probe collects telemetry data. The default value is `false`. If set to `true`, the telemetries view will be shown. Telemetries must then be configured with calls to `addCustomTelemetry(String, Unit, float)` and `addOpenControlObjectTelemetry(String)`. Telemetry data is sampled every second with calls to `TelemetryProbe.fillTelemetryData(ProbeContext, int[])`.

  This only makes sense for `telemetry probes`.

  Parameters:
    `telemetry` - the value
  Returns:
    this instance

### controlObjectView

    public abstract ProbeMetaData controlObjectView(boolean controlObjectView)

  Configures if the probe publishes control objects. The default value is `false`. If set to `true`, the control objects view will be shown. Control objects are created with calls to `ProbeContext.createOpenEvent(String, Object)` or `InterceptorContext.createOpenEvent(PayloadInfo, Object)`.

  Parameters:
    `controlObjectView` - the value
  Returns:
    this instance

### recordOnStartup

    public abstract ProbeMetaData recordOnStartup(boolean startRecording)

  Configures if the probe should record data on startup. The default value is `true`. In any case, the user can start and stop recording the JProfiler GUI.

  Parameters:
    `startRecording` - the value
  Returns:
    this instance

### annotatePayloads

    public abstract ProbeMetaData annotatePayloads(boolean annotatePayloads)

  Configures if the probe should annotate data into the call tree view. The default value is `false`. If set to `true`, you should also call the `payloadName(String)` method, so you can distinguish payload from different probes in the call tree.

  Parameters:
    `annotatePayloads` - the value
  Returns:
    this instance

### payloadName

    public abstract ProbeMetaData payloadName(java.lang.String payloadName)

  Sets the name of the payload. Then the probe annotates data in the the call tree, the container node for the payload of this probe shows this name.

  This only has an effect if `annotatePayloads(boolean)` is called with the argument `true`.

  Parameters:
    `payloadName` - the name
  Returns:
    this instance

### startTelemetryGroup

    public abstract ProbeMetaData startTelemetryGroup(java.lang.String name)

  Starts a group of telemetries that can be displayed in the same graph. The telemetries have to have the same units and their values should be in the sme order of magnitude. All subsequent calls to `addCustomTelemetry(String, Unit, float)` will be added to this group. To start a new group, you have to call this method again. If you never call this method, all telemetries will be in separate graphs.

  This only makes sense if the `telemetry(boolean)` method has been called with the argument `true`.

  Parameters:
    `name` - the name of the telemetry group
  Returns:
    this instance

### addOpenControlObjectTelemetry

    public abstract ProbeMetaData addOpenControlObjectTelemetry(java.lang.String name)

  Configures a telemetry that shows the number of open control objects. This only makes sense if your probe supports control objects and has called `controlObjectView(boolean)` with the argument `true`.

  This only makes sense if the `telemetry(boolean)` method has been called with the argument `true`.

  Parameters:
    `name` - the name of the telemetry
  Returns:
    this instance

### addCustomTelemetry

    public abstract ProbeMetaData addCustomTelemetry(java.lang.String name,
                                                     Unit unit,
                                                     float factor)

  Configures a custom telemetry. Telemetry values are sampled every second by calls to `TelemetryProbe.fillTelemetryData(ProbeContext, int[])`. The order of the invocations of this configuration method define the indices in the data array of the sampling method.

  This only makes sense if the `telemetry(boolean)` method has been called with the argument `true`.

  Parameters:
    `name` - the name of the telemetry
    `unit` - the unit of the measurement
    `factor` - the number by which the measurements should be divided to get the numeric value for the vertical axis. If your measurements directly correspond to the selected unit, pass `1f`.
  Returns:
    this instance

### addAdditionalData

    public abstract ProbeMetaData addAdditionalData(java.lang.String name,
                                                    DataType dataType)

  Configures an additional data column for probe events. Additional data is set by a call to `ProbeEvent.additionalData(Object[])`. The order of the invocations of this configuration method define the indices in the data array of the `additionalData` method.

  This only makes sense if the `events(boolean)` method has been called with the argument `true`.

  Parameters:
    `name` - the name of the additional data column. This is displayed as the column header in the events view.
    `dataType` - the data type of the additional data column
  Returns:
    this instance

### addAdditionalControlObjectData

    public abstract ProbeMetaData addAdditionalControlObjectData(java.lang.String name,
                                                                 DataType dataType,
                                                                 boolean nested)

  Configures an additional data column for control objects. Additional data is set when control objects are opened with a call to `ProbeContext.createOpenEvent(String, Object, Object[])` or `ProbeContext.createOpenEvent(String, Object, Object[])`. The order of the invocations of this configuration method define the indices in the data array of the `createOpenEvent` methods.

  This only makes sense if the `controlObjectView(boolean)` method has been called with the argument `true`.

  Parameters:
    `name` - the name of the additional data column. This is displayed as the column header in the control objects view.
    `dataType` - the data type of the additional data column
    `nested` - If the column should be displayed in a nested table. This makes sense if the data is more for debugging purposes, contains very long text values or if you have a lot of additional data columns. For example, the built-in process probe shows several columns in a nested table.
  Returns:
    this instance

### customTypeNames

    public abstract ProbeMetaData customTypeNames(java.lang.String[] typeNames)

  Configures the custom event types and their names. The index in the array becomes the ID of the custom event type and is used in calls to `ProbeContext.createCustomEvent(String, int, Object)` and `InterceptorContext.startCustomState(Object, int)`. Custom events that are associated with control objects are also shown in the time line view in the way the horizontal bar of a control object is colored along the time axis. To configure the colors of custom events, call `customColors(int[])`.

  Parameters:
    `typeNames` - the names of the custom events. Not that the index in the array becomes the ID of the custom event.
  Returns:
    this instance

### customColors

    public abstract ProbeMetaData customColors(int[] customColors)

  Configures the colors of the custom events in the time line view.

  Parameters:
    `customColors` - the colors as RGB values. The RGB value is the result of the `getRGB()` method on a `java.awt.Color` object. The array index of each color corresponds to the custom event index in the call to `customTypeNames(String[])`.
  Returns:
    this instance
  See Also:
    `customTypeNames(String[])`

### openTypeName

    public abstract ProbeMetaData openTypeName(java.lang.String name)

  Sets the name of the automatic event type for the opening of a control object. This name is displayed in the event type selector of control object and events view as well as in the event type column of the events view. For example, the file probe sets this value to "File opened".

  This only makes sense if the `controlObjectView(boolean)` method has been called with the argument `true`.

  Parameters:
    `name` - the name of the event type
  Returns:
    this instance
  See Also:
    `closeTypeName(String)`

### closeTypeName

    public abstract ProbeMetaData closeTypeName(java.lang.String name)

  Sets the name of the automatic event type for the closing of a control object. This name is displayed in the event type selector of control object and events view as well as in the event type column of the events view. For example, the file probe sets this value to "File closed".

  This only makes sense if the `controlObjectView(boolean)` method has been called with the argument `true`.

  Parameters:
    `name` - the name of the event type
  Returns:
    this instance
  See Also:
    `(String)`