The following section describes the structure of a typical .hooks file:
[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
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 '!'.
Note: When you use a filter such as !.* then the ! indicates the beginning of a RegExp—not a Regexp negation.
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:
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. The following example filters for any class that starts with javax.jms and is followed by at least one character.
class = !javax\.jms\.*
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
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 = !.* will match any possible signature, thus causing any method in this class to be recorded into the script regardless of signature.
signature = !\(Lorg/omg/CORBA/ORB;\).* will match any signature starting with
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\..*
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
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.
The callback class that gets the call from the hooked method. It should always be set to mercury.ProtocolSupport.
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.
The general callback method. This value should always be set to true.
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.
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
When set to true (default), 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 invoke the callback.