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(java.lang.String, long, long)
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(com.sun.jdi.connect.spi.TransportService.ListenKey, long, long)
method is used to accept a connection initiated by a
target VM.
- Since:
- 1.5
-
Nested Class Summary
Modifier and TypeClassDescriptionstatic class
The transport service capabilities.static class
A listen key. -
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionabstract Connection
accept
(TransportService.ListenKey listenKey, long acceptTimeout, long handshakeTimeout) Accept a connection from a target VM.abstract Connection
Attaches to the specified address.abstract TransportService.Capabilities
Returns the capabilities of the transport service.abstract String
Returns a description of the transport service.abstract String
name()
Returns a name to identify the transport service.abstract TransportService.ListenKey
Listens on an address chosen by the transport service.abstract TransportService.ListenKey
startListening
(String address) Listens on the specified address for inbound connections.abstract void
stopListening
(TransportService.ListenKey listenKey) Stop listening for inbound connections.
-
Constructor Details
-
TransportService
public TransportService()Constructor for subclasses to call.
-
-
Method Details
-
name
Returns a name to identify the transport service.- Returns:
- The name of the transport service
-
description
Returns a description of the transport service.- Returns:
- The description of the transport service
-
capabilities
Returns the capabilities of the transport service.- Returns:
- the transport service capabilities
-
attach
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
- The address of the target VM.attachTimeout
- If this transport service supports an attach timeout, and ifattachTimeout
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 ifattachTimeout
is specified as zero then attach without any timeout.handshakeTimeout
- If this transport service supports a handshake timeout, and ifhandshakeTimeout
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 ifhandshakeTimeout
is specified as zero then the handshake does not timeout if there isn't a response from the target VM.- Returns:
- The Connection representing the bi-directional communication channel to the target VM.
- Throws:
TransportTimeoutException
- If a timeout occurs while establishing the connection.IOException
- If an I/O error occurs (including a timeout when handshaking).IllegalArgumentException
- If the address is invalid or the value of the attach timeout or handshake timeout is negative.- See Also:
-
startListening
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
- The address to start listening for connections, ornull
to listen on an address chosen by the transport service.- Returns:
- a listen key to be used in subsequent calls to be
accept
orstopListening
methods. - Throws:
IOException
- If an I/O error occurs.IllegalArgumentException
- If the specific address is invalid
-
startListening
Listens on an address chosen by the transport service.This convenience method works as if by invoking
startListening(null)
.- Returns:
- a listen key to be used in subsequent calls to be
accept
orstopListening
methods. - Throws:
IOException
- If an I/O error occurs.
-
stopListening
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
- The listen key obtained from a previous call tostartListening(String)
orstartListening()
.- Throws:
IllegalArgumentException
- If the listen key is invalidIOException
- If an I/O error occurs.
-
accept
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
- A listen key obtained from a previous call tostartListening(String)
orstartListening()
.acceptTimeout
- if this transport service supports an accept timeout, and ifacceptTimeout
is positive then block for up toacceptTimeout
milliseconds, more or less, while waiting for the target VM to connect. If the transport service does not support an accept timeout or ifacceptTimeout
is zero then block indefinitely for a target VM to connect.handshakeTimeout
- If this transport service supports a handshake timeout, and ifhandshakeTimeout
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 ifhandshakeTimeout
is specified as zero then the handshake does not timeout if there isn't a response from the target VM.- Returns:
- The Connection representing the bi-directional communication channel to the target VM.
- Throws:
TransportTimeoutException
- If a timeout occurs while waiting for a target VM to connect.IOException
- If an I/O error occurs (including a timeout when handshaking).IllegalArgumentException
- If the value of the acceptTimeout argument, or handshakeTimeout is negative, or an invalid listen key is provided.IllegalStateException
- IfstopListening
has already been called with this listen key and the transport service is no longer listening for inbound connections.- See Also:
-