Configuring Instrumentation 11-15
The name for a custom monitor is an arbitrary string chosen by the developer. Because this monitor is custom, it has no predefined locations when actions should be
invoked; the descriptor file must define the location type and pointcut expression. In this example, the TraceAction action will be invoked before
location-typebeforelocation-type any methods defined by the pointcut expression is invoked.
Table 11–1 shows how the pointcut expression from
Example 11–2 is parsed. Note the use of wildcards.
This pointcut expression matches all get methods in all classes in package com.foo.bar and its sub-packages. The methods can return values of any type,
including void, and can have any number of arguments of any type. Instrumentation code will be inserted before these methods are called, and, just before those methods
are called, the TraceAction action will be invoked.
See Section 11.5.4.1, Defining Pointcuts for Custom Monitors,
for a description of the grammar used to define pointcuts.
11.5.4.1 Defining Pointcuts for Custom Monitors
Custom monitors provide more flexibility than delegating monitors because you create pointcut expressions to control where diagnostics actions are invoked. As with
delegating monitors, you must select actions from the action library.
A joinpoint is a specific, well-defined location in a program. A pointcut is an expression that specifies a set of joinpoints. This section describes how you define
expressions for pointcuts using the following pointcut syntax.
You can specify two types of pointcuts for custom monitors:
■
call: Take an action when a method is invoked.
■
execution: Take an action when a method is executed. The syntax for defining a pointcut expression is as follows:
pointcutExpr := orExpr OR orExpr orExpr := andExpr AND andExpr
andExpr := NOT ? termExpr termExpr := exec_pointcut | call_pointcut | pointcutExpr
exec_pointcut := execution modifiers? returnSpec
classSpecWithAnnotations methodSpec parameterList
Table 11–6 Description of a Sample Pointcut Expression
Pointcut Expression Description
call com.foo.bar. get ...
call
: Trigger any defined actions when the methods whose joinpoints are defined by the
remainder of this pointcut expression are invoked.
call com.foo.bar. get ... : Return value. The wildcard indicates that the
methods can have any type of return value.
call com.foo.bar. get ... com.foo.bar.
: Methods from class com.foo.bar and its sub-packages are eligible.
call com.foo.bar. get ... get
: Any methods whose name starts with the string get is eligible.
call com.foo.bar. get ... ...
: The ellipsis indicates that the methods can have any number of arguments.
11-16 Configuring and Using the Diagnostics Framework for Oracle WebLogic Server
call_pointcut := call returnSpec classSpec
methodSpec parameterList modifiers := modifier OR modifier modifier := public | protected |
private | static returnSpec := | typeSpec
classSpecWithAnnotations := IDENTIFIER OR IDENTIFIER | classSpec classSpec := + ? classOrMethodPattern |
typeSpec := ? primitiveType | classSpec [] methodSpec := classOrMethodPattern
parameterList := param , param param := typeSpec | ...
primitiveType := byte | char | boolean | short | int | float | long | double | void
classOrMethodPattern := ? IDENTIFIER ? |
The following rules apply:
■
Wildcards can be used in class types and method names.
■
An ellipsis ... in the argument list signifies a variable number of arguments of any types beyond the argument.
■
A percent character prefix designates the value of a non-static class instantiation, parameter, or return specification as not containing nor exposing
sensitive information. The use of this operator is particularly useful with the DisplayArgumentsAction action, which captures method arguments or return
values. If this prefix character is not explicitly used, an asterisk string is substituted for the value that is returned; this behavior ensures that sensitive data
in your application is not inadvertently transmitted when an instrumentation event captures input arguments to, or return values from, a joinpoint.
■
A + plus sign prefix to a class type identifies all subclasses, sub-interfaces or concrete classes implementing the specified classinterface pattern.
■
A pointcut expression specifies a pattern to identify matching joinpoints. An attempt to match a joinpoint against it will return a boolean, indicating a valid
match or not.
■
Pointcut expressions can be combined with AND, OR and NOT boolean operators to build complex pointcut expression trees.
For example, the following pointcut matches method executions of all public initialize methods in all classes in package com.foo.bar and its sub-packages. The initialize
methods may return values of any type, including void, and may have any number of arguments of any types.
executionpublic com.foo.bar. initialize... The following pointcut matches the method calls callsites on all classes that directly
or indirectly implement the com.foo.bar.MyInterface interface or a subclass, if it happens to be a class. The method names must start with get, be public, and return an
int value. The method must accept exactly one argument of type java.lang.String:
callint +com.foo.bar.MyInterface getjava.lang.String
Note: The operator cannot be applied to an ellipsis or to a
wildcarded type within a pointcut expression.
Configuring Instrumentation 11-17
The following example shows how to use boolean operators to build a pointcut expression tree:
callvoid com.foo.bar. setjava.lang.String OR call com.foo.bar. get
The following example illustrates how the previous expression tree would be rendered as a pointcut element in a configuration file:
pointcutcallvoid com.foo.bar. setjava.lang.String OR call com.foo.bar. getpointcut
11.5.4.2 Annotation-based Pointcuts
