Hook File Structure

The following section describes the structure of a typical .hooks file:

The hook files are structured as .ini files where each section represents a
hook definition. Regular expressions are supported in some of the entries.
Any entry that uses regular expression must start with a '!'.
Hook-Name
Specifies the name of this section in the hooks file. Hook-Name must be
unique across all hooks files. A good practice is to give the fully qualified
class name and method. For example:
[javax.jms.Queue.getQueueName]
Class
A fully qualified class name. Regular expression can be used to include
several classes from the same package, a whole package, several packages, or
any class that matches a name. For example:
Class = !javax\.jms\.*
[Hook-Name]
class = MyPackage.MyClass
method = MyMethod
signature = ()V
ignore_cl =
ignore_mtd =
ignore_tree =
cb_class = mercury.ProtocolSupport
cb_mtd =
general_cb = true
deep_mode = soft | hard
make_methods_public = true | false
lock = true | false
Chapter 21 Java Protocol
709
Method
The simple name of the method to include. Regular expressions can be used
to include more than one method from the class. For example:
Method = getQueueName
Signature
The standard Java internal type signature of the method. To determine the
signature of a method, run the command javap -s class-name where class
name is the fully qualified name of the class. Regular expressions can be
used to include several methods with the same name, but with different
arguments. For example:
Signature = !.*
ignore_cl
A specific class to ignore from the classes that match this hook. This can be a
list of comma separated class names. Each item in the list can contain a
regular expression. If an item in the list contains a regular expression,
prepend a '!' to the class name. For example:
Ignore_cl = !com.hp.jms.Queue,!com\.hp\..*
ignore_mtd
A specific method to ignore. When the loaded class method matches this
hook definition, this method will not be hooked. The method name must
be the simple method name followed by the signature (as explained above).
To ignore multiple methods, list them in a comma separated list. To use a
regular expression, prepend a '!' to the method name. For example:
Ignore_cl = open, close
ignore_tree
A specific tree to ignore. When the name of the class matches the ignore tree
expression, any class that inherits from it will not be hooked, if it matches
this hooks definition. To ignore multiple trees, list them in a comma
separated list. To use a regular expression, prepend a '!' to the class name.
This option is relevant only for hooks that are defined as deep.
Chapter 21 Java Protocol
710
cb_class
The callback class that gets the call from the hooked method. It should
always be set to mercury.ProtocolSupport.
cb_mtd
A method in the callback class that gets the call from the hooked method. If
omitted, it uses the default, general_rec_func. For cases where you just need
to lock the subtree of calls, use general_func instead.
general_cb
The general callback method. This value should always be set to true.
Deep_mode
Deep mode refers to classes and interfaces that inherit or implement the
class or interface that the hook is listed for. The inherited classes will be
hooked according to the type of hook: Hard, Soft, or Off.
Hard. Hooks the current class and any class that inherits from it. If regular
expressions exist, they are matched against every class that inherits from
the class in the hook definition. Interface inheritance is treated the same
as class inheritance.
Soft. Hooks the current class and any class that inherits from it, only if
the methods are overridden in the inheriting class. If the hook lists an
interface, then if a class implements this interface those methods will be
hooked. If they exist in classes that directly inherit from that class they
will also be hooked. However, if the hook lists an interface and a class
implements a second interface that inherits from this interface, the class
will not be hooked.
Note: Regular expressions are not inherited but converted to actual
methods.
Off. Only the class listed in the hook definition and the direct inheriting
class will be hooked. If the hook lists an interface, only classes that
directly implement it will be hooked.
Chapter 21 Java Protocol
711
make_methods_public:
Any method that matches the hook definition will be converted to public.
This is useful for custom hooks or for locking a sub tree of calls from a
non-public method.
Note that this applies only during record. During replay, the method will
use the original access flags. In the case of non-public methods, it will throw
java.lang.VerifyError.
Lock
When set to true, it locks the sub tree and prevents the calling of any
method originating from the original method.
When set to false, it will unlock the sub tree, record any method originating
from the current method (if it is hooked), and invok