Source code: javax/ide/debug/Connector.java
1 package javax.ide.debug;
2
3 import java.io.IOException;
4 import java.util.Map;
5
6 import javax.ide.command.Context;
7 /**
8 * The <code>Connector</code> interface is used to connect to a debugging
9 * session. The <code>Connector</code> object is used to start the debuggee
10 * or to retrieve command line options so the extension can start the debuggee
11 * itself.<p>
12 *
13 * IDE providers must provide an implementation of this interface. Extension
14 * writers can access the <code>Connector</code> through the
15 * {@link Debugger#getClientConnector} and {@link Debugger#getServerConnector}
16 * methods.
17 */
18
19 public abstract class Connector
20 {
21 public static final String OPTION_JAVA_EXECUTABLE = "java-executable";
22 public static final String OPTION_JVM = "jvm";
23 public static final String OPTION_DEBUG_FIRST = "debug-first";
24 public static final String OPTION_CLASSPATH = "classpath";
25 public static final String OPTION_JAVA_OPTIONS = "java-options";
26 public static final String OPTION_DEBUG_LAST = "debug-last";
27 public static final String OPTION_MAIN_CLASS = "main-class";
28 public static final String OPTION_PROGRAM_ARGUMENTS = "program-arguments";
29
30 /**
31 * Get the options the extension should use when starting the
32 * debuggee.
33 *
34 * The extension will mostly call this method when it wants to
35 * start the debuggee process itself.
36 *
37 * If the extension wants the IDE to start the debuggee process,
38 * this method does not need to be called, unless the extension
39 * wants to modify some of the command line options.
40 *
41 * Returns a Map where the keys are the following String
42 * constants
43 * {@link #OPTION_JAVA_EXECUTABLE},
44 * {@link #OPTION_JVM},
45 * {@link #OPTION_DEBUG_FIRST},
46 * {@link #OPTION_CLASSPATH},
47 * {@link #OPTION_JAVA_OPTIONS},
48 * {@link #OPTION_DEBUG_LAST},
49 * {@link #OPTION_MAIN_CLASS},
50 * {@link #OPTION_PROGRAM_ARGUMENTS},
51 * and the values are String[].
52 * Each String[] value can be null, if no options are
53 * necessary, or an array of one or more Strings.
54 *
55 * @return a Map of command line options.
56 */
57 public abstract Map getOptions();
58
59 /**
60 * Start the debuggee process.
61 * The extension should call this method when it wants the IDE to
62 * start the debuggee process.
63 *
64 * The <code>options</code> can be a full set of command line
65 * options as returned {@link #getOptions}, or it can be a
66 * partial set of options. If the <code>options</code> map
67 * contains a key/value pair, the value specified will override
68 * the value that the IDE would ordinarily use for that key.
69 * If the extension does not want to override any options, the
70 * <code>options</code> parameter can be null.
71 *
72 * For example, if a extension wants to add an additional program
73 * argument, it should call {@link #getOptions} and get the
74 * value for {@link #OPTION_PROGRAM_ARGUMENTS} out of the Map.
75 * It should then create a new String[] to hold the original
76 * program arguments plus the additional program argument. It
77 * should then put this new String[] into the Map before
78 * passing it to <code>startDebuggee</code>.
79 *
80 * @param options a Map of command line options
81 * @return the debuggee process
82 * @exception IOException if the process can not be started.
83 */
84 public abstract Process startDebuggee( Map options ) throws IOException;
85
86 /**
87 * Check if the debugger has connected to the debuggee.
88 * @return true if connected.
89 */
90 public abstract boolean isConnected();
91
92 /**
93 * Check if the debugger has finished debugging.
94 * @return true if finished.
95 */
96 public abstract boolean isFinished();
97
98 /**
99 * Get the {@link Context} used to create this connector.
100 * @return the context.
101 */
102 public abstract Context getContext();
103 }
104