/*
* Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package com.sun.jdi.connect;
import java.util.Map;
import java.util.List;
import java.io.Serializable;
A method of connection between a debugger and a target VM. A connector encapsulates exactly one Transport. used to establish the connection. Each connector has a set of arguments which controls its operation. The arguments are stored as a map, keyed by a string. Each implementation defines the string argument keys it accepts. Author: Gordon Hirsch See Also: Since: 1.3
/**
* A method of connection between a debugger and a target VM.
* A connector encapsulates exactly one {@link Transport}. used
* to establish the connection. Each connector has a set of arguments
* which controls its operation. The arguments are stored as a
* map, keyed by a string. Each implementation defines the string
* argument keys it accepts.
*
* @see LaunchingConnector
* @see AttachingConnector
* @see ListeningConnector
* @see Connector.Argument
*
* @author Gordon Hirsch
* @since 1.3
*/
public interface Connector {
Returns a short identifier for the connector. Connector implementors
should follow similar naming conventions as are used with packages
to avoid name collisions. For example, the Sun connector
implementations have names prefixed with "com.sun.jdi.".
Not intended for exposure to end-user.
Returns: the name of this connector.
/**
* Returns a short identifier for the connector. Connector implementors
* should follow similar naming conventions as are used with packages
* to avoid name collisions. For example, the Sun connector
* implementations have names prefixed with "com.sun.jdi.".
* Not intended for exposure to end-user.
*
* @return the name of this connector.
*/
String name();
Returns a human-readable description of this connector
and its purpose.
Returns: the description of this connector
/**
* Returns a human-readable description of this connector
* and its purpose.
*
* @return the description of this connector
*/
String description();
Returns the transport mechanism used by this connector to establish
connections with a target VM.
Returns: the Transport used by this connector.
/**
* Returns the transport mechanism used by this connector to establish
* connections with a target VM.
*
* @return the {@link Transport} used by this connector.
*/
Transport transport();
Returns the arguments accepted by this Connector and their default values. The keys of the returned map are string argument names. The values are Argument containing information about the argument and its default value. Returns: the map associating argument names with argument
information and default value.
/**
* Returns the arguments accepted by this Connector and their
* default values. The keys of the returned map are string argument
* names. The values are {@link Connector.Argument} containing
* information about the argument and its default value.
*
* @return the map associating argument names with argument
* information and default value.
*/
Map<String,Connector.Argument> defaultArguments();
Specification for and value of a Connector argument. Will always implement a subinterface of Argument: StringArgument, BooleanArgument, IntegerArgument, or SelectedArgument. /**
* Specification for and value of a Connector argument.
* Will always implement a subinterface of Argument:
* {@link Connector.StringArgument}, {@link Connector.BooleanArgument},
* {@link Connector.IntegerArgument},
* or {@link Connector.SelectedArgument}.
*/
public interface Argument extends Serializable {
Returns a short, unique identifier for the argument.
Not intended for exposure to end-user.
Returns: the name of this argument.
/**
* Returns a short, unique identifier for the argument.
* Not intended for exposure to end-user.
*
* @return the name of this argument.
*/
String name();
Returns a short human-readable label for this argument.
Returns: a label for this argument
/**
* Returns a short human-readable label for this argument.
*
* @return a label for this argument
*/
String label();
Returns a human-readable description of this argument
and its purpose.
Returns: the description of this argument
/**
* Returns a human-readable description of this argument
* and its purpose.
*
* @return the description of this argument
*/
String description();
Returns the current value of the argument. Initially, the
default value is returned. If the value is currently unspecified,
null is returned.
Returns: the current value of the argument.
/**
* Returns the current value of the argument. Initially, the
* default value is returned. If the value is currently unspecified,
* null is returned.
*
* @return the current value of the argument.
*/
String value();
Sets the value of the argument. The value should be checked with isValid(String) before setting it; invalid values will throw an exception when the connection is established - for example, on LaunchingConnector.launch /**
* Sets the value of the argument.
* The value should be checked with {@link #isValid(String)}
* before setting it; invalid values will throw an exception
* when the connection is established - for example,
* on {@link LaunchingConnector#launch}
*/
void setValue(String value);
Performs basic sanity check of argument.
Returns: true if the value is valid to be used in setValue(String)
/**
* Performs basic sanity check of argument.
* @return <code>true</code> if the value is valid to be
* used in {@link #setValue(String)}
*/
boolean isValid(String value);
Indicates whether the argument must be specified. If true, setValue must be used to set a non-null value before using this argument in establishing a connection. Returns: true if the argument must be specified;
false otherwise.
/**
* Indicates whether the argument must be specified. If true,
* {@link #setValue} must be used to set a non-null value before
* using this argument in establishing a connection.
*
* @return <code>true</code> if the argument must be specified;
* <code>false</code> otherwise.
*/
boolean mustSpecify();
}
Specification for and value of a Connector argument,
whose value is Boolean. Boolean values are represented
by the localized versions of the strings "true" and "false".
/**
* Specification for and value of a Connector argument,
* whose value is Boolean. Boolean values are represented
* by the localized versions of the strings "true" and "false".
*/
public interface BooleanArgument extends Argument {
Sets the value of the argument.
/**
* Sets the value of the argument.
*/
void setValue(boolean value);
Performs basic sanity check of argument.
See Also: Returns: true if value is a string
representation of a boolean value.
/**
* Performs basic sanity check of argument.
* @return <code>true</code> if value is a string
* representation of a boolean value.
* @see #stringValueOf(boolean)
*/
boolean isValid(String value);
Return the string representation of the value
parameter.
Does not set or examine the current value of this
instance.
Returns: the localized String representation of the
boolean value.
/**
* Return the string representation of the <code>value</code>
* parameter.
* Does not set or examine the current value of <code>this</code>
* instance.
* @return the localized String representation of the
* boolean value.
*/
String stringValueOf(boolean value);
Return the value of the argument as a boolean. Since the argument may not have been set or may have an invalid value isValid(String) should be called on Argument.value() to check its validity. If it is invalid the boolean returned by this method is undefined. Returns: the value of the argument as a boolean.
/**
* Return the value of the argument as a boolean. Since
* the argument may not have been set or may have an invalid
* value {@link #isValid(String)} should be called on
* {@link #value()} to check its validity. If it is invalid
* the boolean returned by this method is undefined.
* @return the value of the argument as a boolean.
*/
boolean booleanValue();
}
Specification for and value of a Connector argument,
whose value is an integer. Integer values are represented
by their corresponding strings.
/**
* Specification for and value of a Connector argument,
* whose value is an integer. Integer values are represented
* by their corresponding strings.
*/
public interface IntegerArgument extends Argument {
Sets the value of the argument. The value should be checked with isValid(int) before setting it; invalid values will throw an exception when the connection is established - for example, on LaunchingConnector.launch /**
* Sets the value of the argument.
* The value should be checked with {@link #isValid(int)}
* before setting it; invalid values will throw an exception
* when the connection is established - for example,
* on {@link LaunchingConnector#launch}
*/
void setValue(int value);
Performs basic sanity check of argument.
Returns: true if value represents an int that is
min() <= value <= max()
/**
* Performs basic sanity check of argument.
* @return <code>true</code> if value represents an int that is
* <code>{@link #min()} <= value <= {@link #max()}</code>
*/
boolean isValid(String value);
Performs basic sanity check of argument.
Returns: true if
min() <= value <= max()
/**
* Performs basic sanity check of argument.
* @return <code>true</code> if
* <code>{@link #min()} <= value <= {@link #max()}</code>
*/
boolean isValid(int value);
Return the string representation of the value
parameter.
Does not set or examine the current value of this
instance.
Returns: the String representation of the
int value.
/**
* Return the string representation of the <code>value</code>
* parameter.
* Does not set or examine the current value of <code>this</code>
* instance.
* @return the String representation of the
* int value.
*/
String stringValueOf(int value);
Return the value of the argument as a int. Since the argument may not have been set or may have an invalid value isValid(String) should be called on Argument.value() to check its validity. If it is invalid the int returned by this method is undefined. Returns: the value of the argument as a int.
/**
* Return the value of the argument as a int. Since
* the argument may not have been set or may have an invalid
* value {@link #isValid(String)} should be called on
* {@link #value()} to check its validity. If it is invalid
* the int returned by this method is undefined.
* @return the value of the argument as a int.
*/
int intValue();
The upper bound for the value.
Returns: the maximum allowed value for this argument.
/**
* The upper bound for the value.
* @return the maximum allowed value for this argument.
*/
int max();
The lower bound for the value.
Returns: the minimum allowed value for this argument.
/**
* The lower bound for the value.
* @return the minimum allowed value for this argument.
*/
int min();
}
Specification for and value of a Connector argument,
whose value is a String.
/**
* Specification for and value of a Connector argument,
* whose value is a String.
*/
public interface StringArgument extends Argument {
Performs basic sanity check of argument.
Returns: true always
/**
* Performs basic sanity check of argument.
* @return <code>true</code> always
*/
boolean isValid(String value);
}
Specification for and value of a Connector argument,
whose value is a String selected from a list of choices.
/**
* Specification for and value of a Connector argument,
* whose value is a String selected from a list of choices.
*/
public interface SelectedArgument extends Argument {
Return the possible values for the argument
Returns: List of String
/**
* Return the possible values for the argument
* @return {@link List} of {@link String}
*/
List<String> choices();
Performs basic sanity check of argument.
Returns: true if value is one of choices().
/**
* Performs basic sanity check of argument.
* @return <code>true</code> if value is one of {@link #choices()}.
*/
boolean isValid(String value);
}
}