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  ;
31  import java.io.File  ;
32  import java.io.IOException  ;
33  import java.util.Iterator  ;
34  import java.util.List  ;
35  import java.util.Map  ;
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            PROP_STATE = "state";
61      /** Name of property for current thread. */
62      public static final String            PROP_CURRENT_THREAD = "currentThread";
63      /** Name of property for current stack frame. */
64      public static final String            PROP_CURRENT_CALL_STACK_FRAME = "currentCallStackFrame";
65      /** Property name constant. */
66      public static final String            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            ENGINE_ID = "netbeans-JPDASession/Java";
84      /** ID of JPDA Debugger Engine. */
85      public static final String            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            mainClassName,
101         String  []        args,
102         String            classPath,
103         boolean         suspend
104     ) {
105         DebuggerEngine[] es = DebuggerManager.getDebuggerManager().startDebugging (
106             DebuggerInfo.create (
107                 LaunchingDICookie.ID,
108                 new Object  [] {
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  (
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  <String  , ? extends Argument>  args,
139         Object  []                  services
140     ) throws DebuggerStartException {
141         Object  [] s = new Object   [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  <String  , ? extends Argument>  args,
178         Object  []                  services
179     ) throws DebuggerStartException {
180         Object  [] s = new Object   [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            hostName,
209         int             portNumber,
210         Object  []        services
211     ) throws DebuggerStartException {
212         Object  [] s = new Object   [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            name,
246         Object  []        services
247     ) throws DebuggerStartException {
248         Object  [] s = new Object   [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   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  <String  , 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   l);
392 
393     /**
394      * Removes property change listener.
395      *
396      * @param l removed listener.
397      */
398     public abstract void removePropertyChangeListener (
399         PropertyChangeListener   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   propertyName, 
410         PropertyChangeListener   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   propertyName, 
421         PropertyChangeListener   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  ("This method must be overridden."); 
433     } 
434 }
435
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags