01: /*******************************************************************************
02: * Copyright (c) 2000, 2006 IBM Corporation and others.
03: * All rights reserved. This program and the accompanying materials
04: * are made available under the terms of the Eclipse Public License v1.0
05: * which accompanies this distribution, and is available at
06: * http://www.eclipse.org/legal/epl-v10.html
07: *
08: * Contributors:
09: * IBM Corporation - initial API and implementation
10: *******************************************************************************/package org.eclipse.jdt.launching;
11:
12: import java.util.List;
13: import java.util.Map;
14:
15: import org.eclipse.core.runtime.CoreException;
16: import org.eclipse.core.runtime.IProgressMonitor;
17: import org.eclipse.debug.core.ILaunch;
18:
19: /**
20: * A VM connector establishes a JDI connection with a debuggable
21: * virtual machine. This extension point provides a mechanism for
22: * abstracting the connection to a remote virtual machine.
23: * <p>
24: * A VM connector extension is defined in <code>plugin.xml</code>.
25: * Following is an example definition of a VM connector extension.
26: * <pre>
27: * <extension point="org.eclipse.jdt.launching.vmConnectors">
28: * <vmConnector
29: * id="com.example.VMConnector"
30: * class="com.example.VMConnectorClass"
31: * </vmConnector>
32: * </extension>
33: * </pre>
34: * The attributes are specified as follows:
35: * <ul>
36: * <li><code>id</code> specifies a unique identifier for this VM connector.</li>
37: * <li><code>class</code> specifies the fully qualified name of the Java class
38: * that implements <code>IVMConnector</code>.</li>
39: * </ul>
40: * </p>
41: * @since 2.0
42: */
43:
44: public interface IVMConnector {
45:
46: /**
47: * Establishes a JDI connection with a debuggable VM using the arguments
48: * specified in the given map, contributing results (debug targets and processes),
49: * to the given launch.
50: *
51: * @param arguments Argument map to use in establishing a connection. The keys of
52: * the map are strings corresponding to the names of arguments returned by this
53: * connector's <code>getDefaultAgruments()</code> method. The values of the map
54: * are strings corresponding to the (String) values of the associated
55: * <code>com.sun.jdi.connect.Connector.Argument</code>s to use.
56: * @param monitor progress monitor
57: * @param launch launch to contribute debug target(s) and/or process(es) to
58: * @exception CoreException if unable to establish a connection with the target VM
59: */
60: public void connect(Map arguments, IProgressMonitor monitor,
61: ILaunch launch) throws CoreException;
62:
63: /**
64: * Returns the name of this connector.
65: *
66: * @return the name of this connector
67: */
68: public String getName();
69:
70: /**
71: * Returns a unique identifier for this kind of connector.
72: *
73: * @return a unique identifier for this kind of connector
74: */
75: public String getIdentifier();
76:
77: /**
78: * Returns a map of default arguments used by this connector.
79: * The keys of the map are names of arguments used by this
80: * connector, and the values are of type
81: * <code>com.sun.jdi.connect.Connector.Argument</code>.
82: *
83: * @return argument map with default values
84: * @exception CoreException if unable to retrieve a default argument map
85: */
86: public Map getDefaultArguments() throws CoreException;
87:
88: /**
89: * Returns a list of argument names found in this connector's
90: * default argument map, defining the order in which arguments
91: * should be presented to the user. Since a map is not ordered,
92: * this provides control on how arguments will be presented to
93: * the user.
94: *
95: * @return list of argument names
96: */
97: public List getArgumentOrder();
98: }
|