Interceptor (JProfiler API)
Keywords: com.jprofiler.api.agent.interceptor.Interceptor class

Overview | Package | Class | Tree | Deprecated | Index | Help
| JProfiler API
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.jprofiler.api.agent.interceptor
Class Interceptor

    java.lang.Object
      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:

- classes that are loaded before the main class is loaded
- the main class and its superclasses

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 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 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 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 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, 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
    `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 Also:
    `createPayloadInfo(String)`, `createPayloadInfo(String, Object)`

### interceptionExit

    public abstract void interceptionExit(java.lang.Object object,
                                          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.Object[])`.

  Parameters:
    `object` - the object on which the intercepted method was called
    `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 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
    `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.

  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.

Overview | Package | Class | Tree | Deprecated | Index | Help
| JProfiler API
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD