Class Payload
- java.lang.Object
-
- com.jprofiler.api.probe.embedded.Payload
-
public class Payload extends java.lang.ObjectBy 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)andexit(String)calls or theexecutewrappers. If you write your own wrapper in another JVM language it is advisable to use theenter(Class)andexit(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 overloadedexecutewrappers to associate a payload with a control object. With theopenControlObject(Class, Object, String),closeControlObject(Class, Object)andPayloadProbe.getControlObjectName(Object)methods you can further customize control object recording. Your configuration subclass ofPayloadProbemust overridePayloadProbe.isControlObjects()and returntrueto 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 toenter(Class, Object, Enum). ThetoString()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 theTypeCustomizerinterface.
-
-
Constructor Summary
Constructors Constructor Description Payload()
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static voidcloseControlObject(java.lang.Class<? extends PayloadProbe> probe, java.lang.Object controlObject)Closes a control object.static voidenter(java.lang.Class<? extends PayloadProbe> probe)Start a payload.static voidenter(java.lang.Class<? extends PayloadProbe> probe, java.lang.Object controlObject, java.lang.Enum<?> type)Start a payload.static voidexecute(java.lang.Class<? extends PayloadProbe> probe, java.lang.String name, java.lang.Object controlObject, java.lang.Enum<?> type, java.lang.Runnable runnable)static <T> Texecute(java.lang.Class<? extends PayloadProbe> probe, java.lang.String name, java.lang.Object controlObject, java.lang.Enum<?> type, java.util.concurrent.Callable<T> callable)static voidexecute(java.lang.Class<? extends PayloadProbe> probe, java.lang.String name, java.lang.Runnable runnable)static <T> Texecute(java.lang.Class<? extends PayloadProbe> probe, java.lang.String name, java.util.concurrent.Callable<T> callable)static voidexit(java.lang.String name)Finishes recording of a payload.static voidopenControlObject(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 voidregister(java.lang.Class<? extends PayloadProbe> probe)You can register your probe independently ofenterandexecutecalls.
-
-
-
Method Detail
-
enter
public static void enter(java.lang.Class<? extends PayloadProbe> probe)
Start a payload. A matchingexit(String)call must be always called.- Parameters:
probe- the configuration class. Must not benull.
-
enter
public static void enter(java.lang.Class<? extends PayloadProbe> probe, java.lang.Object controlObject, java.lang.Enum<?> type)
Start a payload. A matchingexit(String)call must be always called.- Parameters:
probe- the configuration class. Must not benull.controlObject- the control object this payload belongs to ornull. If control objects should be recorded you have to overridePayloadProbe.isControlObjects().type- the payload type. Must by an object of your custom enum class registered by overridingPayloadProbe.getCustomTypes()ornull.
-
exit
public static void exit(java.lang.String name)
Finishes recording of a payload. A matchingentercall must have been called first.- Parameters:
name- the name of the recorded payload. Ifnull, 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)
- Parameters:
probe- the configuration class. Must not benull.name- the name of the recorded payload. Ifnull, 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)
- Parameters:
probe- the configuration class. Must not benull.name- the name of the recorded payload. Ifnull, the payload recording will be discarded.controlObject- the control object this payload belongs to ornull. If control objects should be recorded you have to overridePayloadProbe.isControlObjects().type- the payload type. Must by an object of your custom enum class registered by overridingPayloadProbe.getCustomTypes()ornull.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
- Parameters:
probe- the configuration class. Must not benull.name- the name of the recorded payload. Ifnull, 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
- Parameters:
probe- the configuration class. Must not benull.name- the name of the recorded payload. Ifnull, the payload recording will be discarded.controlObject- the control object this payload belongs to ornull. If control objects should be recorded you have to overridePayloadProbe.isControlObjects().type- the payload type. Must by an object of your custom enum class registered by overridingPayloadProbe.getCustomTypes()ornull.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 ofPayloadProbemust overridePayloadProbe.isControlObjects()and returntrueto 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
enterorexecutemethods and you have overridden thePayloadProbe.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 benull.controlObject- the control objectname- 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 benull.controlObject- the control object
-
register
public static void register(java.lang.Class<? extends PayloadProbe> probe)
You can register your probe independently ofenterandexecutecalls. 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 anenterorexecutecall takes place.enterorexecuteand all control object methods will automatically register your probe.- Parameters:
probe- the configuration class. Must not benull.
-
-