Source code: javax/ide/debug/Debugger.java
1 package javax.ide.debug;
2
3 import javax.ide.Service;
4 import javax.ide.spi.ProviderNotFoundException;
5 import javax.ide.command.Context;
6
7 /**
8 * The <code>Debugger</code> can be used to start the debuggee or to
9 * retrieve command line options so the extension can start the debuggee
10 * itself.<p>
11 *
12 * IDE providers must provide an implementation of {@link #getClientConnector( Context )}
13 * and {@link #getServerConnector(Context)}.
14 */
15 public abstract class Debugger extends Service
16 {
17
18
19 /**
20 * Creates a server connector for a debugging session. The
21 * {@link ServerConnector} object returned can be used to start the
22 * debuggee or to retrieve command line options so the extension can start
23 * the debuggee itself.
24 *
25 * If the extension wants to start the the debuggee itself, it should
26 * call {@link Connector#getOptions} to retrieve the command line
27 * options that it should use to start the debuggee.
28 * If the extension wants to start a third party container (such as
29 * Tomcat, WebLogic, Avalon based systems, properietary based
30 * systems, etc.), it can ignore options that are specific to the
31 * IDE's preferred container (for example, the extension may ignore the
32 * values corresponding to the {@link Connector#OPTION_MAIN_CLASS}
33 * key). The extension should not ignore the values corresponding to
34 * the {@link Connector#OPTION_DEBUG_FIRST} and
35 * {@link Connector#OPTION_DEBUG_LAST} keys, as these are dictated
36 * by the IDE so that the debugger will be able connect with the
37 * debuggee.
38 *
39 * If the extension wants the IDE to start the debuggee, it should call
40 * {@link Connector#startDebuggee}.
41 *
42 * The returned Connector will implement {@link ServerConnector}. The
43 * extension writer should call {@link ServerConnector#startListening} to
44 * start the debugger listening, and then the extension should either start
45 * the debuggee process or tell the IDE to do so by calling {@link
46 * Connector#startDebuggee}. When the debuggee process is launched,
47 * the listening debugger will automatically accept the connection.
48 *
49 * @param context the current {@link Context}.
50 * @return the debugger connector
51 * @exception UnsupportedOperationException if the IDE does not
52 * support the debugger as server.
53 */
54 public abstract ServerConnector getServerConnector( Context context )
55 throws UnsupportedOperationException;
56
57 /**
58 * Creates a client connector for a debugging session. The
59 * {@link ClientConnector} object returned can be used to start the
60 * debuggee or to retrieve command line options so the extension can start
61 * the debuggee itself.
62 *
63 * If the extension wants to start the the debuggee itself, it should
64 * call {@link Connector#getOptions} to retrieve the command line
65 * options that it should use to start the debuggee.
66 * If the extension wants to start a third party container (such as
67 * Tomcat, WebLogic, Avalon based systems, properietary based
68 * systems, etc.), it can ignore options that are specific to the
69 * IDE's preferred container (for example, the extension may ignore the
70 * values corresponding to the {@link Connector#OPTION_MAIN_CLASS}
71 * key). The extension should not ignore the values corresponding to
72 * the {@link Connector#OPTION_DEBUG_FIRST} and
73 * {@link Connector#OPTION_DEBUG_LAST} keys, as these are dictated
74 * by the IDE so that the debugger will be able connect with the
75 * debuggee.
76 *
77 * If the extension wants the IDE to start the debuggee, it should call
78 * {@link Connector#startDebuggee}.
79 *
80 * The returned Connector will implement {@link ClientConnector}. The
81 * extension writer should either start the debuggee process or tell the
82 * IDE to do so by calling {@link Connector#startDebuggee}, and then the
83 * extension writer should call {@link ClientConnector#attachDebugger} to
84 * tell the debugger to attach to the debuggee.
85 *
86 * @param context the current {@link Context}.
87
88 * @return the debugger connector
89 * @exception UnsupportedOperationException if the IDE does not
90 * support debugger as client.
91 */
92 public abstract ClientConnector getClientConnector( Context context )
93 throws UnsupportedOperationException;
94
95
96 /**
97 * Get the debugger implementation for this IDE.
98 *
99 * @return the debugger implementation.
100 */
101 public static Debugger getDebugger()
102 {
103 try
104 {
105 return (Debugger)getService( Debugger.class );
106 }
107 catch ( ProviderNotFoundException nse )
108 {
109 nse.printStackTrace();
110 throw new IllegalStateException( "No debugger." );
111 }
112 }
113 }
114