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      */
name()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      */
description()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      */
transport()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      */
defaultArguments()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          */
name()103         String name();
104 
105         /**
106          * Returns a short human-readable label for this argument.
107          *
108          * @return a label for this argument
109          */
label()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          */
description()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          */
value()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          */
setValue(String value)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          */
isValid(String value)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          */
mustSpecify()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          */
setValue(boolean value)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          */
isValid(String value)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          */
stringValueOf(boolean value)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          */
booleanValue()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          */
setValue(int value)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          */
isValid(String value)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          */
isValid(int value)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          */
stringValueOf(int value)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          */
intValue()245         int intValue();
246 
247         /**
248          * The upper bound for the value.
249          * @return the maximum allowed value for this argument.
250          */
max()251         int max();
252 
253         /**
254          * The lower bound for the value.
255          * @return the minimum allowed value for this argument.
256          */
min()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          */
isValid(String value)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          */
choices()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          */
isValid(String value)289         boolean isValid(String value);
290     }
291 }
292