001: //
002: // This file is part of the prose package.
003: //
004: // The contents of this file are subject to the Mozilla Public License
005: // Version 1.1 (the "License"); you may not use this file except in
006: // compliance with the License. You may obtain a copy of the License at
007: // http://www.mozilla.org/MPL/
008: //
009: // Software distributed under the License is distributed on an "AS IS" basis,
010: // WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
011: // for the specific language governing rights and limitations under the
012: // License.
013: //
014: // The Original Code is prose.
015: //
016: // The Initial Developer of the Original Code is Andrei Popovici. Portions
017: // created by Andrei Popovici are Copyright (C) 2002 Andrei Popovici.
018: // All Rights Reserved.
019: //
020: // Contributor(s):
021: // $Id: JVMAspectInterface.java,v 1.2 2004/05/12 09:41:54 anicoara Exp $
022: // =====================================================================
023: //
024: // (history at end)
025: //
026:
027: package ch.ethz.jvmai;
028:
029: // used packages/classes
030: import java.lang.reflect.Field;
031: import java.lang.reflect.Method;
032: import java.lang.reflect.Constructor;
033: import java.util.List;
034:
035: /**
036: * Interface JVMAspectInterface represents the
037: * aspect-interface to the jvmai-system. It's needed for
038: * initialization of the jvmai-system, management of
039: * joinpoint-watches and for enable or disable
040: * event-notification.
041: * <p>
042: * An instance of this interface can be obtained by calling
043: * the method <code>getAspectInterface()</code> of a
044: * jvmai-provider (class <code>Provider</code>).
045: *
046: * @version $Revision: 1.2 $
047: * @author Stephan Markwalder
048: * @author Andrei Popovici
049: * @author Angela Nicoara
050: */
051: public interface JVMAspectInterface {
052:
053: /**
054: * Initializes the underlying jvmai system.
055: * <p>
056: * In addition, this method takes a list of java
057: * package-names and a boolean indicating how to
058: * interpret this prefixes. The prefixes are used by the
059: * jvmai system to determine the set of classes beeing
060: * relevant to the system at all. Depeding on the value
061: * of <code>openWorldAssumption</code>, prefixes are
062: * interpreted as followed:
063: * <p>
064: * <code>openWorldAssumption == true</code><br>
065: * The jvmai-system is instructed to treat ALL classes
066: * as relevant, EXCEPT the ones contained in a packages
067: * starting with one of the supplied prefixes in
068: * <code>packagePrefixes</code>
069: * <p>
070: * <code>openWorldAssumption == false</code><br>
071: * The jvmai-system is instructed to treat as relevant
072: * ONLY the classes contained in a packages starting
073: * with one of the supplied prefixes in
074: * <code>packagePrefixes</code>
075: *
076: * @param packagePrefixes List of prefixes for java
077: * package-names.
078: * @param openWorldAssumption Specifies how the prefixes
079: * are interpreted.
080: * @exception StartupException Use <code>StartupException.getMessage()</code>
081: * to get a detailed description
082: */
083: public void startup(String[] packagePrefixes,
084: boolean openWorldAssumption);
085:
086: /** Teardown the AOP support. As a result,
087: * no events will be sent to the JoinPointHook.
088: */
089: public void teardown();
090:
091: /**
092: * Sets a JoinPointHook as listener for jvmai-events.
093: * Whenever a watched joinpoint is reached or a class is
094: * loaded into the virtual machine, this JoinPointHook
095: * is notified by the aspect-interface. As long as no
096: * JoinPointHook is set (or after setting
097: * <code>null</code>), processing of joinpoint- and
098: * classload-events is disabled in the jvmai-system.
099: *
100: * @param hook JoinPointHook to set as listener.
101: * @exception NotInitializedException Aspect-interface has not been
102: * initialized yet. Call <code>setup</code> first.
103: */
104: public void setJoinPointHook(JoinPointHook hook);
105:
106: /**
107: * Sets a watch on a field access joinpoint.
108: *
109: * @param f the field to be watched.
110: * @param aopTag A user-defined object saved with this watch.
111: * When the joinpoint is reached, this object is
112: * passed to the JoinPointHook as part of the
113: * JoinPoint-instance. This object may be <code>null</code>.
114: * @exception NotInitializedException Aspect-interface has not been initialized yet. Call <code>setup</code> first.
115: * @exception NullPointerException <code>f</code> is <code>null</code>.
116: * @exception IllegalArgumentException or <code>aopTag<code> is null
117: * @exception CannotSetWatchException ?
118: * @exception WatchAlreadySetException There already exists a access-watch on the field.
119: */
120: public void setFieldAccessWatch(Field f, Object aopTag);
121:
122: /**
123: * Clears a watch on a field access joinpoint.
124: *
125: * @param f Field declaring the field beeing watched.
126: * @exception NotInitializedException Aspect-interface has not been initialized yet. Call <code>setup</code> first.
127: * @exception NullPointerException <code>f</code> is <code>null</code>.
128: * @exception IllegalArgumentException or <code>aopTag<code> is null
129: * @exception WatchNotSetException There exists no access-watch on the field.
130: */
131: public void clearFieldAccessWatch(Field f);
132:
133: /**
134: * Sets a watch on a field modification joinpoint.
135: *
136: * @param f the field to be watched.
137: * @param aopTag A user-defined object saved with this watch.
138: * When the joinpoint is reached, this object is
139: * passed to the JoinPointHook as part of the
140: * JoinPoint-instance. This object may be <code>null</code>.
141: * @exception NotInitializedException Aspect-interface has not been initialized yet. Call <code>setup</code> first.
142: * @exception NullPointerException <code>cls</code> is <code>null</code>.
143: * @exception IllegalArgumentException <code>aopTag<code> is null
144: * @exception CannotSetWatchException ?
145: * @exception WatchAlreadySetException There already exists a modification-watch on the field.
146: */
147: public void setFieldModificationWatch(Field f, Object aopTag);
148:
149: /**
150: * Clears a watch on a field modification joinpoint.
151: *
152: * @param f the field beeing watched, whose watch should be cleared
153: * @exception NotInitializedException Aspect-interface has not been initialized yet. Call <code>setup</code> first.
154: * @exception NullPointerException <code>f</code> is <code>null</code>.
155: * @exception IllegalArgumentException <code>aopTag<code> is null
156: * @exception WatchNotSetException There exists no modification-watch on the field.
157: */
158: public void clearFieldModificationWatch(Field f);
159:
160: /**
161: * Sets a watch on a method entry joinpoint.
162: *
163: * @param m the method to be watched.
164: * @param aopTag A user-defined object saved with this watch.
165: * When the joinpoint is reached, this object is
166: * passed to the JoinPointHook as part of the
167: * JoinPoint-instance. This object may be <code>null</code>.
168: * @exception NotInitializedException Aspect-interface has not been initialized yet. Call <code>setup</code> first.
169: * @exception NullPointerException <code>cls</code> is <code>null</code>.
170: * @exception IllegalArgumentException <code>aopTag<code> is null
171: * @exception CannotSetWatchException The method must not be abstract or native.
172: * @exception WatchAlreadySetException There already exists a entry-watch on the method.
173: */
174: public void setMethodEntryWatch(Method m, Object aopTag);
175:
176: /**
177: * Clears a watch on a method entry joinpoint.
178: *
179: * @param m the method beeing watched.
180: * @exception NotInitializedException Aspect-interface has not been initialized yet. Call <code>setup</code> first.
181: * @exception NullPointerException <code>cls</code> is <code>null</code>.
182: * @exception IllegalArgumentException <code>aopTag<code> is null
183: * @exception WatchNotSetException There exists no entry-watch on the method.
184: */
185: public void clearMethodEntryWatch(Method m);
186:
187: /**
188: * Sets a watch on a constructor joinpoint.
189: *
190: * @param m the constructor to be watched.
191: * @param aopTag A user-defined object saved with this watch.
192: * When the joinpoint is reached, this object is
193: * passed to the JoinPointHook as part of the
194: * JoinPoint-instance. This object may be <code>null</code>.
195: * @exception NotInitializedException Aspect-interface has not been initialized yet. Call <code>setup</code> first.
196: * @exception NullPointerException <code>cls</code> is <code>null</code>.
197: * @exception IllegalArgumentException <code>aopTag<code> is null
198: * @exception CannotSetWatchException The method must not be abstract or native.
199: * @exception WatchAlreadySetException There already exists a entry-watch on the method.
200: */
201: public void setConstructorWatch(Constructor m, Object aopTag);
202:
203: /**
204: * Clears a watch on a constructor joinpoint.
205: *
206: * @param m the constructor beeing watched.
207: * @exception NotInitializedException Aspect-interface has not been initialized yet. Call <code>setup</code> first.
208: * @exception NullPointerException <code>cls</code> is <code>null</code>.
209: * @exception IllegalArgumentException <code>aopTag<code> is null
210: * @exception WatchNotSetException There exists no entry-watch on the method.
211: */
212: public void clearConstructorWatch(Constructor m);
213:
214: /**
215: * Sets a watch on a method exit joinpoint.
216: *
217: * @param m the method to be watched.
218: * @param aopTag A user-defined object saved with this watch.
219: * When the joinpoint is reached, this object is
220: * passed to the JoinPointHook as part of the
221: * JoinPoint-instance. This object may be <code>null</code>.
222: * @exception NotInitializedException Aspect-interface has not been initialized yet. Call <code>setup</code> first.
223: * @exception NullPointerException <code>cls</code> is <code>null</code>.
224: * @exception IllegalArgumentException <code>aopTag<code> is null
225: * @exception CannotSetWatchException The method must not be abstract or native.
226: * @exception WatchAlreadySetException There already exists a exit-watch on the method.
227: */
228: public void setMethodExitWatch(Method m, Object aopTag);
229:
230: /**
231: * Clears a watch on a method exit joinpoint.
232: *
233: * @param m the method beeing watched.
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 exit-watch on the method.
238: */
239: public void clearMethodExitWatch(Method m);
240:
241: /**
242: * Sets a watch on a exception throw 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 exceptionThrow-watch at this point.
255: */
256: public void setExceptionThrowWatch(Class cls, Object aopTag);
257:
258: /**
259: * Clears a watch on a exception throw 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 exceptionThrow-watch at this point.
266: */
267: public void clearExceptionThrowWatch(Class cls);
268:
269: /**
270: * Sets a watch on a exception catch joinpoint.
271: *
272: * @param cls Class of the watched exception. All exceptions
273: * thows with exception classes that <em>is the same </em> as
274: * cls will be captured by corresponding join-points.
275: * @param aopTag A user-defined object saved with this watch.
276: * When the joinpoint is reached, this object is
277: * passed to the JoinPointHook as part of the
278: * JoinPoint-instance. This object may be <code>null</code>.
279: * @exception NotInitializedException Aspect-interface has not been initialized yet. Call <code>setup</code> first.
280: * @exception NullPointerException <code>cls</code> is <code>null</code>.
281: * @exception IllegalArgumentException <code>aopTag<code> is null
282: * @exception WatchAlreadySetException There already exists a exceptionCatch-watch at this point.
283: */
284: public void setExceptionCatchWatch(Class cls, Object aopTag);
285:
286: /**
287: * Clears a watch on a exception catch joinpoint.
288: *
289: * @param cls Class of the watched exception.
290: * @exception NotInitializedException Aspect-interface has not been initialized yet. Call <code>setup</code> first.
291: * @exception NullPointerException <code>cls</code> is <code>null</code>.
292: * @exception IllegalArgumentException <code>aopTag<code> is null
293: * @exception WatchNotSetException There exists no exceptionCatch-watch at this point.
294: */
295: public void clearExceptionCatchWatch(Class cls);
296:
297: /**
298: * Suspend notification regarding the specified thread.
299: * Successive calls to <code>suspendNotification</code>
300: * are idempotent. That is, <em>n</em> successive calls to
301: * <code>suspendNotification</code> is equivalent to one
302: * call to <code>suspendNotification</code>
303: * is equivalen
304: *
305: * @param thread Thread for which to disable notification.
306: * @exception NotInitializedException Aspect-interface has not been initialized yet. Call <code>setup</code> first.
307: * @exception NullPointerException <code>thread</code> is <code>null</code>.
308: */
309: public void suspendNotification(Thread thread);
310:
311: /**
312: * Resumes notification regarding the specified thread.
313: * Successive calls to <code>resumeNotification</code>
314: * without preceding calls to <code>suspendNotification</code>
315: * will be ignored.
316: *
317: * @param thread Thread for which to reenable notification.
318: * @exception NotInitializedException Aspect-interface has not been initialized yet. Call <code>setup</code> first.
319: * @exception NullPointerException <code>thread</code> is <code>null</code>.
320: */
321: public void resumeNotification(Thread thread);
322:
323: /** Return a list of currently loaded clasess.
324: *
325: */
326: public List getLoadedClasses();
327:
328: }
329:
330: //======================================================================
331: //
332: // $Log: JVMAspectInterface.java,v $
333: // Revision 1.2 2004/05/12 09:41:54 anicoara
334: // Remove the README.RVM file
335: //
336: // Revision 1.1.1.1 2003/07/02 15:30:50 apopovic
337: // Imported from ETH Zurich
338: //
339: // Revision 1.2 2003/07/02 12:42:49 anicoara
340: // Added CatchJoinPoint Functionality (Requests, Join-Points, Filters, CatchCuts, Tests)
341: //
342: // Revision 1.1 2003/05/05 14:02:23 popovici
343: // renaming from runes to prose
344: //
345: // Revision 1.7 2003/03/04 11:27:04 popovici
346: // Important refactorization step (march):
347: // - removal of 'JoinPointEvents'; JoinPoints now have the same function as events
348: // - reimplementation of the JVMAIDebuggerAspectInterface (better performance, coding conventions, removal of ProseVM
349: // structures
350: //
351: // Revision 1.6 2002/10/17 12:23:42 pschoch
352: // Added throw capabability to JVMAI
353: //
354: // Revision 1.5 2002/09/21 14:04:33 popovici
355: // Bug 0000010 fixed. Added 'teardown' procedure
356: // in the JVMAI, Jikes & JDK prose implementation
357: //
358: // Revision 1.4 2002/03/28 13:48:27 popovici
359: // Mozilla-ified
360: //
361: // Revision 1.3 2002/02/13 12:25:45 smarkwal
362: // spaces/tabs alignment corrected
363: //
364: // Revision 1.2 2002/01/24 12:59:38 smarkwal
365: // Comments added.
366: //
367: // Revision 1.1 2001/12/14 15:01:17 smarkwal
368: // Initial Revision
369: //
|