# Interface ListeningConnector

All Superinterfaces:
  `Connector`

public interface ListeningConnector extends Connector
A connector which listens for a connection initiated by a target VM.

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`
  `accept(Map<String, ? extends Connector.Argument> arguments)`
  Waits for a target VM to attach to this connector.
  `String`
  `startListening(Map<String, ? extends Connector.Argument> arguments)`
  Listens for one or more connections initiated by target VMs.
  `void`
  `stopListening(Map<String, ? extends Connector.Argument> arguments)`
  Cancels listening for connections.
  `boolean`
  `supportsMultipleConnections()`
  Indicates whether this listening connector supports multiple connections for a single argument map.

  ### 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

  - ### supportsMultipleConnections

    boolean supportsMultipleConnections()
    Indicates whether this listening connector supports multiple connections for a single argument map. If so, a call to `startListening(Map)` may allow multiple target VM to become connected.
    Returns:
      `true` if multiple connections are supported; `false` otherwise.

  - ### startListening

    String startListening(Map<String, ? extends Connector.Argument> arguments) throws IOException, IllegalConnectorArgumentsException
    Listens for one or more connections initiated by target VMs. The connector uses the given argument map in determining the address at which to listen or else it generates an appropriate listen address. In either case, an address string is returned from this method which can be used in starting target VMs to identify this connector. The format of the address string is connector, transport, and, possibly, platform dependent.

    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.

    This method does not return a `VirtualMachine`, and, normally, returns before any target VM initiates a connection. The connected target is obtained through `accept(Map)` (using the same argument map as is passed to this method).

    If `arguments` contains addressing information and only one connection will be accepted, the `accept` method can be called immediately without calling this method.

    Returns:
      the address at which the connector is listening for a connection.
    Throws:
      `IOException` - when unable to start listening. Specific exceptions are dependent on the Connector implementation in use.
      `IllegalConnectorArgumentsException` - when one of the connector arguments is invalid.

  - ### stopListening

    void stopListening(Map<String, ? extends Connector.Argument> arguments) throws IOException, IllegalConnectorArgumentsException
    Cancels listening for connections. The given argument map should match the argument map given for a previous `startListening(Map)` invocation.
    Throws:
      `IOException` - when unable to stop listening. Specific exceptions are dependent on the Connector implementation in use.
      `IllegalConnectorArgumentsException` - when one of the connector arguments is invalid.

  - ### accept

    VirtualMachine accept(Map<String, ? extends Connector.Argument> arguments) throws IOException, IllegalConnectorArgumentsException
    Waits for a target VM to attach to this connector.
    Throws:
      `TransportTimeoutException` - when the Connector encapsulates a transport that supports a timeout when accepting, a `Connector.Argument` representing a timeout has been set in the argument map, and a timeout occurs whilst waiting for the target VM to connect.
      `IOException` - when unable to accept. Specific exceptions are dependent on the Connector implementation in use.
      `IllegalConnectorArgumentsException` - when one of the connector arguments is invalid.