KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > alt > jiapi > instrumentor > Hook


1 /*
2  * Copyright (C) 2001 Mika Riekkinen, Joni Suominen
3  *
4  * This library is free software; you can redistribute it and/or
5  * modify it under the terms of the GNU Lesser General Public
6  * License as published by the Free Software Foundation; either
7  * version 2.1 of the License, or (at your option) any later version.
8  *
9  * This library is distributed in the hope that it will be useful,
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12  * Lesser General Public License for more details.
13  *
14  * You should have received a copy of the GNU Lesser General Public
15  * License along with this library; if not, write to the Free Software
16  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
17  */
18
19 package alt.jiapi.instrumentor;
20
21 import java.lang.reflect.Method JavaDoc;
22
23 /**
24  * This interface defines methods, which is used by
25  * MethodCallInstrumentor, to query Hooks about which method is to be called.
26  * This interface is not the actual hook that is to be called. Rather,
27  * it is a container that specifies which method is to be called, and what
28  * is the Object instance, that a method call should be made on.
29  *
30  * @author Mika Riekkinen
31  * @author Joni Suominen
32  * @see MethodCallInstrumentor
33  * @version $Revision: 1.4 $ $Date: 2002/03/20 12:15:59 $
34  */
35 public interface Hook {
36     /**
37      * Get the method, that is to be called. Hook method must conform to the
38      * following rules.
39      *
40      * <ul>
41      * <li>Method has to be accessible from any class. I.e. it has to be
42      * public.
43      * <li>Possible arguments, that may be passed to Hook method, are
44      * <ol>
45      * <li>Source Object (Object). 'this' If current method is dynamic, or
46      * String naming the current class.
47      * <li>Target name (String). This might be name of the current method,
48      * name of the field, or similar.
49      * <li>Target Object (Object). This is the target that we are operating
50      * on. For example, it could be Exception just caught. Or Object,
51      * method invocation is being made upon. Or Object, whose field
52      * we are accessing.
53      * <li>Target arguments (Object[]). For example, method parameters,
54      * parameters of the current method, etc.
55      * </ol>
56      *
57      * The order of the parameters is not significant. They may appear in
58      * any order, except that source object is allways the first one. For
59      * example, one cannot switch the position of source object and target
60      * object, but target name and target object may be switched.
61      *
62      * <li>Hook method may not want some of the arguments. In that case,
63      * hook method may just drop that argument, and it will be skipped.
64      * For example, if Hook method is declared as
65      * <blockquote>
66      * <code>void myMethod(Object, Object);</code>
67      * </blockquote>
68      *
69      * then target name and target arguments are not passed to hook method.
70      * Hook method is then interpreted as
71      * <blockquote>
72      * <code>void myMethod(&lt;source Object&gt;, &lt;target Object&gt;);
73      * </code>
74      * </blockquote>
75      *
76      *
77      * @return A reflection method, that is to be called
78      * @see #getInstance()
79      */
80     public Method JavaDoc getHookMethod();
81
82     /**
83      * Gets an instance of Object, that is declaring a Method this
84      * hook is referring to.
85      * It is possible to implement this interface, without declaring
86      * hook-method. In that case, this method must
87      * returns an instance of the Object declaring actual hook-method.
88      * If hook-method is declared by the implementing class, it should
89      * return <i>this</i>.
90      *
91      * @return instance of the Object, that contains reflection method
92      * specified by getHookMethod();
93      * @see #getHookMethod()
94      */
95     public Object JavaDoc getInstance();
96 }
97
Popular Tags