Save This Page
Home » openjdk-7 » com.sun » jdi » connect » spi » [javadoc | source]
com.sun.jdi.connect.spi
abstract public class: TransportService [javadoc | source]
java.lang.Object
   com.sun.jdi.connect.spi.TransportService

Direct Known Subclasses:
    SharedMemoryTransportService, SocketTransportService

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 com.sun.jdi.connect.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 Class Summary:
abstract public static class  TransportService.Capabilities  The transport service capabilities. 
abstract public static class  TransportService.ListenKey  A listen key.

A TransportService may listen on multiple, yet different, addresses at the same time. To uniquely identify each listener a listen key is created each time that {@link #startListening startListening} is called. The listen key is used in calls to the {@link #accept accept} method to accept inbound connections to that listener. A listen key is valid until it is used as an argument to {@link #stopListening stopListening} to stop the transport service from listening on an address. 

Method from com.sun.jdi.connect.spi.TransportService Summary:
accept,   attach,   capabilities,   description,   name,   startListening,   startListening,   stopListening
Methods from java.lang.Object:
clone,   equals,   finalize,   getClass,   hashCode,   notify,   notifyAll,   toString,   wait,   wait,   wait
Method from com.sun.jdi.connect.spi.TransportService Detail:
 abstract public Connection accept(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.

 abstract public 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.

 abstract public Capabilities capabilities()
    Returns the capabilities of the transport service.
 abstract public String description()
    Returns a description of the transport service.
 abstract public String name()
    Returns a name to identify the transport service.
 abstract public ListenKey startListening() throws IOException
    Listens on an address choosen by the transport service.

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

 abstract public 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.

 abstract public  void stopListening(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.