JProfiler API documentation

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