Interface LaunchingConnector

All Superinterfaces:

Connector

public interface LaunchingConnector
extends Connector

A connector which can launch a target VM before connecting to it.

Since:

1.3

Nested Class Summary

Nested classes/interfaces declared in interface Connector

Connector.Argument, Connector.BooleanArgument, Connector.IntegerArgument, Connector.SelectedArgument, Connector.StringArgument

Modifier and Type	Interface	Description
static interface	Connector.Argument	Specification for and value of a Connector argument.
static interface	Connector.BooleanArgument	Specification for and value of a Connector argument, whose value is Boolean.
static interface	Connector.IntegerArgument	Specification for and value of a Connector argument, whose value is an integer.
static interface	Connector.SelectedArgument	Specification for and value of a Connector argument, whose value is a String selected from a list of choices.
static interface	Connector.StringArgument	Specification for and value of a Connector argument, whose value is a String.

Method Summary

Modifier and Type	Method	Description
VirtualMachine	launch(Map<String, ? extends Connector.Argument> arguments)	Launches an application and connects to its VM.

Methods declared in interface Connector

defaultArguments, description, name, transport

Modifier and Type	Method	Description
Map<String, Connector.Argument>	defaultArguments()	Returns the arguments accepted by this Connector and their default values.
String	description()	Returns a human-readable description of this connector and its purpose.
String	name()	Returns a short identifier for the connector.
Transport	transport()	Returns the transport mechanism used by this connector to establish connections with a target VM.

Method Details

launch

VirtualMachine launch(Map<String, ? extends Connector.Argument> arguments)
               throws IOException,
IllegalConnectorArgumentsException,
VMStartException

Launches an application and connects to its VM. Properties of the launch (possibly including options, main class, and arguments) are specified in arguments. The argument map associates argument name strings to instances of Connector.Argument. The default argument map for a connector can be obtained through Connector.defaultArguments(). Argument map values can be changed, but map entries should not be added or deleted.

A target VM launched by a launching connector is not guaranteed to be stable until after the VMStartEvent has been received.

Important note: If a target VM is launched through this funcctions, its output and error streams must be read as it executes. These streams are available through the Process object returned by VirtualMachine.process(). If the streams are not periodically read, the target VM will stop executing when the buffers for these streams are filled.

Parameters:

arguments - the argument map to be used in launching the VM.

Returns:

the VirtualMachine mirror of the target VM.

Throws:

IOException - when unable to launch. Specific exceptions are dependent on the Connector implementation in use.

IllegalConnectorArgumentsException - when one of the connector arguments is invalid.

VMStartException - when the VM was successfully launched, but terminated with an error before a connection could be established.