KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > debug > core > DebugEvent


1 /*******************************************************************************
2  * Copyright (c) 2000, 2006 IBM Corporation and others.
3  * All rights reserved. This program and the accompanying materials
4  * are made available under the terms of the Eclipse Public License v1.0
5  * which accompanies this distribution, and is available at
6  * http://www.eclipse.org/legal/epl-v10.html
7  *
8  * Contributors:
9  * IBM Corporation - initial API and implementation
10  *******************************************************************************/
11 package org.eclipse.debug.core;
12
13
14 import java.util.EventObject JavaDoc;
15
16 import org.eclipse.debug.internal.core.DebugCoreMessages;
17
18 /**
19  * A debug event describes an event in a program being debugged or
20  * in a running process. Debug models and process implementations
21  * are required to generate debug events as specified by this class.
22  * <p>
23  * The following list defines the events generated for each debug
24  * model element.
25  * The <code>getSource()</code> method of a debug event
26  * returns the element associated with the event.
27  * Creation events are guaranteed to occur in a top
28  * down order - that is, parents are created before children.
29  * Termination events are guaranteed to occur in a bottom up order -
30  * that is, children before parents. However, termination events are not guaranteed
31  * for all elements that are created. That is, terminate events can be coalesced - a
32  * terminate event for a parent signals that all children have been terminated.
33  * </p>
34  * <p>
35  * A debug model may define model specific events by specifying a debug event
36  * kind of <code>MODEL_SPECIFIC</code>. A model specific event is identified by the
37  * event source (i.e. by the debug model that generated the event). The detail of
38  * a model specific event is client defined. Note that model specific events are
39  * not understood by the debug platform, and are thus ignored.
40  * </p>
41  * <p>
42  * The generic <code>CHANGE</code> event can be fired at any time by any element.
43  * Generally, a client of a debug model, such as as a UI, can get sufficient
44  * information to update by listening/responding to the other event kinds. However,
45  * if a debug model needs to inform clients of a change that is not specified
46  * by create/terminate/suspend/resume, the <code>CHANGE</code> event may be used.
47  * For example, generally, the only way a thread or any of its children can change
48  * state between a suspend and resume operation, is if the thread or owning debug
49  * target is terminated. However, if a debug model supports some other operation
50  * that would allow a debug element to change state while suspended, the debug model
51  * would fire a change event for that element. The valid detail codes for a
52  * change event are:<ul>
53  * <li><code>STATE</code> - indicates the state of an element has changed, but its
54  * children are not affected. A client would use a state change event to update
55  * a label of the affected element, but would not update any children.</li>
56  * <li><code>CONTENT</code> - indicates that a debug element's value or contents have
57  * changed in some way. For example, when the value of a variable is changed
58  * explicitly, the variable should fire a content change event.</li>
59  * </ul>
60  * </p>
61  * <ul>
62  * <li><code>IProcess</code>
63  * <ul>
64  * <li><code>CREATE</code> - a process has been created and is executing.</li>
65  * <li><code>TERMINATE</code> - a process has terminated.</li>
66  * </ul>
67  * <li><code>IDebugTarget</code>
68  * <ul>
69  * <li><code>CREATE</code> - a debug target has been created and is ready
70  * to begin a debug session.</li>
71  * <li><code>TERMINATE</code> - a debug target has terminated and the debug
72  * session has ended.</li>
73  * <li><code>SUSPEND</code> - a debug target has suspended. Event detail provides
74  * the reason for the suspension:<ul>
75  * <li><code>STEP_END</code> - a request to step has completed</li>
76  * <li><code>BREAKPOINT</code> - a breakpoint has been hit</li>
77  * <li><code>CLIENT_REQUEST</code> - a client request has caused the target to suspend
78  * (i.e. an explicit call to <code>suspend()</code>)</li>
79  * <li><code>UNSPECIFIED</code> - the reason for the suspend is not specified</li>
80  * </ul>
81  * </li>
82  * <li><code>RESUME</code> - a debug target has resumed. Event detail provides
83  * the reason for the resume:<ul>
84  * <li><code>STEP_INTO</code> - a target is being resumed because of a request to step into</li>
85  * <li><code>STEP_OVER</code> - a target is being resumed because of a request to step over</li>
86  * <li><code>STEP_RETURN</code> - a target is being resumed because of a request to step return</li>
87  * <li><code>CLIENT_REQUEST</code> - a client request has caused the target to be resumed
88  * (i.e. an explicit call to <code>resume()</code>)</li>
89  * <li><code>UNSPECIFIED</code> - The reason for the resume is not specified</li>
90  * </ul>
91  * </li>
92  * </ul>
93  * </li>
94  * <li><code>IThread</code>
95  * <ul>
96  * <li><code>CREATE</code> - a thread has been created in a debug target.</li>
97  * <li><code>TERMINATE</code> - a thread has terminated.</li>
98  * <li><code>SUSPEND</code> - a thread has suspended execution. Event detail provides
99  * the reason for the suspension:<ul>
100  * <li><code>STEP_END</code> - a request to step has completed</li>
101  * <li><code>BREAKPOINT</code> - a breakpoint has been hit</li>
102  * <li><code>CLIENT_REQUEST</code> - a client request has caused the thread to suspend
103  * (i.e. an explicit call to <code>suspend()</code>)</li>
104  * <li><code>EVALUATION</code> - an expression evaluation has ended that may
105  * have had side effects in the debug target.</li>
106  * <li><code>EVALUATION_IMPLICIT</code> - an expression evaluation has ended that
107  * had no side effects in the debug target.</li>
108  * <li><code>UNSPECIFIED</code> - the reason for the suspend is not specified</li>
109  * </ul>
110  * </li>
111  * <li><code>RESUME</code> - a thread has resumed execution. Event detail provides
112  * the reason for the resume:<ul>
113  * <li><code>STEP_INTO</code> - a thread is being resumed because of a request to step into</li>
114  * <li><code>STEP_OVER</code> - a thread is being resumed because of a request to step over</li>
115  * <li><code>STEP_RETURN</code> - a thread is being resumed because of a request to step return</li>
116  * <li><code>CLIENT_REQUEST</code> - a client request has caused the thread to be resumed
117  * (i.e. an explicit call to <code>resume()</code>)</li>
118  * <li><code>EVALUATION</code> - an expression evaluation has started that may
119  * have side effects in the debug target.</li>
120  * <li><code>EVALUATION_IMPLICIT</code> - an expression evaluation has started that
121  * will have no side effects in the debug target.</li>
122  * <li><code>UNSPECIFIED</code> - The reason for the resume is not specified</li>
123  * </ul>
124  * </li>
125  * </ul>
126  * </li>
127  * <li><code>IStackFrame</code> - no events are specified for stack frames.
128  * When a thread is suspended, it has stack frames. When a thread resumes,
129  * stack frames are unavailable.
130  * </li>
131  * <li><code>IVariable</code> - no events are specified for variables.
132  * When a thread is suspended, stack frames have variables. When a thread resumes,
133  * variables are unavailable.
134  * </li>
135  * <li><code>IValue</code> - no events are specified for values.
136  * </li>
137  * </ul>
138  * <p>
139  * Clients may instantiate this class. Clients are not intended to subclass this class.
140  * </p>
141  *
142  */
143 public final class DebugEvent extends EventObject JavaDoc {
144     
145     /**
146      * All objects that can be serialized should have a stable serialVersionUID
147      */
148     private static final long serialVersionUID = 1L;
149     
150     /**
151      * Resume event kind.
152      */
153     public static final int RESUME= 0x0001;
154
155     /**
156      * Suspend event kind.
157      */
158     public static final int SUSPEND= 0x0002;
159
160     /**
161      * Create event kind.
162      */
163     public static final int CREATE= 0x0004;
164
165     /**
166      * Terminate event kind.
167      */
168     public static final int TERMINATE= 0x0008;
169     
170     /**
171      * Change event kind.
172      */
173     public static final int CHANGE= 0x0010;
174     
175     /**
176      * Model specific event kind. The detail codes
177      * for a model specific event are client defined.
178      *
179      * @since 2.1.2
180      */
181     public static final int MODEL_SPECIFIC= 0x0020;
182
183     /**
184      * Step start detail. Indicates a thread was resumed by a step
185      * into action.
186      * @since 2.0
187      */
188     public static final int STEP_INTO= 0x0001;
189     
190     /**
191      * Step start detail. Indicates a thread was resumed by a step
192      * over action.
193      * @since 2.0
194      */
195     public static final int STEP_OVER= 0x0002;
196     
197     /**
198      * Step start detail. Indicates a thread was resumed by a step
199      * return action.
200      * @since 2.0
201      */
202     public static final int STEP_RETURN= 0x0004;
203
204     /**
205      * Step end detail. Indicates a thread was suspended due
206      * to the completion of a step action.
207      */
208     public static final int STEP_END= 0x0008;
209     
210     /**
211      * Breakpoint detail. Indicates a thread was suspended by
212      * a breakpoint.
213      */
214     public static final int BREAKPOINT= 0x0010;
215     
216     /**
217      * Client request detail. Indicates a thread was suspended due
218      * to a client request.
219      */
220     public static final int CLIENT_REQUEST= 0x0020;
221     
222     /**
223      * Evaluation detail. Indicates that a thread was resumed or
224      * suspended to perform an expression evaluation.
225      *
226      * @since 2.0
227      */
228     public static final int EVALUATION = 0x0040;
229     
230     /**
231      * Evaluation detail. Indicates that a thread was resumed or
232      * suspended to perform an implicit expression evaluation.
233      * An implicit evaluation is an evaluation that is performed
234      * as an indirect result of a user action.
235      * Clients may use this detail event to decide whether or not
236      * to alert the user that an evaluation is taking place..
237      *
238      * @since 2.0
239      */
240     public static final int EVALUATION_IMPLICIT = 0x0080;
241
242     /**
243      * State change detail. Indicates the state of a single
244      * debug element has changed. Only valid for <code>CHANGE</code>
245      * events.
246      *
247      * @since 2.0
248      */
249     public static final int STATE = 0x0100;
250     
251     /**
252      * Content change detail. Indicates the content of a debug element
253      * (and potentially its children) has changed. Only valid for
254      * <code>CHANGE</code> events.
255      *
256      * @since 2.0
257      */
258     public static final int CONTENT = 0x0200;
259             
260     /**
261      * Constant indicating that the kind or detail of a debug
262      * event is unspecified.
263      */
264     public static final int UNSPECIFIED = 0;
265     
266     /**
267      * The kind of event - one of the kind constants defined by
268      * this class.
269      */
270     private int fKind= UNSPECIFIED;
271
272     /**
273      * The detail of the event - one of the detail constants defined by
274      * this class.
275      */
276     private int fDetail= UNSPECIFIED;
277     
278     /**
279      * Client defined data field.
280      *
281      * @since 2.1.2
282      */
283     private Object JavaDoc fData = null;
284     
285     /**
286      * Constructs a new debug event of the given kind with a detail code of
287      * <code>UNSPECIFIED</code>.
288      *
289      * @param eventSource the object associated with the event
290      * @param kind the kind of debug event (one of the
291      * kind constants defined by this class)
292      */
293     public DebugEvent(Object JavaDoc eventSource, int kind) {
294         this(eventSource, kind, UNSPECIFIED);
295     }
296
297     /**
298      * Constructs a new debug event of the given kind with the given detail.
299      *
300      * @param eventSource the object associated with the event
301      * @param kind the kind of debug event (one of the
302      * kind constants defined by this class)
303      * @param detail extra information about the event (one of the
304      * detail constants defined by this class or a client defined detail if this is a model specific event)
305      */
306     public DebugEvent(Object JavaDoc eventSource, int kind, int detail) {
307         super(eventSource);
308         if ((kind & (RESUME | SUSPEND | CREATE | TERMINATE | CHANGE | MODEL_SPECIFIC)) == 0)
309             throw new IllegalArgumentException JavaDoc(DebugCoreMessages.DebugEvent_illegal_kind);
310         if (kind != MODEL_SPECIFIC && detail != UNSPECIFIED && (detail & (STEP_END | STEP_INTO | STEP_OVER | STEP_RETURN | BREAKPOINT | CLIENT_REQUEST |EVALUATION | EVALUATION_IMPLICIT | STATE | CONTENT)) == 0)
311             throw new IllegalArgumentException JavaDoc(DebugCoreMessages.DebugEvent_illegal_detail);
312         fKind= kind;
313         fDetail= detail;
314     }
315
316     /**
317      * Returns a constant describing extra detail about the event - either one
318      * of the detail constants defined by this class, possibly
319      * <code>UNSPECIFIED</code>, or a client defined detail if this is a model specific event.
320      *
321      * @return the detail code
322      */
323     public int getDetail() {
324         return fDetail;
325     }
326
327     /**
328      * Returns this event's kind - one of the kind constants defined by this class.
329      *
330      * @return the kind code
331      */
332     public int getKind() {
333         return fKind;
334     }
335     
336     /**
337      * Returns whether this event's detail indicates the
338      * beginning of a step event. This event's detail is one
339      * of <code>STEP_INTO</code>, <code>STEP_OVER</code>, or
340      * <code>STEP_RETURN</code>.
341      *
342      * @return whether this event's detail indicates the beginning
343      * of a step event.
344      * @since 2.0
345      */
346     public boolean isStepStart() {
347         return (getDetail() & (STEP_INTO | STEP_OVER | STEP_RETURN)) > 0;
348     }
349     
350     /**
351      * Returns whether this event's detail indicates an
352      * evaluation. This event's detail is one
353      * of <code>EVALUATION</code>, or <code>EVALUATION_IMPLICIT</code>.
354      *
355      * @return whether this event's detail indicates an evaluation.
356      * @since 2.0
357      */
358     public boolean isEvaluation() {
359         return (getDetail() & (EVALUATION | EVALUATION_IMPLICIT)) > 0;
360     }
361     
362     /**
363      * Sets this event's application defined data.
364      *
365      * @param data application defined data
366      * @since 2.1.2
367      */
368     public void setData(Object JavaDoc data) {
369         fData = data;
370     }
371     
372     /**
373      * Returns this event's application defined data, or <code>null</code> if none
374      *
375      * @return application defined data, or <code>null</code> if none
376      * @since 2.1.2
377      */
378     public Object JavaDoc getData() {
379         return fData;
380     }
381     
382     /**
383      * @see java.lang.Object#toString()
384      */
385     public String JavaDoc toString() {
386         StringBuffer JavaDoc buf = new StringBuffer JavaDoc("DebugEvent["); //$NON-NLS-1$
387 if (getSource() != null) {
388             buf.append(getSource().toString());
389         } else {
390             buf.append("null"); //$NON-NLS-1$
391 }
392         buf.append(", "); //$NON-NLS-1$
393 switch (getKind()) {
394             case CREATE:
395                 buf.append("CREATE"); //$NON-NLS-1$
396 break;
397             case TERMINATE:
398                 buf.append("TERMINATE"); //$NON-NLS-1$
399 break;
400             case RESUME:
401                 buf.append("RESUME"); //$NON-NLS-1$
402 break;
403             case SUSPEND:
404                 buf.append("SUSPEND"); //$NON-NLS-1$
405 break;
406             case CHANGE:
407                 buf.append("CHANGE"); //$NON-NLS-1$
408 break;
409             case UNSPECIFIED:
410                 buf.append("UNSPECIFIED"); //$NON-NLS-1$
411 break;
412             case MODEL_SPECIFIC:
413                 buf.append("MODEL_SPECIFIC"); //$NON-NLS-1$
414 break;
415         }
416         buf.append(", "); //$NON-NLS-1$
417 switch (getDetail()) {
418             case BREAKPOINT:
419                 buf.append("BREAKPOINT"); //$NON-NLS-1$
420 break;
421             case CLIENT_REQUEST:
422                 buf.append("CLIENT_REQUEST"); //$NON-NLS-1$
423 break;
424             case STEP_END:
425                 buf.append("STEP_END"); //$NON-NLS-1$
426 break;
427             case STEP_INTO:
428                 buf.append("STEP_INTO"); //$NON-NLS-1$
429 break;
430             case STEP_OVER:
431                 buf.append("STEP_OVER"); //$NON-NLS-1$
432 break;
433             case STEP_RETURN:
434                 buf.append("STEP_RETURN"); //$NON-NLS-1$
435 break;
436             case EVALUATION:
437                 buf.append("EVALUATION"); //$NON-NLS-1$
438 break;
439             case EVALUATION_IMPLICIT:
440                 buf.append("EVALUATION_IMPLICIT"); //$NON-NLS-1$
441 break;
442             case STATE:
443                 buf.append("STATE"); //$NON-NLS-1$
444 break;
445             case CONTENT:
446                 buf.append("CONTENT"); //$NON-NLS-1$
447 break;
448             case UNSPECIFIED:
449                 buf.append("UNSPECIFIED"); //$NON-NLS-1$
450 break;
451             default:
452                 // model specific
453 buf.append(getDetail());
454                 break;
455         }
456         buf.append("]"); //$NON-NLS-1$
457 return buf.toString();
458     }
459 }
460
461
Popular Tags