A transport service for connections between a debugger and a target VM.

A transport service is a concrete subclass of this class that has a zero-argument constructor and implements the abstract methods specified below. It is the underlying service used by a Transport for connections between a debugger and a target VM.

A transport service is used to establish a connection between a debugger and a target VM, and to transport Java Debug Wire Protocol (JDWP) packets over an underlying communication protocol. In essence a transport service implementation binds JDWP (as specified in the JDWP specification) to an underlying communication protocol. A transport service implementation provides a reliable JDWP packet transportation service. JDWP packets are sent to and from the target VM without duplication or data loss. A transport service implementation may be based on an underlying communication protocol that is reliable or unreliable. If the underlying communication protocol is reliable then the transport service implementation may be relatively simple and may only need to transport JDWP packets as payloads of the underlying communication protocol. In the case of an unreliable communication protocol the transport service implementation may include additional protocol support in order to ensure that packets are not duplicated and that there is no data loss. The details of such protocols are specific to the implementation but may involve techniques such as the positive acknowledgment with retransmission technique used in protocols such as the Transmission Control Protocol (TCP) (see RFC 793 ).

A transport service can be used to initiate a connection to a target VM. This is done by invoking the attach method. Alternatively, a transport service can listen and accept connections initiated by a target VM. This is done by invoking the startListening(String) method to put the transport into listen mode. Then the accept method is used to accept a connection initiated by a target VM.

Nested and Inner Type Summary

Modifier and Type	Class and Description
public abstract static class	TransportService.Capabilities The transport service capabilities.
public abstract static class	TransportService.ListenKey A listen key.

Constructor Summary

Access	Constructor and Description
public	TransportService() Constructor for subclasses to call.

Method Summary

Modifier and Type	Method and Description
public abstract Connection	Returns: The Connection representing the bi-directional communication channel to the target VM. accept(TransportService.ListenKey A listen key obtained from a previous call to `startListening(String)` or `startListening()`. listenKey, long if this transport service supports an accept timeout, and if `acceptTimeout` is positive then block for up to `acceptTimeout` milliseconds, more or less, while waiting for the target VM to connect. If the transport service does not support an accept timeout or if `acceptTimeout` is zero then block indefinitely for a target VM to connect. acceptTimeout, long If this transport service supports a handshake timeout, and if `handshakeTimeout` is positive, then it specifies the timeout, in milliseconds (more or less), to use when handshaking with the target VM. The exact usage of the timeout is specific to the transport service. A transport service may, for example, use the handshake timeout as the inter-character timeout while waiting for the JDWP-Handshake message from the target VM. Alternatively, a transport service may, for example, use the timeout as a timeout for the duration of the handshake exchange. If the transport service does not support a handshake timeout, of if `handshakeTimeout` is specified as zero then the handshake does not timeout if there isn't a response from the target VM. handshakeTimeout) Accept a connection from a target VM.
public abstract Connection	Returns: The Connection representing the bi-directional communication channel to the target VM. attach(String The address of the target VM. address, long If this transport service supports an attach timeout, and if `attachTimeout` is positive, then it specifies the timeout, in milliseconds (more or less), to use when attaching to the target VM. If the transport service does not support an attach timeout, or if `attachTimeout` is specified as zero then attach without any timeout. attachTimeout, long If this transport service supports a handshake timeout, and if `handshakeTimeout` is positive, then it specifies the timeout, in milliseconds (more or less), to use when handshaking with the target VM. The exact usage of the timeout are specific to the transport service. A transport service may, for example, use the handshake timeout as the inter-character timeout while waiting for the JDWP-Handshake message from the target VM. Alternatively, a transport service may, for example, use the handshakeTimeout as a timeout for the duration of the handshake exchange. If the transport service does not support a handshake timeout, or if `handshakeTimeout` is specified as zero then the handshake does not timeout if there isn't a response from the target VM. handshakeTimeout) Attaches to the specified address.
public abstract TransportService.Capabilities	Returns: the transport service capabilities capabilities() Returns the capabilities of the transport service.
public abstract String	Returns: The description of the transport service description() Returns a description of the transport service.
public abstract String	Returns: The name of the transport service name() Returns a name to identify the transport service.
public abstract TransportService.ListenKey	Returns: a listen key to be used in subsequent calls to be `accept` or `stopListening` methods. startListening(String The address to start listening for connections, or `null` to listen on an address chosen by the transport service. address) Listens on the specified address for inbound connections.
public abstract TransportService.ListenKey	Returns: a listen key to be used in subsequent calls to be `accept` or `stopListening` methods. startListening() Listens on an address chosen by the transport service.
public abstract void	stopListening(TransportService.ListenKey The listen key obtained from a previous call to `startListening(String)` or `startListening()`. listenKey) Stop listening for inbound connections.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Constructor Detail

TransportService	back to summary
public TransportService() Constructor for subclasses to call.

Method Detail

accept back to summary

accept	back to summary
public abstract Connection accept(TransportService.ListenKey listenKey, long acceptTimeout, long handshakeTimeout) throws IOException Accept a connection from a target VM. Waits (indefinitely or with timeout) to accept a connection from a target VM. Returns a connection representing the bi-directional communication channel to the target VM. Accepting a connection from a target VM involves two steps. First, the transport service waits to accept the connection from the target VM. Once the connection is established a handshake is performed to ensure that the connection is indeed to a target VM. The handshake involves the exchange of a string JDWP-Handshake as specified in the Java Debug Wire Protocol specification. Parameters listenKey:TransportService.ListenKey A listen key obtained from a previous call to `startListening(String)` or `startListening()`. acceptTimeout:long if this transport service supports an accept timeout, and if `acceptTimeout` is positive then block for up to `acceptTimeout` milliseconds, more or less, while waiting for the target VM to connect. If the transport service does not support an accept timeout or if `acceptTimeout` is zero then block indefinitely for a target VM to connect. handshakeTimeout:long If this transport service supports a handshake timeout, and if `handshakeTimeout` is positive, then it specifies the timeout, in milliseconds (more or less), to use when handshaking with the target VM. The exact usage of the timeout is specific to the transport service. A transport service may, for example, use the handshake timeout as the inter-character timeout while waiting for the JDWP-Handshake message from the target VM. Alternatively, a transport service may, for example, use the timeout as a timeout for the duration of the handshake exchange. If the transport service does not support a handshake timeout, of if `handshakeTimeout` is specified as zero then the handshake does not timeout if there isn't a response from the target VM. Returns:Connection The Connection representing the bi-directional communication channel to the target VM. Exceptions IOException: If an I/O error occurs (including a timeout when handshaking). TransportTimeoutException: If a timeout occurs while waiting for a target VM to connect. IllegalArgumentException: If the value of the acceptTimeout argument, or handshakeTimeout is negative, or an invalid listen key is provided. IllegalStateException: If `stopListening` has already been called with this listen key and the transport service is no longer listening for inbound connections. See Also `TransportService.Capabilities#supportsAcceptTimeout()`

public abstract Connection accept(TransportService.ListenKey listenKey, long acceptTimeout, long handshakeTimeout) throws IOException

Accept a connection from a target VM.

Waits (indefinitely or with timeout) to accept a connection from a target VM. Returns a connection representing the bi-directional communication channel to the target VM.

Accepting a connection from a target VM involves two steps. First, the transport service waits to accept the connection from the target VM. Once the connection is established a handshake is performed to ensure that the connection is indeed to a target VM. The handshake involves the exchange of a string JDWP-Handshake as specified in the Java Debug Wire Protocol specification.

Parameters

listenKey:TransportService.ListenKey: A listen key obtained from a previous call to startListening(String) or startListening().
acceptTimeout:long: if this transport service supports an accept timeout, and if acceptTimeout is positive then block for up to acceptTimeout milliseconds, more or less, while waiting for the target VM to connect. If the transport service does not support an accept timeout or if acceptTimeout is zero then block indefinitely for a target VM to connect.
handshakeTimeout:long: If this transport service supports a handshake timeout, and if handshakeTimeout is positive, then it specifies the timeout, in milliseconds (more or less), to use when handshaking with the target VM. The exact usage of the timeout is specific to the transport service. A transport service may, for example, use the handshake timeout as the inter-character timeout while waiting for the JDWP-Handshake message from the target VM. Alternatively, a transport service may, for example, use the timeout as a timeout for the duration of the handshake exchange. If the transport service does not support a handshake timeout, of if handshakeTimeout is specified as zero then the handshake does not timeout if there isn't a response from the target VM.

Returns:Connection

The Connection representing the bi-directional communication channel to the target VM.

Exceptions

IOException:: If an I/O error occurs (including a timeout when handshaking).
TransportTimeoutException:: If a timeout occurs while waiting for a target VM to connect.
IllegalArgumentException:: If the value of the acceptTimeout argument, or handshakeTimeout is negative, or an invalid listen key is provided.
IllegalStateException:: If stopListening has already been called with this listen key and the transport service is no longer listening for inbound connections.

attach back to summary

attach	back to summary
public abstract Connection attach(String address, long attachTimeout, long handshakeTimeout) throws IOException Attaches to the specified address. Attaches to the specified address and returns a connection representing the bi-directional communication channel to the target VM. Attaching to the target VM involves two steps: First, a connection is established to specified address. This is followed by a handshake to ensure that the connection is to a target VM. The handshake involves the exchange of a string JDWP-Handshake as specified in the Java Debug Wire Protocol specification. Parameters address:String The address of the target VM. attachTimeout:long If this transport service supports an attach timeout, and if `attachTimeout` is positive, then it specifies the timeout, in milliseconds (more or less), to use when attaching to the target VM. If the transport service does not support an attach timeout, or if `attachTimeout` is specified as zero then attach without any timeout. handshakeTimeout:long If this transport service supports a handshake timeout, and if `handshakeTimeout` is positive, then it specifies the timeout, in milliseconds (more or less), to use when handshaking with the target VM. The exact usage of the timeout are specific to the transport service. A transport service may, for example, use the handshake timeout as the inter-character timeout while waiting for the JDWP-Handshake message from the target VM. Alternatively, a transport service may, for example, use the handshakeTimeout as a timeout for the duration of the handshake exchange. If the transport service does not support a handshake timeout, or if `handshakeTimeout` is specified as zero then the handshake does not timeout if there isn't a response from the target VM. Returns:Connection The Connection representing the bi-directional communication channel to the target VM. Exceptions IOException: If an I/O error occurs (including a timeout when handshaking). TransportTimeoutException: If a timeout occurs while establishing the connection. IllegalArgumentException: If the address is invalid or the value of the attach timeout or handshake timeout is negative. See Also `TransportService.Capabilities#supportsAttachTimeout()`

public abstract Connection attach(String address, long attachTimeout, long handshakeTimeout) throws IOException

Attaches to the specified address.

Attaches to the specified address and returns a connection representing the bi-directional communication channel to the target VM.

Attaching to the target VM involves two steps: First, a connection is established to specified address. This is followed by a handshake to ensure that the connection is to a target VM. The handshake involves the exchange of a string JDWP-Handshake as specified in the Java Debug Wire Protocol specification.

Parameters

address:String: The address of the target VM.
attachTimeout:long: If this transport service supports an attach timeout, and if attachTimeout is positive, then it specifies the timeout, in milliseconds (more or less), to use when attaching to the target VM. If the transport service does not support an attach timeout, or if attachTimeout is specified as zero then attach without any timeout.
handshakeTimeout:long: If this transport service supports a handshake timeout, and if handshakeTimeout is positive, then it specifies the timeout, in milliseconds (more or less), to use when handshaking with the target VM. The exact usage of the timeout are specific to the transport service. A transport service may, for example, use the handshake timeout as the inter-character timeout while waiting for the JDWP-Handshake message from the target VM. Alternatively, a transport service may, for example, use the handshakeTimeout as a timeout for the duration of the handshake exchange. If the transport service does not support a handshake timeout, or if handshakeTimeout is specified as zero then the handshake does not timeout if there isn't a response from the target VM.

Returns:Connection

The Connection representing the bi-directional communication channel to the target VM.

Exceptions

IOException:: If an I/O error occurs (including a timeout when handshaking).
TransportTimeoutException:: If a timeout occurs while establishing the connection.
IllegalArgumentException:: If the address is invalid or the value of the attach timeout or handshake timeout is negative.

capabilities	back to summary
public abstract TransportService.Capabilities capabilities() Returns the capabilities of the transport service. Returns:TransportService.Capabilities the transport service capabilities

capabilities

back to summary

public abstract TransportService.Capabilities capabilities()

Returns the capabilities of the transport service.

Returns:TransportService.Capabilities: the transport service capabilities

description	back to summary
public abstract String description() Returns a description of the transport service. Returns:String The description of the transport service

description

back to summary

public abstract String description()

Returns a description of the transport service.

Returns:String: The description of the transport service

name	back to summary
public abstract String name() Returns a name to identify the transport service. Returns:String The name of the transport service

name

back to summary

public abstract String name()

Returns a name to identify the transport service.

Returns:String: The name of the transport service

startListening back to summary

startListening	back to summary
public abstract TransportService.ListenKey startListening(String address) throws IOException Listens on the specified address for inbound connections. This method starts the transport service listening on the specified address so that it can subsequently accept an inbound connection. It does not wait until an inbound connection is established. Parameters address:String The address to start listening for connections, or `null` to listen on an address chosen by the transport service. Returns:TransportService.ListenKey a listen key to be used in subsequent calls to be `accept` or `stopListening` methods. Exceptions IOException: If an I/O error occurs. IllegalArgumentException: If the specific address is invalid

public abstract TransportService.ListenKey startListening(String address) throws IOException

Listens on the specified address for inbound connections.

This method starts the transport service listening on the specified address so that it can subsequently accept an inbound connection. It does not wait until an inbound connection is established.

Parameters

address:String: The address to start listening for connections, or null to listen on an address chosen by the transport service.

Returns:TransportService.ListenKey

a listen key to be used in subsequent calls to be accept or stopListening methods.

Exceptions

IOException:: If an I/O error occurs.
IllegalArgumentException:: If the specific address is invalid

startListening back to summary

startListening	back to summary
public abstract TransportService.ListenKey startListening() throws IOException Listens on an address chosen by the transport service. This convenience method works as if by invoking `startListening(null)`. Returns:TransportService.ListenKey a listen key to be used in subsequent calls to be `accept` or `stopListening` methods. Exceptions IOException: If an I/O error occurs.

public abstract TransportService.ListenKey startListening() throws IOException

Listens on an address chosen by the transport service.

This convenience method works as if by invoking startListening(null).

Returns:TransportService.ListenKey

a listen key to be used in subsequent calls to be accept or stopListening methods.

Exceptions

IOException:: If an I/O error occurs.

stopListening back to summary

stopListening	back to summary
public abstract void stopListening(TransportService.ListenKey listenKey) throws IOException Stop listening for inbound connections. Invoking this method while another thread is blocked in `accept`, with the same listen key, waiting to accept a connection will cause that thread to throw an IOException. If the thread blocked in accept has already accepted a connection from a target VM and is in the process of handshaking with the target VM then invoking this method will not cause the thread to throw an exception. Parameters listenKey:TransportService.ListenKey The listen key obtained from a previous call to `startListening(String)` or `startListening()`. Exceptions IOException: If an I/O error occurs. IllegalArgumentException: If the listen key is invalid

public abstract void stopListening(TransportService.ListenKey listenKey) throws IOException

Stop listening for inbound connections.

Invoking this method while another thread is blocked in accept, with the same listen key, waiting to accept a connection will cause that thread to throw an IOException. If the thread blocked in accept has already accepted a connection from a target VM and is in the process of handshaking with the target VM then invoking this method will not cause the thread to throw an exception.

Parameters

listenKey:TransportService.ListenKey: The listen key obtained from a previous call to startListening(String) or startListening().

Exceptions

IOException:: If an I/O error occurs.
IllegalArgumentException:: If the listen key is invalid

com.sun.jdi.connect.spi back to summary

public abstract Class TransportService.Capabilities

Class Inheritance

extends Object

java.lang.Object
com.sun.jdi.connect.spi.TransportService.Capabilities

The transport service capabilities.

Constructor Summary

Access	Constructor and Description
public	Capabilities() Constructor for subclasses to call.

Method Summary

Modifier and Type	Method and Description
public abstract boolean	Returns: `true` if, and only if, this transport service supports timeout while waiting for a target VM to connect. supportsAcceptTimeout() Tell whether or not this transport service supports a timeout while waiting for a target VM to connect.
public abstract boolean	Returns: `true` if, and only if, this transport service supports attaching with a timeout. supportsAttachTimeout() Tell whether or not this transport service supports a timeout when attaching to a target VM.
public abstract boolean	Returns: `true` if, and only if, this transport service supports a timeout while handshaking with the target VM. supportsHandshakeTimeout() Tells whether or not this transport service supports a timeout when handshaking with the target VM.
public abstract boolean	Returns: `true` if, and only if, this transport service supports multiple connections. supportsMultipleConnections() Tells whether or not this transport service can support multiple concurrent connections to a single address that it is listening on.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Constructor Detail

Capabilities	back to summary
public Capabilities() Constructor for subclasses to call.

Method Detail

supportsAcceptTimeout back to summary

supportsAcceptTimeout	back to summary
public abstract boolean supportsAcceptTimeout() Tell whether or not this transport service supports a timeout while waiting for a target VM to connect. Returns:boolean `true` if, and only if, this transport service supports timeout while waiting for a target VM to connect. See Also `accept(TransportService.ListenKey, long, long)`

public abstract boolean supportsAcceptTimeout()

Tell whether or not this transport service supports a timeout while waiting for a target VM to connect.

Returns:boolean: true if, and only if, this transport service supports timeout while waiting for a target VM to connect.
See Also: accept(TransportService.ListenKey, long, long)

supportsAttachTimeout back to summary

supportsAttachTimeout	back to summary
public abstract boolean supportsAttachTimeout() Tell whether or not this transport service supports a timeout when attaching to a target VM. Returns:boolean `true` if, and only if, this transport service supports attaching with a timeout. See Also `attach(String, long, long)`

public abstract boolean supportsAttachTimeout()

Tell whether or not this transport service supports a timeout when attaching to a target VM.

Returns:boolean: true if, and only if, this transport service supports attaching with a timeout.
See Also: attach(String, long, long)

supportsHandshakeTimeout back to summary

supportsHandshakeTimeout	back to summary
public abstract boolean supportsHandshakeTimeout() Tells whether or not this transport service supports a timeout when handshaking with the target VM. Returns:boolean `true` if, and only if, this transport service supports a timeout while handshaking with the target VM. See Also `attach(String, long, long)`, `accept(TransportService.ListenKey, long, long)`

public abstract boolean supportsHandshakeTimeout()

Tells whether or not this transport service supports a timeout when handshaking with the target VM.

Returns:boolean: true if, and only if, this transport service supports a timeout while handshaking with the target VM.
See Also: attach(String, long, long), accept(TransportService.ListenKey, long, long)

supportsMultipleConnections back to summary

supportsMultipleConnections	back to summary
public abstract boolean supportsMultipleConnections() Tells whether or not this transport service can support multiple concurrent connections to a single address that it is listening on. Returns:boolean `true` if, and only if, this transport service supports multiple connections.

public abstract boolean supportsMultipleConnections()

Tells whether or not this transport service can support multiple concurrent connections to a single address that it is listening on.

Returns:boolean: true if, and only if, this transport service supports multiple connections.

public abstract Class TransportService

Nested and Inner Type Summary

Constructor Summary

Method Summary

Constructor Detail

Method Detail

public abstract Class TransportService.Capabilities

Constructor Summary

Method Summary

Constructor Detail

Method Detail

public abstract Class TransportService.ListenKey

Constructor Summary

Method Summary

Constructor Detail

Method Detail