Class Payload


  • public class Payload
    extends java.lang.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 Summary

      Constructors 
      Constructor Description
      Payload()  
    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static void closeControlObject​(java.lang.Class<? extends PayloadProbe> probe, java.lang.Object controlObject)
      Closes a control object.
      static void enter​(java.lang.Class<? extends PayloadProbe> probe)
      Start a payload.
      static void enter​(java.lang.Class<? extends PayloadProbe> probe, java.lang.Object controlObject, java.lang.Enum<?> type)
      Start a payload.
      static void execute​(java.lang.Class<? extends PayloadProbe> probe, java.lang.String name, java.lang.Object controlObject, java.lang.Enum<?> type, java.lang.Runnable runnable)
      A wrapper for the enter(Class, Object, Enum) and exit(String) primitives for a Runnable.
      static <T> T execute​(java.lang.Class<? extends PayloadProbe> probe, java.lang.String name, java.lang.Object controlObject, java.lang.Enum<?> type, java.util.concurrent.Callable<T> callable)
      A wrapper for the enter(Class, Object, Enum) and exit(String) primitives for a Callable.
      static void execute​(java.lang.Class<? extends PayloadProbe> probe, java.lang.String name, java.lang.Runnable runnable)
      A wrapper for the enter(Class) and exit(String) primitives for a Runnable.
      static <T> T execute​(java.lang.Class<? extends PayloadProbe> probe, java.lang.String name, java.util.concurrent.Callable<T> callable)
      A wrapper for the enter(Class) and exit(String) primitives for a Callable.
      static void exit​(java.lang.String name)
      Finishes recording of a payload.
      static void openControlObject​(java.lang.Class<? extends PayloadProbe> probe, java.lang.Object controlObject, java.lang.String name)
      Records an open event for a control object and assigns a name to it.
      static void register​(java.lang.Class<? extends PayloadProbe> probe)
      You can register your probe independently of enter and execute calls.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • Payload

        public Payload()
    • Method Detail

      • enter

        public static void enter​(java.lang.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​(java.lang.Class<? extends PayloadProbe> probe,
                                 java.lang.Object controlObject,
                                 java.lang.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​(java.lang.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​(java.lang.Class<? extends PayloadProbe> probe,
                                   java.lang.String name,
                                   java.lang.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​(java.lang.Class<? extends PayloadProbe> probe,
                                   java.lang.String name,
                                   java.lang.Object controlObject,
                                   java.lang.Enum<?> type,
                                   java.lang.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​(java.lang.Class<? extends PayloadProbe> probe,
                                    java.lang.String name,
                                    java.util.concurrent.Callable<T> callable)
                             throws java.lang.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:
        java.lang.Exception
      • execute

        public static <T> T execute​(java.lang.Class<? extends PayloadProbe> probe,
                                    java.lang.String name,
                                    java.lang.Object controlObject,
                                    java.lang.Enum<?> type,
                                    java.util.concurrent.Callable<T> callable)
                             throws java.lang.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:
        java.lang.Exception
      • openControlObject

        public static void openControlObject​(java.lang.Class<? extends PayloadProbe> probe,
                                             java.lang.Object controlObject,
                                             java.lang.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​(java.lang.Class<? extends PayloadProbe> probe,
                                              java.lang.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​(java.lang.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.