1/*
2 * Copyright (c) 1998, 2017, 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
26package com.sun.jdi.connect;
27
28import java.io.Serializable;
29import java.util.List;
30import java.util.Map;
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 */
48public interface Connector {
49
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    public interface Argument extends Serializable {
96
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    public interface BooleanArgument extends Argument {
162
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    public interface IntegerArgument extends Argument {
203
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    public interface StringArgument extends Argument {
265        /**
266         * Performs basic sanity check of argument.
267         * @return <code>true</code> always
268         */
269        boolean isValid(String value);
270    }
271
272    /**
273     * Specification for and value of a Connector argument,
274     * whose value is a String selected from a list of choices.
275     */
276    public interface SelectedArgument extends Argument {
277        /**
278         * Return the possible values for the argument
279         * @return {@link List} of {@link String}
280         */
281        List<String> choices();
282
283        /**
284         * Performs basic sanity check of argument.
285         * @return <code>true</code> if value is one of {@link #choices()}.
286         */
287        boolean isValid(String value);
288    }
289}
290