JVMAspectInterface


1   //
2   //  This file is part of the prose package.
3   //
4   //  The contents of this file are subject to the Mozilla Public License
5   //  Version 1.1 (the "License"); you may not use this file except in
6   //  compliance with the License. You may obtain a copy of the License at
7   //  http://www.mozilla.org/MPL/
8   //
9   //  Software distributed under the License is distributed on an "AS IS" basis,
10  //  WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
11  //  for the specific language governing rights and limitations under the
12  //  License.
13  //
14  //  The Original Code is prose.
15  //
16  //  The Initial Developer of the Original Code is Andrei Popovici. Portions
17  //  created by Andrei Popovici are Copyright (C) 2002 Andrei Popovici.
18  //  All Rights Reserved.
19  //
20  //  Contributor(s):
21  // $Id: JVMAspectInterface.java,v 1.2 2004/05/12 09:41:54 anicoara Exp $
22  // =====================================================================
23  //
24  // (history at end)
25  //
26  
27  package ch.ethz.jvmai;
28  
29  // used packages/classes
30  import java.lang.reflect.Field  ;
31  import java.lang.reflect.Method  ;
32  import ch.ethz.jvmai.JoinPointHook;
33  import java.util.List  ;
34  
35  /**
36   * Interface JVMAspectInterface represents the
37   * aspect-interface to the jvmai-system. It's needed for
38   * initialization of the jvmai-system, management of
39   * joinpoint-watches and for enable or disable
40   * event-notification.
41   * <p>
42   * An instance of this interface can be obtained by calling
43   * the method <code>getAspectInterface()</code> of a
44   * jvmai-provider (class <code>Provider</code>).
45   *
46   * @version $Revision: 1.2 $
47   * @author  Stephan Markwalder
48   * @author  Andrei Popovici
49   * @author  Angela Nicoara
50   */
51  public interface JVMAspectInterface {
52  
53      /**
54       * Initializes the underlying jvmai system.
55       * <p>
56       * In addition, this method takes a list of java
57       * package-names and a boolean indicating how to
58       * interpret this prefixes. The prefixes are used by the
59       * jvmai system to determine the set of classes beeing
60       * relevant to the system at all. Depeding on the value
61       * of <code>openWorldAssumption</code>, prefixes are
62       * interpreted as followed:
63       * <p>
64       * <code>openWorldAssumption == true</code><br>
65       * The jvmai-system is instructed to treat ALL classes
66       * as relevant, EXCEPT the ones contained in a packages
67       * starting with one of the supplied prefixes in
68       * <code>packagePrefixes</code>
69       * <p>
70       * <code>openWorldAssumption == false</code><br>
71       * The jvmai-system is instructed to treat as relevant
72       * ONLY the classes contained in a packages starting
73       * with one of the supplied prefixes in
74       * <code>packagePrefixes</code>
75       *
76       * @param packagePrefixes List of prefixes for java
77       *                        package-names.
78       * @param openWorldAssumption Specifies how the prefixes
79       *                            are interpreted.
80       * @exception StartupException Use <code>StartupException.getMessage()</code>
81       *                             to get a detailed description
82       */
83      public void startup(String  [] packagePrefixes, boolean openWorldAssumption);
84  
85    /** Teardown the AOP support. As a result,
86     *  no events will be sent to the JoinPointHook.
87     */
88    public void teardown();
89  
90      /**
91       * Sets a JoinPointHook as listener for jvmai-events.
92       * Whenever a watched joinpoint is reached or a class is
93       * loaded into the virtual machine, this JoinPointHook
94       * is notified by the aspect-interface. As long as no
95       * JoinPointHook is set (or after setting
96       * <code>null</code>), processing of joinpoint- and
97       * classload-events is disabled in the jvmai-system.
98       *
99       * @param hook JoinPointHook to set as listener.
100      * @exception NotInitializedException Aspect-interface has not been
101      *                                    initialized yet. Call <code>setup</code> first.
102      */
103     public void setJoinPointHook(JoinPointHook hook);
104 
105     /**
106      * Sets a watch on a field access joinpoint.
107      *
108      * @param f the field to be watched.
109      * @param aopTag A user-defined object saved with this watch.
110      *               When the joinpoint is reached, this object is
111      *               passed to the JoinPointHook as part of the
112      *               JoinPoint-instance. This object may be <code>null</code>.
113      * @exception NotInitializedException Aspect-interface has not been initialized yet. Call <code>setup</code> first.
114      * @exception NullPointerException <code>f</code> is <code>null</code>.
115      * @exception IllegalArgumentException  or <code>aopTag<code> is null
116      * @exception CannotSetWatchException ?
117      * @exception WatchAlreadySetException There already exists a access-watch on the field.
118      */
119     public void setFieldAccessWatch(Field   f, Object   aopTag);
120 
121     /**
122      * Clears a watch on a field access joinpoint.
123      *
124      * @param f Field declaring the field beeing watched.
125      * @exception NotInitializedException Aspect-interface has not been initialized yet. Call <code>setup</code> first.
126      * @exception NullPointerException <code>f</code> is <code>null</code>.
127      * @exception IllegalArgumentException  or <code>aopTag<code> is null
128      * @exception WatchNotSetException There exists no access-watch on the field.
129      */
130     public void clearFieldAccessWatch(Field   f);
131 
132     /**
133      * Sets a watch on a field modification joinpoint.
134      *
135      * @param field the field to be watched.
136      * @param aopTag A user-defined object saved with this watch.
137      *             When the joinpoint is reached, this object is
138      *             passed to the JoinPointHook as part of the
139      *             JoinPoint-instance. This object may be <code>null</code>.
140      * @exception NotInitializedException Aspect-interface has not been initialized yet. Call <code>setup</code> first.
141      * @exception NullPointerException <code>cls</code> is <code>null</code>.
142      * @exception IllegalArgumentException  <code>aopTag<code> is null
143      * @exception CannotSetWatchException ?
144      * @exception WatchAlreadySetException There already exists a modification-watch on the field.
145      */
146     public void setFieldModificationWatch(Field   f, Object   aopTag);
147 
148     /**
149      * Clears a watch on a field modification joinpoint.
150      *
151      * @param f the field beeing watched, whose watch should be cleared
152      * @exception NotInitializedException Aspect-interface has not been initialized yet. Call <code>setup</code> first.
153      * @exception NullPointerException <code>f</code> is <code>null</code>.
154      * @exception IllegalArgumentException  <code>aopTag<code> is null
155      * @exception WatchNotSetException There exists no modification-watch on the field.
156      */
157     public void clearFieldModificationWatch(Field   f);
158 
159     /**
160      * Sets a watch on a method entry joinpoint.
161      *
162      * @param m  the method to be watched.
163      * @param aopTag A user-defined object saved with this watch.
164      *             When the joinpoint is reached, this object is
165      *             passed to the JoinPointHook as part of the
166      *             JoinPoint-instance. This object may be <code>null</code>.
167      * @exception NotInitializedException Aspect-interface has not been initialized yet. Call <code>setup</code> first.
168      * @exception NullPointerException <code>cls</code> is <code>null</code>.
169      * @exception IllegalArgumentException  <code>aopTag<code> is null
170      * @exception CannotSetWatchException The method must not be abstract or native.
171      * @exception WatchAlreadySetException There already exists a entry-watch on the method.
172      */
173     public void setMethodEntryWatch(Method   m, Object   aopTag);
174 
175     /**
176      * Clears a watch on a method entry joinpoint.
177      *
178      * @param m  the method beeing watched.
179      * @exception NotInitializedException Aspect-interface has not been initialized yet. Call <code>setup</code> first.
180      * @exception NullPointerException <code>cls</code> is <code>null</code>.
181      * @exception IllegalArgumentException  <code>aopTag<code> is null
182      * @exception WatchNotSetException There exists no entry-watch on the method.
183      */
184     public void clearMethodEntryWatch(Method   m);
185 
186     /**
187      * Sets a watch on a method exit joinpoint.
188      *
189      * @param m the method to be watched.
190      * @param aopTag A user-defined object saved with this watch.
191      *             When the joinpoint is reached, this object is
192      *             passed to the JoinPointHook as part of the
193      *             JoinPoint-instance. This object may be <code>null</code>.
194      * @exception NotInitializedException Aspect-interface has not been initialized yet. Call <code>setup</code> first.
195      * @exception NullPointerException <code>cls</code> is <code>null</code>.
196      * @exception IllegalArgumentException  <code>aopTag<code> is null
197      * @exception CannotSetWatchException The method must not be abstract or native.
198      * @exception WatchAlreadySetException There already exists a exit-watch on the method.
199      */
200     public void setMethodExitWatch(Method   m,Object   aopTag);
201 
202     /**
203      * Clears a watch on a method exit joinpoint.
204      *
205      * @param m  the method beeing watched.
206      * @exception NotInitializedException Aspect-interface has not been initialized yet. Call <code>setup</code> first.
207      * @exception NullPointerException <code>cls</code> is <code>null</code>.
208      * @exception IllegalArgumentException  <code>aopTag<code> is null
209      * @exception WatchNotSetException There exists no exit-watch on the method.
210      */
211     public void clearMethodExitWatch(Method   m);
212 
213         /**
214          * Sets a watch on a exception throw joinpoint.
215          *
216          * @param cls Class of the watched exception. All exceptions
217          * thows with exception classes that  <em>is the same </em> as
218          * cls will be captured by corresponding join-points.
219          * @param aopTag A user-defined object saved with this watch.
220          *               When the joinpoint is reached, this object is
221          *               passed to the JoinPointHook as part of the
222          *               JoinPoint-instance. This object may be <code>null</code>.
223          * @exception NotInitializedException Aspect-interface has not been initialized yet. Call <code>setup</code> first.
224          * @exception NullPointerException <code>cls</code> is <code>null</code>.
225      * @exception IllegalArgumentException  <code>aopTag<code> is null
226          * @exception WatchAlreadySetException There already exists a exceptionThrow-watch at this point.
227          */
228         public void setExceptionThrowWatch(Class   cls, Object   aopTag);
229 
230         /**
231          * Clears a watch on a exception throw joinpoint.
232          *
233          * @param cls Class of the watched exception.
234          * @exception NotInitializedException Aspect-interface has not been initialized yet. Call <code>setup</code> first.
235          * @exception NullPointerException <code>cls</code> is <code>null</code>.
236          * @exception IllegalArgumentException  <code>aopTag<code> is null
237      * @exception WatchNotSetException There exists no exceptionThrow-watch at this point.
238          */
239         public void clearExceptionThrowWatch(Class   cls);
240 
241     /**
242      * Sets a watch on a exception catch joinpoint.
243      *
244      * @param cls Class of the watched exception. All exceptions
245      * thows with exception classes that  <em>is the same </em> as
246      * cls will be captured by corresponding join-points.
247      * @param aopTag A user-defined object saved with this watch.
248      *               When the joinpoint is reached, this object is
249      *               passed to the JoinPointHook as part of the
250      *               JoinPoint-instance. This object may be <code>null</code>.
251      * @exception NotInitializedException Aspect-interface has not been initialized yet. Call <code>setup</code> first.
252      * @exception NullPointerException <code>cls</code> is <code>null</code>.
253      * @exception IllegalArgumentException  <code>aopTag<code> is null
254      * @exception WatchAlreadySetException There already exists a exceptionCatch-watch at this point.
255      */
256     public void setExceptionCatchWatch(Class   cls, Object   aopTag);
257     
258     /**
259      * Clears a watch on a exception catch joinpoint.
260      *
261      * @param cls Class of the watched exception.
262      * @exception NotInitializedException Aspect-interface has not been initialized yet. Call <code>setup</code> first.
263      * @exception NullPointerException <code>cls</code> is <code>null</code>.
264      * @exception IllegalArgumentException  <code>aopTag<code> is null
265      * @exception WatchNotSetException There exists no exceptionCatch-watch at this point.
266      */
267     public void clearExceptionCatchWatch(Class   cls);  
268 
269 
270     /**
271      * Suspend notification regarding the specified thread.
272      * Successive calls to <code>suspendNotification</code>
273      * are idempotent. That is, <em>n</em> successive calls to
274      * <code>suspendNotification</code> is equivalent to one
275      * call to <code>suspendNotification</code>
276      * is equivalen
277      *
278      * @param thread Thread for which to disable notification.
279      * @exception NotInitializedException Aspect-interface has not been initialized yet. Call <code>setup</code> first.
280      * @exception NullPointerException <code>thread</code> is <code>null</code>.
281      */
282     public void suspendNotification(Thread   thread);
283 
284     /**
285      * Resumes notification regarding the specified thread.
286      * Successive calls to <code>resumeNotification</code>
287      * without preceding calls to <code>suspendNotification</code>
288      * will be ignored.
289      *
290      * @param thread Thread for which to reenable notification.
291      * @exception NotInitializedException Aspect-interface has not been initialized yet. Call <code>setup</code> first.
292      * @exception NullPointerException <code>thread</code> is <code>null</code>.
293      */
294     public void resumeNotification(Thread   thread);
295 
296     /** Return a list of currently loaded clasess.
297      *
298      */
299     public  List   getLoadedClasses();
300 
301 }
302 
303 //======================================================================
304 //
305 // $Log: JVMAspectInterface.java,v $
306 // Revision 1.2  2004/05/12 09:41:54  anicoara
307 // Remove the README.RVM file
308 //
309 // Revision 1.1.1.1  2003/07/02 15:30:50  apopovic
310 // Imported from ETH Zurich
311 //
312 // Revision 1.2  2003/07/02 12:42:49  anicoara
313 // Added CatchJoinPoint Functionality (Requests, Join-Points, Filters, CatchCuts, Tests)
314 //
315 // Revision 1.1  2003/05/05 14:02:23  popovici
316 // renaming from runes to prose
317 //
318 // Revision 1.7  2003/03/04 11:27:04  popovici
319 // Important refactorization step (march):
320 // - removal of 'JoinPointEvents'; JoinPoints now have the same function as events
321 // - reimplementation of the JVMAIDebuggerAspectInterface (better performance, coding conventions, removal of ProseVM
322 //   structures
323 //
324 // Revision 1.6  2002/10/17 12:23:42  pschoch
325 // Added throw capabability to JVMAI
326 //
327 // Revision 1.5  2002/09/21 14:04:33  popovici
328 // Bug 0000010 fixed. Added 'teardown' procedure
329 // in the JVMAI, Jikes & JDK prose implementation
330 //
331 // Revision 1.4  2002/03/28 13:48:27  popovici
332 // Mozilla-ified
333 //
334 // Revision 1.3  2002/02/13 12:25:45  smarkwal
335 // spaces/tabs alignment corrected
336 //
337 // Revision 1.2  2002/01/24 12:59:38  smarkwal
338 // Comments added.
339 //
340 // Revision 1.1  2001/12/14 15:01:17  smarkwal
341 // Initial Revision
342 //
343
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags