IVMConnector


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