com.jprofiler.api.agent.probe
Interface InterceptorContext

All Superinterfaces:

ProbeContext

public interface InterceptorContext
extends ProbeContext

Context object that is passed to the interception methods of interceptor probes. It extends the capabilities of the parent interface to provide support for payload creation and management.

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

Method Summary

void	addPayloadInfo(PayloadInfo payloadInfo) Publishes the payload into the call tree.
ProbeEvent	createCloseEvent(PayloadInfo payloadInfo, java.lang.Object controlObject) Creates an event for closing a control object with payload information.
ProbeEvent	createCustomEvent(PayloadInfo payloadInfo, int type, java.lang.Object controlObject) Creates a custom event with payload information.
ProbeEvent	createOpenEvent(PayloadInfo payloadInfo, java.lang.Object controlObject) Creates an event for opening a control object with payload information.
PayloadInfo	createPayloadInfo(java.lang.String description) Creates a payload info object for this interceptor probe.
PayloadInfo	createPayloadInfo(java.lang.String description, java.lang.Object memento) Creates a payload info object for this interceptor probe with a memento object.
java.lang.String	getOpenEventDescription(java.lang.Object controlObject) Returns the description that was used for creating a control object.
boolean	implementsInterface(java.lang.Object object, java.lang.String interfaceName) Helper method to check whether the class of an object implements an interface.
boolean	isPayloadStackEmpty() Check if the payload stack is empty.
boolean	isTargetMethod(java.lang.String actualMethodName, java.lang.String actualMethodSignature, java.lang.String targetMethodName, java.lang.String targetMethodSignature) Helper method to check if a method name and signature are equivalent with target values.
PayloadInfo	pop() Retrieves a payload that was saved to the thread local stack with push(PayloadInfo).
void	push(PayloadInfo payloadInfo) Saves a payload to a thread local stack.
void	startCustomState(java.lang.Object controlObject, int type) Change the state of a control object for the time line view.

Methods inherited from interface com.jprofiler.api.agent.probe.ProbeContext

addEvent, createCloseEvent, createCustomEvent, createOpenEvent, createOpenEvent, getMap, isRecording

Method Detail

createPayloadInfo

PayloadInfo createPayloadInfo(java.lang.String description)

Creates a payload info object for this interceptor probe. See PayloadInfo for more information.

Parameters:

description - the payload description

Returns:

the payload info object

createPayloadInfo

PayloadInfo createPayloadInfo(java.lang.String description,
                              java.lang.Object memento)

Creates a payload info object for this interceptor probe with a memento object. See PayloadInfo for more information.

Parameters:

description - the payload description

memento - a memento object for information that you need in order to analyze the payload info in a different context.

Returns:

the payload info object

implementsInterface

boolean implementsInterface(java.lang.Object object,
                            java.lang.String interfaceName)

Helper method to check whether the class of an object implements an interface. This method uses reflection to check the condition and saves the result in a thread-local cache, so subsequent invocations are very fast.

Parameters:

object - the object whose class should be checked

interfaceName - the name of the interface that should be checked

Returns:

if the interface is implemented or not

isTargetMethod

boolean isTargetMethod(java.lang.String actualMethodName,
                       java.lang.String actualMethodSignature,
                       java.lang.String targetMethodName,
                       java.lang.String targetMethodSignature)

Helper method to check if a method name and signature are equivalent with target values. This method is important if you intercept multiple methods, since all method calls are intercepted by the same methods in the interceptor.

Parameters:

actualMethodName - the method name as passed to the interceptor methods

actualMethodSignature - the method signature as passed to the interceptor methods

targetMethodName - the method name against which you are testing

targetMethodSignature - the method signature against which you are testing in JVM format. See InterceptionMethod for more information on that format.

Returns:

if the methods are equal or not

addPayloadInfo

void addPayloadInfo(PayloadInfo payloadInfo)

Publishes the payload into the call tree. You can see the results of published payload in the hot spot view. The probe meta data method ProbeMetaData.payload(boolean) has to be called with the argument true in the meta data configuration method.

Parameters:

payloadInfo - the payload that should be published.

push

void push(PayloadInfo payloadInfo)

Saves a payload to a thread local stack. You can retrieve it with pop() later on. The typical use case is to create a payload during the method entry, creating its payload name from the arguments of the intercepted method or other data. During method exit, you then calculate times and publish it.

Parameters:

payloadInfo - the payload info

pop

PayloadInfo pop()

Retrieves a payload that was saved to the thread local stack with push(PayloadInfo).

Returns:

the most recently saved payload info. If the payload stack is empty, it returns null.

isPayloadStackEmpty

boolean isPayloadStackEmpty()

Check if the payload stack is empty. Payloads are saved to the payload stack with push(PayloadInfo).

Returns:

the value

createOpenEvent

ProbeEvent createOpenEvent(PayloadInfo payloadInfo,
                           java.lang.Object controlObject)

Creates an event for opening a control object with payload information. This method enhances the ProbeContext.createOpenEvent(String, Object) with payload. The description of the event is taken from the payload name.

Note that the returned event must be published with ProbeContext.addEvent(ProbeEvent), otherwise the event will be discarded.

Parameters:

payloadInfo - the payload info

controlObject - the control object that is being opened

Returns:

the probe event

createCloseEvent

ProbeEvent createCloseEvent(PayloadInfo payloadInfo,
                            java.lang.Object controlObject)

Creates an event for closing a control object with payload information. This method enhances the ProbeContext.createCloseEvent(String, Object) with payload. The description of the event is taken from the payload name.

Note that the returned event must be published with ProbeContext.addEvent(ProbeEvent), otherwise the event will be discarded.

Parameters:

payloadInfo - the payload info

controlObject - the control object that is being closed

Returns:

the probe event

createCustomEvent

ProbeEvent createCustomEvent(PayloadInfo payloadInfo,
                             int type,
                             java.lang.Object controlObject)

Creates a custom event with payload information. This method enhances the ProbeContext.createCustomEvent(String, int, Object). The description of the event is taken from the payload name.

Note that the returned event must be published with ProbeContext.addEvent(ProbeEvent), otherwise the event will be discarded.

Parameters:

payloadInfo - the payload info

type - the type corresponds to the index of the desired custom event in the the call to ProbeMetaData.customTypeNames(String[])

controlObject - the control object for this event. Can be null.

Returns:

the probe event

startCustomState

void startCustomState(java.lang.Object controlObject,
                      int type)

Change the state of a control object for the time line view. In the time line view, the horizontal bars that show the control objects on the time axis are colored according to the colors defined in ProbeMetaData.customColors(int[]). The indices correspond to the custom states defined with ProbeMetaData.customTypeNames(String[]). Usually, this is done automatically based on the published custom events. If you do not want to publish, associated events, you can used this method to change the state of a control object.

Parameters:

controlObject - the control object whose state should be changed

type - the new state. This is the index of the desired custom state in the call to ProbeMetaData.customTypeNames(String[]).

getOpenEventDescription

java.lang.String getOpenEventDescription(java.lang.Object controlObject)

Returns the description that was used for creating a control object. This corresponds to the description parameter in createOpenEvent(PayloadInfo, Object).

Parameters:

controlObject - the control object

Returns:

the description