JProfiler API

com.jprofiler.api.agent.interceptor
Class Interceptor

java.lang.Object
  extended by com.jprofiler.api.agent.interceptor.Interceptor

public abstract class Interceptor
extends java.lang.Object

Base class for deriving a concrete interceptor. An interceptor can inject itself into arbitrary methods and monitor entry, exit and exception exit as well as parameters and return value. Based on that information it can create "payload" that can be added to the current call stack together with a payload timing. Payload statistics is displayed in the "Call Tree" view and each payload type adds a new hot spot type to the "Hot Spots" view.

The functionality offered by interceptors is similar to that of the built-in J2EE service call measurements (JDBC, JMS and JNDI).

Note that implementation classes that are observed by an interceptor are only available if they are in the boot classpath. Since this is usually not the case, you have to check class hierarchies by using the reflection API. The implementsInterface(java.lang.Object, java.lang.String) is useful for checking interface-based hierarchies.

Important:Interceptors cannot intercept methods in the following classes:

Interceptors are added to the profiled process with an InterceptorProvider.

See Also:
InterceptorProvider

Constructor Summary
Interceptor()
           
 
Method Summary
protected  PayloadInfo createPayloadInfo(java.lang.String description)
          Creates a payload info object for this interceptor.
protected  PayloadInfo createPayloadInfo(java.lang.String description, java.lang.Object memento)
          Creates a payload info object for this interceptor with a memento object.
abstract  java.lang.String getInterceptionDescription()
          A description for this interceptor.
abstract  InterceptionMethod[] getInterceptionMethods()
          Defines the methods that should be intercepted by this interceptor.
protected  boolean implementsInterface(java.lang.Object object, java.lang.String interfaceName)
          Helper method to check whether the class of an object implements an interface.
abstract  void interceptionEnter(java.lang.Object object, java.lang.String declaringClassName, java.lang.String methodName, java.lang.String methodSignature, java.lang.Object[] arguments)
          Called when an intercepted method is entered.
abstract  void interceptionExceptionExit(java.lang.Object object, java.lang.String declaringClassName, java.lang.String methodName, java.lang.String methodSignature, java.lang.Throwable throwable)
          Called when an in intercepted method is exited because an exception is thrown.
abstract  void interceptionExit(java.lang.Object object, java.lang.String declaringClassName, java.lang.String methodName, java.lang.String methodSignature, java.lang.Object returnValue)
          Called when an intercepted method is exited via a regular return call.
protected static boolean isCpuRecording()
          Determines if CPU data is being recorded by the profiling agent.
protected static 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.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Interceptor

public Interceptor()
Method Detail

interceptionEnter

public abstract void interceptionEnter(java.lang.Object object,
                                       java.lang.String declaringClassName,
                                       java.lang.String methodName,
                                       java.lang.String methodSignature,
                                       java.lang.Object[] arguments)
Called when an intercepted method is entered. If you want to add payload information with a time measurement to the current call stack, you should create the payload info in this method and save it in a ThreadLocalStack for analysis in the interceptionExceptionExit(Object, String, String, String, Throwable) method.

If you perform wildcard interception based on method names only, you should check if the object has the expected class hierarchy.

Parameters:
object - the object on which the intercepted method was called
declaringClassName - the class where the intercepted method has been declared
methodName - the name of the intercepted method
methodSignature - the signature of the intercepted method in JVM format. See InterceptionMethod for more information on that format.
arguments - the arguments that were passed to the intercepted method or an empty array if the method has no arguments. @see #createPayloadInfo(String)
See Also:
createPayloadInfo(String, Object)

interceptionExit

public abstract void interceptionExit(java.lang.Object object,
                                      java.lang.String declaringClassName,
                                      java.lang.String methodName,
                                      java.lang.String methodSignature,
                                      java.lang.Object returnValue)
Called when an intercepted method is exited via a regular return call. If you want to add payload information with a time measurement to the current call stack, you should call PayloadInfo.calculateTime() on the payload info that you created in interceptionEnter(java.lang.Object, java.lang.String, java.lang.String, java.lang.String, java.lang.Object[]).

Parameters:
object - the object on which the intercepted method was called
declaringClassName - the class where the intercepted method has been declared
methodName - the name of the intercepted method
methodSignature - the signature of the intercepted method in JVM format. See InterceptionMethod for more information on that format.
returnValue - the value that was returned by the intercepted method or null if the return type of the method is void.

interceptionExceptionExit

public abstract void interceptionExceptionExit(java.lang.Object object,
                                               java.lang.String declaringClassName,
                                               java.lang.String methodName,
                                               java.lang.String methodSignature,
                                               java.lang.Throwable throwable)
Called when an in intercepted method is exited because an exception is thrown.

Parameters:
object - the object on which the intercepted method was called
declaringClassName - the class where the intercepted method has been declared
methodName - the name of the intercepted method
methodSignature - the signature of the intercepted method in JVM format. See InterceptionMethod for more information on that format.
throwable - the exception that was thrown in the intercepted method

getInterceptionMethods

public abstract InterceptionMethod[] getInterceptionMethods()
Defines the methods that should be intercepted by this interceptor. See InterceptionMethod for more information. When the interceptor is used within a trigger, this method is ignored and may return null.

Returns:
the intercepted methods

getInterceptionDescription

public abstract java.lang.String getInterceptionDescription()
A description for this interceptor. If you add payload to the call tree, this description will be displayed in the "Call Tree" view and is the name for the hot spot type contributed by this interceptor.

Returns:
the description

createPayloadInfo

protected PayloadInfo createPayloadInfo(java.lang.String description)
Creates a payload info object for this interceptor. See PayloadInfo for more information.

Parameters:
description - the payload description
Returns:
the payload info object

createPayloadInfo

protected PayloadInfo createPayloadInfo(java.lang.String description,
                                        java.lang.Object memento)
Creates a payload info object for this interceptor 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

protected final 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

protected static 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

isCpuRecording

protected static boolean isCpuRecording()
Determines if CPU data is being recorded by the profiling agent. Depending on that fact you might wish to handle payload calculation differently.

Returns:
if CPU data is being recorded.

JProfiler API