javax.ide.debug
Class Connector

java.lang.Object
  javax.ide.debug.Connector

Direct Known Subclasses:

ClientConnector, ServerConnector

public abstract class Connector
extends java.lang.Object

The Connector interface is used to connect to a debugging session. The Connector object is used to start the debuggee or to retrieve command line options so the extension can start the debuggee itself.

IDE providers must provide an implementation of this interface. Extension writers can access the Connector through the Debugger.getClientConnector(Context) and Debugger.getServerConnector(Context) methods.

Field Summary

static java.lang.String	OPTION_CLASSPATH The key of an option in the options map for arguments required to set the classpath of Java.
static java.lang.String	OPTION_DEBUG_FIRST The key of an option in the options map for zero or more arguments which must be passed into java immediately following the switch specifying the VM.
static java.lang.String	OPTION_DEBUG_LAST The key of an option in the options map for options that are passed into Java immediately before the main class.
static java.lang.String	OPTION_JAVA_EXECUTABLE The key of the option in the options map for the absolute path of the Java executable to run.
static java.lang.String	OPTION_JAVA_OPTIONS The key of an option in the options map for options that should be passed into the java exectuable.
static java.lang.String	OPTION_JVM The key of the option in the options map for an argument passed to Java to set the VM.
static java.lang.String	OPTION_MAIN_CLASS The key of an option in the options map for the main class to run.
static java.lang.String	OPTION_PROGRAM_ARGUMENTS The key of an option in the options map for arguments passed into the java process.

Constructor Summary

Connector()

Method Summary

abstract Context	getContext() Get the Context used to create this connector.
abstract java.util.Map	getOptions() Get the options the extension should use when starting the debuggee.
abstract boolean	isConnected() Check if the debugger has connected to the debuggee.
abstract boolean	isFinished() Check if the debugger has finished debugging.
abstract java.lang.Process	startDebuggee(java.util.Map options) Start the debuggee process.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

OPTION_JAVA_EXECUTABLE

public static final java.lang.String OPTION_JAVA_EXECUTABLE

The key of the option in the options map for the absolute path of the Java executable to run.

See Also:

Constant Field Values

OPTION_JVM

public static final java.lang.String OPTION_JVM

The key of the option in the options map for an argument passed to Java to set the VM. This is normally the first option passed to Java, e.g. for the client VM, this would be String[0] or { "-client' }.

See Also:

Constant Field Values

OPTION_DEBUG_FIRST

public static final java.lang.String OPTION_DEBUG_FIRST

The key of an option in the options map for zero or more arguments which must be passed into java immediately following the switch specifying the VM. These options are specific to the debugger.

See Also:

Constant Field Values

OPTION_CLASSPATH

public static final java.lang.String OPTION_CLASSPATH

The key of an option in the options map for arguments required to set the classpath of Java. For example, a typical value might be { "-classpath", "somejar.jar" }

See Also:

Constant Field Values

OPTION_JAVA_OPTIONS

public static final java.lang.String OPTION_JAVA_OPTIONS

The key of an option in the options map for options that should be passed into the java exectuable.

See Also:

Constant Field Values

OPTION_DEBUG_LAST

public static final java.lang.String OPTION_DEBUG_LAST

The key of an option in the options map for options that are passed into Java immediately before the main class. These options are specific to the debugger.

See Also:

Constant Field Values

OPTION_MAIN_CLASS

public static final java.lang.String OPTION_MAIN_CLASS

The key of an option in the options map for the main class to run.

See Also:

Constant Field Values

OPTION_PROGRAM_ARGUMENTS

public static final java.lang.String OPTION_PROGRAM_ARGUMENTS

The key of an option in the options map for arguments passed into the java process.

See Also:

Constant Field Values

Constructor Detail

Connector

public Connector()

Method Detail

getOptions

public abstract java.util.Map getOptions()

Get the options the extension should use when starting the debuggee. The extension will mostly call this method when it wants to start the debuggee process itself. If the extension wants the IDE to start the debuggee process, this method does not need to be called, unless the extension wants to modify some of the command line options. Returns a Map where the keys are the following String constants OPTION_JAVA_EXECUTABLE, OPTION_JVM, OPTION_DEBUG_FIRST, OPTION_CLASSPATH, OPTION_JAVA_OPTIONS, OPTION_DEBUG_LAST, OPTION_MAIN_CLASS, OPTION_PROGRAM_ARGUMENTS, and the values are String[]. Each String[] value can be null or of zero length, if no options are necessary, or an array of one or more Strings.

Returns:

a Map of command line options.

startDebuggee

public abstract java.lang.Process startDebuggee(java.util.Map options)
                                         throws java.io.IOException

Start the debuggee process. The extension should call this method when it wants the IDE to start the debuggee process. The options can be a full set of command line options as returned getOptions(), or it can be a partial set of options. If the options map contains a key/value pair, the value specified will override the value that the IDE would ordinarily use for that key. If the extension does not want to override any options, the options parameter can be null. For example, if a extension wants to add an additional program argument, it should call getOptions() and get the value for OPTION_PROGRAM_ARGUMENTS out of the Map. It should then create a new String[] to hold the original program arguments plus the additional program argument. It should then put this new String[] into the Map before passing it to startDebuggee.

Parameters:

options - a Map of command line options

Returns:

the debuggee process

Throws:

java.io.IOException - if the process can not be started.

isConnected

public abstract boolean isConnected()

Check if the debugger has connected to the debuggee.

Returns:

true if connected.

isFinished

public abstract boolean isFinished()

Check if the debugger has finished debugging.

Returns:

true if finished.

getContext

public abstract Context getContext()

Get the Context used to create this connector.

Returns:

the context.