001: /*
002: * Copyright 1998-2004 Sun Microsystems, Inc. All Rights Reserved.
003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004: *
005: * This code is free software; you can redistribute it and/or modify it
006: * under the terms of the GNU General Public License version 2 only, as
007: * published by the Free Software Foundation. Sun designates this
008: * particular file as subject to the "Classpath" exception as provided
009: * by Sun in the LICENSE file that accompanied this code.
010: *
011: * This code is distributed in the hope that it will be useful, but WITHOUT
012: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014: * version 2 for more details (a copy is included in the LICENSE file that
015: * accompanied this code).
016: *
017: * You should have received a copy of the GNU General Public License version
018: * 2 along with this work; if not, write to the Free Software Foundation,
019: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022: * CA 95054 USA or visit www.sun.com if you need additional information or
023: * have any questions.
024: */
025:
026: package com.sun.jdi.connect;
027:
028: import java.util.Map;
029: import java.util.List;
030: import java.io.Serializable;
031:
032: /**
033: * A method of connection between a debugger and a target VM.
034: * A connector encapsulates exactly one {@link Transport}. used
035: * to establish the connection. Each connector has a set of arguments
036: * which controls its operation. The arguments are stored as a
037: * map, keyed by a string. Each implementation defines the string
038: * argument keys it accepts.
039: *
040: * @see LaunchingConnector
041: * @see AttachingConnector
042: * @see ListeningConnector
043: * @see Connector.Argument
044: *
045: * @author Gordon Hirsch
046: * @since 1.3
047: */
048: public interface Connector {
049: /**
050: * Returns a short identifier for the connector. Connector implementors
051: * should follow similar naming conventions as are used with packages
052: * to avoid name collisions. For example, the Sun connector
053: * implementations have names prefixed with "com.sun.jdi.".
054: * Not intended for exposure to end-user.
055: *
056: * @return the name of this connector.
057: */
058: String name();
059:
060: /**
061: * Returns a human-readable description of this connector
062: * and its purpose.
063: *
064: * @return the description of this connector
065: */
066: String description();
067:
068: /**
069: * Returns the transport mechanism used by this connector to establish
070: * connections with a target VM.
071: *
072: * @return the {@link Transport} used by this connector.
073: */
074: Transport transport();
075:
076: /**
077: * Returns the arguments accepted by this Connector and their
078: * default values. The keys of the returned map are string argument
079: * names. The values are {@link Connector.Argument} containing
080: * information about the argument and its default value.
081: *
082: * @return the map associating argument names with argument
083: * information and default value.
084: */
085: Map<String, Connector.Argument> defaultArguments();
086:
087: /**
088: * Specification for and value of a Connector argument.
089: * Will always implement a subinterface of Argument:
090: * {@link Connector.StringArgument}, {@link Connector.BooleanArgument},
091: * {@link Connector.IntegerArgument},
092: * or {@link Connector.SelectedArgument}.
093: */
094: public interface Argument extends Serializable {
095: /**
096: * Returns a short, unique identifier for the argument.
097: * Not intended for exposure to end-user.
098: *
099: * @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: }
|