1 /* 2 * Copyright (c) 1998, 2004, 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 public interface Connector { 49 /** 50 * Returns a short identifier for the connector. Connector implementors 51 * should follow similar naming conventions as are used with packages 52 * to avoid name collisions. For example, the Sun connector 53 * implementations have names prefixed with "com.sun.jdi.". 54 * Not intended for exposure to end-user. 55 * 56 * @return the name of this connector. 57 */ 58 String name(); 59 60 /** 61 * Returns a human-readable description of this connector 62 * and its purpose. 63 * 64 * @return the description of this connector 65 */ 66 String description(); 67 68 /** 69 * Returns the transport mechanism used by this connector to establish 70 * connections with a target VM. 71 * 72 * @return the {@link Transport} used by this connector. 73 */ 74 Transport transport(); 75 76 /** 77 * Returns the arguments accepted by this Connector and their 78 * default values. The keys of the returned map are string argument 79 * names. The values are {@link Connector.Argument} containing 80 * information about the argument and its default value. 81 * 82 * @return the map associating argument names with argument 83 * information and default value. 84 */ 85 Map<String,Connector.Argument> defaultArguments(); 86 87 /** 88 * Specification for and value of a Connector argument. 89 * Will always implement a subinterface of Argument: 90 * {@link Connector.StringArgument}, {@link Connector.BooleanArgument}, 91 * {@link Connector.IntegerArgument}, 92 * or {@link Connector.SelectedArgument}. 93 */ 94 public interface Argument extends Serializable { 95 /** 96 * Returns a short, unique identifier for the argument. 97 * Not intended for exposure to end-user. 98 * 99 * @return the name of this argument. 100 */ 101 String name(); 102 103 /** 104 * Returns a short human-readable label for this argument. 105 * 106 * @return a label for this argument 107 */ 108 String label(); 109 110 /** 111 * Returns a human-readable description of this argument 112 * and its purpose. 113 * 114 * @return the description of this argument 115 */ 116 String description(); 117 118 /** 119 * Returns the current value of the argument. Initially, the 120 * default value is returned. If the value is currently unspecified, 121 * null is returned. 122 * 123 * @return the current value of the argument. 124 */ 125 String value(); 126 127 /** 128 * Sets the value of the argument. 129 * The value should be checked with {@link #isValid(String)} 130 * before setting it; invalid values will throw an exception 131 * when the connection is established - for example, 132 * on {@link LaunchingConnector#launch} 133 */ 134 void setValue(String value); 135 136 /** 137 * Performs basic sanity check of argument. 138 * @return <code>true</code> if the value is valid to be 139 * used in {@link #setValue(String)} 140 */ 141 boolean isValid(String value); 142 143 /** 144 * Indicates whether the argument must be specified. If true, 145 * {@link #setValue} must be used to set a non-null value before 146 * using this argument in establishing a connection. 147 * 148 * @return <code>true</code> if the argument must be specified; 149 * <code>false</code> otherwise. 150 */ 151 boolean mustSpecify(); 152 } 153 154 /** 155 * Specification for and value of a Connector argument, 156 * whose value is Boolean. Boolean values are represented 157 * by the localized versions of the strings "true" and "false". 158 */ 159 public interface BooleanArgument extends Argument { 160 /** 161 * Sets the value of the argument. 162 */ 163 void setValue(boolean value); 164 165 /** 166 * Performs basic sanity check of argument. 167 * @return <code>true</code> if value is a string 168 * representation of a boolean value. 169 * @see #stringValueOf(boolean) 170 */ 171 boolean isValid(String value); 172 173 /** 174 * Return the string representation of the <code>value</code> 175 * parameter. 176 * Does not set or examine the current value of <code>this</code> 177 * instance. 178 * @return the localized String representation of the 179 * boolean value. 180 */ 181 String stringValueOf(boolean value); 182 183 /** 184 * Return the value of the argument as a boolean. Since 185 * the argument may not have been set or may have an invalid 186 * value {@link #isValid(String)} should be called on 187 * {@link #value()} to check its validity. If it is invalid 188 * the boolean returned by this method is undefined. 189 * @return the value of the argument as a boolean. 190 */ 191 boolean booleanValue(); 192 } 193 194 /** 195 * Specification for and value of a Connector argument, 196 * whose value is an integer. Integer values are represented 197 * by their corresponding strings. 198 */ 199 public interface IntegerArgument extends Argument { 200 /** 201 * Sets the value of the argument. 202 * The value should be checked with {@link #isValid(int)} 203 * before setting it; invalid values will throw an exception 204 * when the connection is established - for example, 205 * on {@link LaunchingConnector#launch} 206 */ 207 void setValue(int value); 208 209 /** 210 * Performs basic sanity check of argument. 211 * @return <code>true</code> if value represents an int that is 212 * <code>{@link #min()} <= value <= {@link #max()}</code> 213 */ 214 boolean isValid(String value); 215 216 /** 217 * Performs basic sanity check of argument. 218 * @return <code>true</code> if 219 * <code>{@link #min()} <= value <= {@link #max()}</code> 220 */ 221 boolean isValid(int value); 222 223 /** 224 * Return the string representation of the <code>value</code> 225 * parameter. 226 * Does not set or examine the current value of <code>this</code> 227 * instance. 228 * @return the String representation of the 229 * int value. 230 */ 231 String stringValueOf(int value); 232 233 /** 234 * Return the value of the argument as a int. Since 235 * the argument may not have been set or may have an invalid 236 * value {@link #isValid(String)} should be called on 237 * {@link #value()} to check its validity. If it is invalid 238 * the int returned by this method is undefined. 239 * @return the value of the argument as a int. 240 */ 241 int intValue(); 242 243 /** 244 * The upper bound for the value. 245 * @return the maximum allowed value for this argument. 246 */ 247 int max(); 248 249 /** 250 * The lower bound for the value. 251 * @return the minimum allowed value for this argument. 252 */ 253 int min(); 254 } 255 256 /** 257 * Specification for and value of a Connector argument, 258 * whose value is a String. 259 */ 260 public interface StringArgument extends Argument { 261 /** 262 * Performs basic sanity check of argument. 263 * @return <code>true</code> always 264 */ 265 boolean isValid(String value); 266 } 267 268 /** 269 * Specification for and value of a Connector argument, 270 * whose value is a String selected from a list of choices. 271 */ 272 public interface SelectedArgument extends Argument { 273 /** 274 * Return the possible values for the argument 275 * @return {@link List} of {@link String} 276 */ 277 List<String> choices(); 278 279 /** 280 * Performs basic sanity check of argument. 281 * @return <code>true</code> if value is one of {@link #choices()}. 282 */ 283 boolean isValid(String value); 284 } 285 }