KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > netbeans > api > debugger > jpda > JPDADebugger


1 /*
2  * The contents of this file are subject to the terms of the Common Development
3  * and Distribution License (the License). You may not use this file except in
4  * compliance with the License.
5  *
6  * You can obtain a copy of the License at http://www.netbeans.org/cddl.html
7  * or http://www.netbeans.org/cddl.txt.
8  *
9  * When distributing Covered Code, include this CDDL Header Notice in each file
10  * and include the License file at http://www.netbeans.org/cddl.txt.
11  * If applicable, add the following below the CDDL Header, with the fields
12  * enclosed by brackets [] replaced by your own identifying information:
13  * "Portions Copyrighted [year] [name of copyright owner]"
14  *
15  * The Original Software is NetBeans. The Initial Developer of the Original
16  * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
17  * Microsystems, Inc. All Rights Reserved.
18  */

19
20 package org.netbeans.api.debugger.jpda;
21
22 import com.sun.jdi.Bootstrap;
23 import com.sun.jdi.VirtualMachine;
24 import com.sun.jdi.connect.AttachingConnector;
25 import com.sun.jdi.connect.Connector.Argument;
26 import com.sun.jdi.connect.IllegalConnectorArgumentsException;
27 import com.sun.jdi.connect.ListeningConnector;
28 import com.sun.jdi.request.EventRequest;
29
30 import java.beans.PropertyChangeListener JavaDoc;
31 import java.io.File JavaDoc;
32 import java.io.IOException JavaDoc;
33 import java.util.Iterator JavaDoc;
34 import java.util.List JavaDoc;
35 import java.util.Map JavaDoc;
36 import org.netbeans.api.debugger.DebuggerEngine;
37 import org.netbeans.api.debugger.DebuggerInfo;
38 import org.netbeans.api.debugger.DebuggerManager;
39 import org.netbeans.api.debugger.jpda.InvalidExpressionException;
40 import org.netbeans.api.debugger.jpda.Variable;
41 import org.netbeans.api.debugger.jpda.event.JPDABreakpointEvent;
42 import org.openide.util.NbBundle;
43
44
45 /**
46  * Represents one JPDA debugger session (one
47  * {@link com.sun.jdi.VirtualMachine}).
48  *
49  * <br><br>
50  * <b>How to obtain it from DebuggerEngine:</b>
51  * <pre style="background-color: rgb(255, 255, 153);">
52  * JPDADebugger jpdaDebugger = (JPDADebugger) debuggerEngine.lookup
53  * (JPDADebugger.class);</pre>
54  *
55  * @author Jan Jancura
56  */

57 public abstract class JPDADebugger {
58
59     /** Name of property for state of debugger. */
60     public static final String JavaDoc PROP_STATE = "state";
61     /** Name of property for current thread. */
62     public static final String JavaDoc PROP_CURRENT_THREAD = "currentThread";
63     /** Name of property for current stack frame. */
64     public static final String JavaDoc PROP_CURRENT_CALL_STACK_FRAME = "currentCallStackFrame";
65     /** Property name constant. */
66     public static final String JavaDoc PROP_SUSPEND = "suspend"; // NOI18N
67

68     /** Suspend property value constant. */
69     public static final int SUSPEND_ALL = EventRequest.SUSPEND_ALL;
70     /** Suspend property value constant. */
71     public static final int SUSPEND_EVENT_THREAD = EventRequest.SUSPEND_EVENT_THREAD;
72     
73     /** Debugger state constant. */
74     public static final int STATE_STARTING = 1;
75     /** Debugger state constant. */
76     public static final int STATE_RUNNING = 2;
77     /** Debugger state constant. */
78     public static final int STATE_STOPPED = 3;
79     /** Debugger state constant. */
80     public static final int STATE_DISCONNECTED = 4;
81
82     /** ID of JPDA Debugger Engine. */
83     public static final String JavaDoc ENGINE_ID = "netbeans-JPDASession/Java";
84     /** ID of JPDA Debugger Engine. */
85     public static final String JavaDoc SESSION_ID = "netbeans-JPDASession";
86     
87
88     
89     /**
90      * This utility method helps to start a new JPDA debugger session.
91      * Its implementation use {@link LaunchingDICookie} and
92      * {@link org.netbeans.api.debugger.DebuggerManager#getDebuggerManager}.
93      *
94      * @param mainClassName a name or main class
95      * @param args command line arguments
96      * @param classPath a classPath
97      * @param suspend if true session will be suspended
98      */

99     public static void launch (
100         String JavaDoc mainClassName,
101         String JavaDoc[] args,
102         String JavaDoc classPath,
103         boolean suspend
104     ) {
105         DebuggerEngine[] es = DebuggerManager.getDebuggerManager().startDebugging (
106             DebuggerInfo.create (
107                 LaunchingDICookie.ID,
108                 new Object JavaDoc[] {
109                     LaunchingDICookie.create (
110                         mainClassName,
111                         args,
112                         classPath,
113                         suspend
114                     )
115                 }
116             )
117         );
118         if (es.length == 0) {
119             /* Can not throw DebuggerStartException, but it should...
120             throw new DebuggerStartException(
121                     NbBundle.getMessage(JPDADebugger.class, "MSG_NO_DEBUGGER")); */

122             throw new RuntimeException JavaDoc(
123                     NbBundle.getMessage(JPDADebugger.class, "MSG_NO_DEBUGGER"));
124         }
125     }
126     
127     /**
128      * This utility method helps to start a new JPDA debugger session.
129      * Its implementation use {@link ListeningDICookie} and
130      * {@link org.netbeans.api.debugger.DebuggerManager#getDebuggerManager}.
131      *
132      * @param connector The listening connector
133      * @param args The arguments
134      * @param services The additional services
135      */

136     public static JPDADebugger listen (
137         ListeningConnector connector,
138         Map JavaDoc<String JavaDoc, ? extends Argument> args,
139         Object JavaDoc[] services
140     ) throws DebuggerStartException {
141         Object JavaDoc[] s = new Object JavaDoc [services.length + 1];
142         System.arraycopy (services, 0, s, 1, services.length);
143         s [0] = ListeningDICookie.create (
144             connector,
145             args
146         );
147         DebuggerEngine[] es = DebuggerManager.getDebuggerManager ().
148             startDebugging (
149                 DebuggerInfo.create (
150                     ListeningDICookie.ID,
151                     s
152                 )
153             );
154         int i, k = es.length;
155         for (i = 0; i < k; i++) {
156             JPDADebugger d = (JPDADebugger) es [i].lookupFirst
157                 (null, JPDADebugger.class);
158             if (d == null) continue;
159             d.waitRunning ();
160             return d;
161         }
162         throw new DebuggerStartException(
163                 NbBundle.getMessage(JPDADebugger.class, "MSG_NO_DEBUGGER"));
164     }
165     
166     /**
167      * This utility method helps to start a new JPDA debugger session.
168      * Its implementation use {@link ListeningDICookie} and
169      * {@link org.netbeans.api.debugger.DebuggerManager#getDebuggerManager}.
170      *
171      * @param connector The listening connector
172      * @param args The arguments
173      * @param services The additional services
174      */

175     public static void startListening (
176         ListeningConnector connector,
177         Map JavaDoc<String JavaDoc, ? extends Argument> args,
178         Object JavaDoc[] services
179     ) throws DebuggerStartException {
180         Object JavaDoc[] s = new Object JavaDoc [services.length + 1];
181         System.arraycopy (services, 0, s, 1, services.length);
182         s [0] = ListeningDICookie.create (
183             connector,
184             args
185         );
186         DebuggerEngine[] es = DebuggerManager.getDebuggerManager ().
187             startDebugging (
188                 DebuggerInfo.create (
189                     ListeningDICookie.ID,
190                     s
191                 )
192             );
193         if (es.length == 0) {
194             throw new DebuggerStartException(
195                     NbBundle.getMessage(JPDADebugger.class, "MSG_NO_DEBUGGER"));
196         }
197     }
198     
199     /**
200      * This utility method helps to start a new JPDA debugger session.
201      * Its implementation use {@link AttachingDICookie} and
202      * {@link org.netbeans.api.debugger.DebuggerManager#getDebuggerManager}.
203      *
204      * @param hostName a name of computer to attach to
205      * @param portNumber a port number
206      */

207     public static JPDADebugger attach (
208         String JavaDoc hostName,
209         int portNumber,
210         Object JavaDoc[] services
211     ) throws DebuggerStartException {
212         Object JavaDoc[] s = new Object JavaDoc [services.length + 1];
213         System.arraycopy (services, 0, s, 1, services.length);
214         s [0] = AttachingDICookie.create (
215             hostName,
216             portNumber
217         );
218         DebuggerEngine[] es = DebuggerManager.getDebuggerManager ().
219             startDebugging (
220                 DebuggerInfo.create (
221                     AttachingDICookie.ID,
222                     s
223                 )
224             );
225         int i, k = es.length;
226         for (i = 0; i < k; i++) {
227             JPDADebugger d = (JPDADebugger) es [i].lookupFirst
228                 (null, JPDADebugger.class);
229             if (d == null) continue;
230             d.waitRunning ();
231             return d;
232         }
233         throw new DebuggerStartException(
234                 NbBundle.getMessage(JPDADebugger.class, "MSG_NO_DEBUGGER"));
235     }
236     
237     /**
238      * This utility method helps to start a new JPDA debugger session.
239      * Its implementation use {@link AttachingDICookie} and
240      * {@link org.netbeans.api.debugger.DebuggerManager#getDebuggerManager}.
241      *
242      * @param name a name of shared memory block
243      */

244     public static JPDADebugger attach (
245         String JavaDoc name,
246         Object JavaDoc[] services
247     ) throws DebuggerStartException {
248         Object JavaDoc[] s = new Object JavaDoc [services.length + 1];
249         System.arraycopy (services, 0, s, 1, services.length);
250         s [0] = AttachingDICookie.create (
251             name
252         );
253         DebuggerEngine[] es = DebuggerManager.getDebuggerManager ().
254             startDebugging (
255                 DebuggerInfo.create (
256                     AttachingDICookie.ID,
257                     s
258                 )
259             );
260         int i, k = es.length;
261         for (i = 0; i < k; i++) {
262             JPDADebugger d = (JPDADebugger) es [i].lookupFirst
263                 (null, JPDADebugger.class);
264             d.waitRunning ();
265             if (d == null) continue;
266             return d;
267         }
268         throw new DebuggerStartException(
269                 NbBundle.getMessage(JPDADebugger.class, "MSG_NO_DEBUGGER"));
270     }
271
272     /**
273      * Returns current state of JPDA debugger.
274      *
275      * @return current state of JPDA debugger
276      * @see #STATE_STARTING
277      * @see #STATE_RUNNING
278      * @see #STATE_STOPPED
279      * @see #STATE_DISCONNECTED
280      */

281     public abstract int getState ();
282     
283     /**
284      * Gets value of suspend property.
285      *
286      * @return value of suspend property
287      */

288     public abstract int getSuspend ();
289
290     /**
291      * Sets value of suspend property.
292      *
293      * @param s a new value of suspend property
294      */

295     public abstract void setSuspend (int s);
296     
297     /**
298      * Returns current thread or null.
299      *
300      * @return current thread or null
301      */

302     public abstract JPDAThread getCurrentThread ();
303     
304     /**
305      * Returns current stack frame or null.
306      *
307      * @return current stack frame or null
308      */

309     public abstract CallStackFrame getCurrentCallStackFrame ();
310     
311     /**
312      * Evaluates given expression in the current context.
313      *
314      * @param expression a expression to be evaluated
315      *
316      * @return current value of given expression
317      */

318     public abstract Variable evaluate (String JavaDoc expression)
319     throws InvalidExpressionException;
320
321     /**
322      * Waits till the Virtual Machine is started and returns
323      * {@link DebuggerStartException} if some problem occurres.
324      *
325      * @throws DebuggerStartException is some problems occurres during debugger
326      * start
327      *
328      * @see AbstractDICookie#getVirtualMachine()
329      */

330     public abstract void waitRunning () throws DebuggerStartException;
331
332     /**
333      * Returns <code>true</code> if this debugger supports fix & continue
334      * (HotSwap).
335      *
336      * @return <code>true</code> if this debugger supports fix & continue
337      */

338     public abstract boolean canFixClasses ();
339
340     /**
341      * Returns <code>true</code> if this debugger supports Pop action.
342      *
343      * @return <code>true</code> if this debugger supports Pop action
344      */

345     public abstract boolean canPopFrames ();
346     
347     /**
348      * Determines if the target debuggee can be modified.
349      *
350      * @return <code>true</code> if the target debuggee can be modified or when
351      * this information is not available (on JDK 1.4).
352      * @since 2.3
353      */

354     public boolean canBeModified() {
355         return true;
356     }
357
358     /**
359      * Implements fix & continue (HotSwap). Map should contain class names
360      * as a keys, and byte[] arrays as a values.
361      *
362      * @param classes a map from class names to be fixed to byte[]
363      */

364     public abstract void fixClasses (Map JavaDoc<String JavaDoc, byte[]> classes);
365     
366     /**
367      * Returns instance of SmartSteppingFilter.
368      *
369      * @return instance of SmartSteppingFilter
370      */

371     public abstract SmartSteppingFilter getSmartSteppingFilter ();
372
373     /**
374      * Helper method that fires JPDABreakpointEvent on JPDABreakpoints.
375      *
376      * @param breakpoint a breakpoint to be changed
377      * @param event a event to be fired
378      */

379     protected void fireBreakpointEvent (
380         JPDABreakpoint breakpoint,
381         JPDABreakpointEvent event
382     ) {
383         breakpoint.fireJPDABreakpointChange (event);
384     }
385     
386     /**
387      * Adds property change listener.
388      *
389      * @param l new listener.
390      */

391     public abstract void addPropertyChangeListener (PropertyChangeListener JavaDoc l);
392
393     /**
394      * Removes property change listener.
395      *
396      * @param l removed listener.
397      */

398     public abstract void removePropertyChangeListener (
399         PropertyChangeListener JavaDoc l
400     );
401
402     /**
403      * Adds property change listener.
404      *
405      * @param propertyName a name of property to listen on
406      * @param l new listener.
407      */

408     public abstract void addPropertyChangeListener (
409         String JavaDoc propertyName,
410         PropertyChangeListener JavaDoc l
411     );
412     
413     /**
414      * Removes property change listener.
415      *
416      * @param propertyName a name of property to listen on
417      * @param l removed listener.
418      */

419     public abstract void removePropertyChangeListener (
420         String JavaDoc propertyName,
421         PropertyChangeListener JavaDoc l
422     );
423     
424     /**
425      * Creates a new {@link JPDAStep}.
426      * Parameters correspond to {@link JPDAStep} constructor.
427      *
428      * @return {@link JPDAStep}
429      * @throws {@link java.lang.UnsupportedOperationException} If not overridden
430      */

431     public JPDAStep createJPDAStep(int size, int depth) {
432         throw new UnsupportedOperationException JavaDoc("This method must be overridden.");
433     }
434 }
435
Popular Tags