public class Payload
extends java.lang.Object
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 and Description |
---|
Payload() |
Modifier and Type | Method and 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 <T> T |
execute(java.lang.Class<? extends PayloadProbe> probe,
java.lang.String name,
java.util.concurrent.Callable<T> callable)
|
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)
|
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)
|
static void |
execute(java.lang.Class<? extends PayloadProbe> probe,
java.lang.String name,
java.lang.Runnable runnable)
|
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. |
public static void enter(java.lang.Class<? extends PayloadProbe> probe)
exit(String)
call must be always called.probe
- the configuration class. Must not be null
.public static void enter(java.lang.Class<? extends PayloadProbe> probe, java.lang.Object controlObject, java.lang.Enum<?> type)
exit(String)
call must be always called.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
.public static void exit(java.lang.String name)
enter
call must have been called first.name
- the name of the recorded payload. If null
, the payload recording will be discarded.public static void execute(java.lang.Class<? extends PayloadProbe> probe, java.lang.String name, java.lang.Runnable runnable)
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.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)
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.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
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.java.lang.Exception
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
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.java.lang.Exception
public static void openControlObject(java.lang.Class<? extends PayloadProbe> probe, java.lang.Object controlObject, java.lang.String name)
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.
probe
- the configuration class. Must not be null
.controlObject
- the control objectname
- the name of the control objectpublic static void closeControlObject(java.lang.Class<? extends PayloadProbe> probe, java.lang.Object controlObject)
probe
- the configuration class. Must not be null
.controlObject
- the control objectpublic static void register(java.lang.Class<? extends PayloadProbe> probe)
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.probe
- the configuration class. Must not be null
.