View Javadoc
1   /*
2    * Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
10   *
11   * This code is distributed in the hope that it will be useful, but WITHOUT
12   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14   * version 2 for more details (a copy is included in the LICENSE file that
15   * accompanied this code).
16   *
17   * You should have received a copy of the GNU General Public License version
18   * 2 along with this work; if not, write to the Free Software Foundation,
19   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20   *
21   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  
26  package com.sun.jdi.connect;
27  
28  import java.util.Map;
29  import java.util.List;
30  import java.io.Serializable;
31  
32  /**
33   * A method of connection between a debugger and a target VM.
34   * A connector encapsulates exactly one {@link Transport}. used
35   * to establish the connection. Each connector has a set of arguments
36   * which controls its operation. The arguments are stored as a
37   * map, keyed by a string. Each implementation defines the string
38   * argument keys it accepts.
39   *
40   * @see LaunchingConnector
41   * @see AttachingConnector
42   * @see ListeningConnector
43   * @see Connector.Argument
44   *
45   * @author Gordon Hirsch
46   * @since  1.3
47   */
48  @jdk.Exported
49  public interface Connector {
50      /**
51       * Returns a short identifier for the connector. Connector implementors
52       * should follow similar naming conventions as are used with packages
53       * to avoid name collisions. For example, the Sun connector
54       * implementations have names prefixed with "com.sun.jdi.".
55       * Not intended for exposure to end-user.
56       *
57       * @return the name of this connector.
58       */
59      String name();
60  
61      /**
62       * Returns a human-readable description of this connector
63       * and its purpose.
64       *
65       * @return the description of this connector
66       */
67      String description();
68  
69      /**
70       * Returns the transport mechanism used by this connector to establish
71       * connections with a target VM.
72       *
73       * @return the {@link Transport} used by this connector.
74       */
75      Transport transport();
76  
77      /**
78       * Returns the arguments accepted by this Connector and their
79       * default values. The keys of the returned map are string argument
80       * names. The values are {@link Connector.Argument} containing
81       * information about the argument and its default value.
82       *
83       * @return the map associating argument names with argument
84       * information and default value.
85       */
86      Map<String,Connector.Argument> defaultArguments();
87  
88      /**
89       * Specification for and value of a Connector argument.
90       * Will always implement a subinterface of Argument:
91       * {@link Connector.StringArgument}, {@link Connector.BooleanArgument},
92       * {@link Connector.IntegerArgument},
93       * or {@link Connector.SelectedArgument}.
94       */
95      @jdk.Exported
96      public interface Argument extends Serializable {
97          /**
98           * Returns a short, unique identifier for the argument.
99           * Not intended for exposure to end-user.
100          *
101          * @return the name of this argument.
102          */
103         String name();
104 
105         /**
106          * Returns a short human-readable label for this argument.
107          *
108          * @return a label for this argument
109          */
110         String label();
111 
112         /**
113          * Returns a human-readable description of this argument
114          * and its purpose.
115          *
116          * @return the description of this argument
117          */
118         String description();
119 
120         /**
121          * Returns the current value of the argument. Initially, the
122          * default value is returned. If the value is currently unspecified,
123          * null is returned.
124          *
125          * @return the current value of the argument.
126          */
127         String value();
128 
129         /**
130          * Sets the value of the argument.
131          * The value should be checked with {@link #isValid(String)}
132          * before setting it; invalid values will throw an exception
133          * when the connection is established - for example,
134          * on {@link LaunchingConnector#launch}
135          */
136         void setValue(String value);
137 
138         /**
139          * Performs basic sanity check of argument.
140          * @return <code>true</code> if the value is valid to be
141          * used in {@link #setValue(String)}
142          */
143         boolean isValid(String value);
144 
145         /**
146          * Indicates whether the argument must be specified. If true,
147          * {@link #setValue} must be used to set a non-null value before
148          * using this argument in establishing a connection.
149          *
150          * @return <code>true</code> if the argument must be specified;
151          * <code>false</code> otherwise.
152          */
153         boolean mustSpecify();
154     }
155 
156     /**
157      * Specification for and value of a Connector argument,
158      * whose value is Boolean.  Boolean values are represented
159      * by the localized versions of the strings "true" and "false".
160      */
161     @jdk.Exported
162     public interface BooleanArgument extends Argument {
163         /**
164          * Sets the value of the argument.
165          */
166         void setValue(boolean value);
167 
168         /**
169          * Performs basic sanity check of argument.
170          * @return <code>true</code> if value is a string
171          * representation of a boolean value.
172          * @see #stringValueOf(boolean)
173          */
174         boolean isValid(String value);
175 
176         /**
177          * Return the string representation of the <code>value</code>
178          * parameter.
179          * Does not set or examine the current value of <code>this</code>
180          * instance.
181          * @return the localized String representation of the
182          * boolean value.
183          */
184         String stringValueOf(boolean value);
185 
186         /**
187          * Return the value of the argument as a boolean.  Since
188          * the argument may not have been set or may have an invalid
189          * value {@link #isValid(String)} should be called on
190          * {@link #value()} to check its validity.  If it is invalid
191          * the boolean returned by this method is undefined.
192          * @return the value of the argument as a boolean.
193          */
194         boolean booleanValue();
195     }
196 
197     /**
198      * Specification for and value of a Connector argument,
199      * whose value is an integer.  Integer values are represented
200      * by their corresponding strings.
201      */
202     @jdk.Exported
203     public interface IntegerArgument extends Argument {
204         /**
205          * Sets the value of the argument.
206          * The value should be checked with {@link #isValid(int)}
207          * before setting it; invalid values will throw an exception
208          * when the connection is established - for example,
209          * on {@link LaunchingConnector#launch}
210          */
211         void setValue(int value);
212 
213         /**
214          * Performs basic sanity check of argument.
215          * @return <code>true</code> if value represents an int that is
216          * <code>{@link #min()} &lt;= value &lt;= {@link #max()}</code>
217          */
218         boolean isValid(String value);
219 
220         /**
221          * Performs basic sanity check of argument.
222          * @return <code>true</code> if
223          * <code>{@link #min()} &lt;= value  &lt;= {@link #max()}</code>
224          */
225         boolean isValid(int value);
226 
227         /**
228          * Return the string representation of the <code>value</code>
229          * parameter.
230          * Does not set or examine the current value of <code>this</code>
231          * instance.
232          * @return the String representation of the
233          * int value.
234          */
235         String stringValueOf(int value);
236 
237         /**
238          * Return the value of the argument as a int.  Since
239          * the argument may not have been set or may have an invalid
240          * value {@link #isValid(String)} should be called on
241          * {@link #value()} to check its validity.  If it is invalid
242          * the int returned by this method is undefined.
243          * @return the value of the argument as a int.
244          */
245         int intValue();
246 
247         /**
248          * The upper bound for the value.
249          * @return the maximum allowed value for this argument.
250          */
251         int max();
252 
253         /**
254          * The lower bound for the value.
255          * @return the minimum allowed value for this argument.
256          */
257         int min();
258     }
259 
260     /**
261      * Specification for and value of a Connector argument,
262      * whose value is a String.
263      */
264     @jdk.Exported
265     public interface StringArgument extends Argument {
266         /**
267          * Performs basic sanity check of argument.
268          * @return <code>true</code> always
269          */
270         boolean isValid(String value);
271     }
272 
273     /**
274      * Specification for and value of a Connector argument,
275      * whose value is a String selected from a list of choices.
276      */
277     @jdk.Exported
278     public interface SelectedArgument extends Argument {
279         /**
280          * Return the possible values for the argument
281          * @return {@link List} of {@link String}
282          */
283         List<String> choices();
284 
285         /**
286          * Performs basic sanity check of argument.
287          * @return <code>true</code> if value is one of {@link #choices()}.
288          */
289         boolean isValid(String value);
290     }
291 }