Package com.jprofiler.api.probe.embedded

Class Payload

java.lang.Object
com.jprofiler.api.probe.embedded.Payload
public class Payload extends Object
By calling this class you can add entries to the payload call tree and hotspots of your probe.

You can either use a pair of enter(Class) and exit(String) calls or the execute wrappers. If you write your own wrapper in another JVM language it is advisable to use the enter(Class) and exit(String) primitives.

When using the primitives, it is very important that a matching exit(String) is always called, so the exit call must be put it a finally block like this:


     Payload.enter(MyProbe.class);
     try {
         // your code
     } finally {
         Payload.exit("my payload string");
     }

If you use control objects in your probe (for example to record connections like in the JDBC probe) you can use the enter(Class, Object, Enum) or the similarly overloaded execute wrappers to associate a payload with a control object. With the openControlObject(Class, Object, String), closeControlObject(Class, Object) and PayloadProbe.getControlObjectName(Object) methods you can further customize control object recording. Your configuration subclass of PayloadProbe must override PayloadProbe.isControlObjects() and return true to enable control object recording as a capability for the probe.

If you want to record different event types which also correspond to different control object states, you have to override PayloadProbe.getCustomTypes() and return a custom enum class. Objects of this class can then be passed to enter(Class, Object, Enum). The toString() method of the enums will be used to get the event name. If you want to control the event color, the enum class can implement the TypeCustomizer interface.

  • Constructor Details

    • Payload

      public Payload()

  • Method Details

    • enter

      public static void enter(Class<? extends PayloadProbe> probe)
      Start a payload. A matching exit(String) call must be always called.
      Parameters:
      probe - the configuration class. Must not be null.

    • enter

      public static void enter(Class<? extends PayloadProbe> probe, Object controlObject, Enum<?> type)
      Start a payload. A matching exit(String) call must be always called.
      Parameters:
      probe - the configuration class. Must not be null.
      controlObject - the control object this payload belongs to or null. If control objects should be recorded you have to override PayloadProbe.isControlObjects().
      type - the payload type. Must by an object of your custom enum class registered by overriding PayloadProbe.getCustomTypes() or null.

    • exit

      public static void exit(String name)
      Finishes recording of a payload. A matching enter call must have been called first.
      Parameters:
      name - the name of the recorded payload. If null, the payload recording will be discarded.

    • execute

      public static void execute(Class<? extends PayloadProbe> probe, String name, Runnable runnable)
      A wrapper for the enter(Class) and exit(String) primitives for a Runnable.
      Parameters:
      probe - the configuration class. Must not be null.
      name - the name of the recorded payload. If null, the payload recording will be discarded.
      runnable - the runnable that will be timed for the payload recording.

    • execute

      public static void execute(Class<? extends PayloadProbe> probe, String name, Object controlObject, Enum<?> type, Runnable runnable)
      A wrapper for the enter(Class, Object, Enum) and exit(String) primitives for a Runnable.
      Parameters:
      probe - the configuration class. Must not be null.
      name - the name of the recorded payload. If null, the payload recording will be discarded.
      controlObject - the control object this payload belongs to or null. If control objects should be recorded you have to override PayloadProbe.isControlObjects().
      type - the payload type. Must by an object of your custom enum class registered by overriding PayloadProbe.getCustomTypes() or null.
      runnable - the runnable that will be timed for the payload recording.

    • execute

      public static <T> T execute(Class<? extends PayloadProbe> probe, String name, Callable<T> callable) throws Exception
      A wrapper for the enter(Class) and exit(String) primitives for a Callable.
      Parameters:
      probe - the configuration class. Must not be null.
      name - the name of the recorded payload. If null, the payload recording will be discarded.
      callable - the callable that will be timed for the payload recording.
      Throws:
      Exception

    • execute

      public static <T> T execute(Class<? extends PayloadProbe> probe, String name, Object controlObject, Enum<?> type, Callable<T> callable) throws Exception
      A wrapper for the enter(Class, Object, Enum) and exit(String) primitives for a Callable.
      Parameters:
      probe - the configuration class. Must not be null.
      name - the name of the recorded payload. If null, the payload recording will be discarded.
      controlObject - the control object this payload belongs to or null. If control objects should be recorded you have to override PayloadProbe.isControlObjects().
      type - the payload type. Must by an object of your custom enum class registered by overriding PayloadProbe.getCustomTypes() or null.
      callable - the callable that will be timed for the payload recording.
      Throws:
      Exception

    • openControlObject

      public static void openControlObject(Class<? extends PayloadProbe> probe, Object controlObject, String name)
      Records an open event for a control object and assigns a name to it. The control object will be displayed in the control objects view and the timeline. Your configuration subclass of PayloadProbe must override PayloadProbe.isControlObjects() and return true to enable control object recording as a capability for the probe.

      If you don't use this method and a previously unknown control object is used in the enter or execute methods and you have overridden the PayloadProbe.getControlObjectName(Object) method of your configuration class, it will be called to assign a name to the new control object. No open event will be created in the events view in that case.

      Parameters:
      probe - the configuration class. Must not be null.
      controlObject - the control object
      name - the name of the control object

    • closeControlObject

      public static void closeControlObject(Class<? extends PayloadProbe> probe, Object controlObject)
      Closes a control object. If the control object is not currently open, this method has no effect.
      Parameters:
      probe - the configuration class. Must not be null.
      controlObject - the control object

    • register

      public static void register(Class<? extends PayloadProbe> probe)
      You can register your probe independently of enter and execute calls. As soon as the probe is registered it will be displayed in the JProfiler UI and telemetries can be recorded. You don't have to call this method if you don't want to start telemetry recording before an enter or execute call takes place. enter or execute and all control object methods will automatically register your probe.
      Parameters:
      probe - the configuration class. Must not be null.