| java.lang.Object
 com.sun.jdi.connect.spi.Connection
| Connection | | abstract public class Connection (Code) | | A connection between a debugger and a target VM which it debugs.
A Connection represents a bi-directional communication channel
between a debugger and a target VM. A Connection is created when
com.sun.jdi.connect.spi.TransportService TransportService establishes a connection and successfully handshakes with a target
VM. A TransportService implementation provides a reliable
JDWP packet transportation service and consequently a Connection
provides a reliable flow of JDWP packets between the debugger
and the target VM. A Connection is stream oriented, that is, the
JDWP packets written to a connection are read by the target VM
in the order in which they were written. Similiarly packets written
to a Connection by the target VM are read by the debugger in the
order in which they were written.
A connection is either open or closed. It is open upon creation,
and remains open until it is closed. Once closed, it remains closed,
and any attempt to invoke an I/O operation upon it will cause a
ClosedConnectionException to be thrown. A connection can
be tested by invoking the
Connection.isOpen isOpen method.
A Connection is safe for access by multiple concurrent threads,
although at most one thread may be reading and at most one thread may
be writing at any given time.
since:
1.5 |
| Method Summary | |
| abstract public void | close()
Closes this connection.
If the connection is already closed then invoking this method
has no effect. | | abstract public boolean | isOpen()
Tells whether or not this connection is open. | | abstract public byte[] | readPacket()
Reads a packet from the target VM.
Attempts to read a JDWP packet from the target VM.
A read operation may block indefinitely and only returns
when it reads all bytes of a packet, or in the case of a
transport service that is based on a stream-oriented
communication protocol, the end of stream is encountered.
Reading a packet does not do any integrity checking on
the packet aside from a check that the length of the packet
(as indicated by the value of the length field, the
first four bytes of the packet) is 11 or more bytes.
If the value of the length value is less then 11
then an IOException is thrown.
Returns a byte array of a length equal to the length
of the received packet, or a byte array of length 0 when an
end of stream is encountered. | | abstract public void | writePacket(byte pkt)
Writes a packet to the target VM.
Attempts to write, or send, a JDWP packet to the target VM.
A write operation only returns after writing the entire packet
to the target VM. |
| isOpen | | abstract public boolean isOpen()(Code) | | Tells whether or not this connection is open.
true if, and only if, this connection is open |
| readPacket | | abstract public byte[] readPacket() throws IOException(Code) | | Reads a packet from the target VM.
Attempts to read a JDWP packet from the target VM.
A read operation may block indefinitely and only returns
when it reads all bytes of a packet, or in the case of a
transport service that is based on a stream-oriented
communication protocol, the end of stream is encountered.
Reading a packet does not do any integrity checking on
the packet aside from a check that the length of the packet
(as indicated by the value of the length field, the
first four bytes of the packet) is 11 or more bytes.
If the value of the length value is less then 11
then an IOException is thrown.
Returns a byte array of a length equal to the length
of the received packet, or a byte array of length 0 when an
end of stream is encountered. If end of stream is encountered
after some, but not all bytes of a packet, are read then it
is considered an I/O error and an IOException is
thrown. The first byte of the packet is stored in element
0 of the byte array, the second in element 1,
and so on. The bytes in the byte array are laid out as per the
JDWP specification. That is, all fields in the packet
are in big endian order as per the JDWP specification.
This method may be invoked at any time. If another thread has
already initiated a
Connection.readPacket readPacket on this
connection then the invocation of this method will block until the
first operation is complete.
the packet read from the target VM
throws:
ClosedConnectionException - If the connection is closed, or another thread closesthe connection while the readPacket is in progress.
throws:
java.io.IOException - If the length of the packet (as indictaed by the first4 bytes) is less than 11 bytes, or an I/O error occurs. |
| writePacket | | abstract public void writePacket(byte pkt) throws IOException(Code) | | Writes a packet to the target VM.
Attempts to write, or send, a JDWP packet to the target VM.
A write operation only returns after writing the entire packet
to the target VM. Writing the entire packet does not mean
the entire packet has been transmitted to the target VM
but rather that all bytes have been written to the
transport service. A transport service based on a TCP/IP connection
may, for example, buffer some or all of the packet before
transmission on the network.
The byte array provided to this method should be laid out
as per the
JDWP specification. That is, all fields in the packet
are in big endian order. The first byte, that is element
pkt[0], is the first byte of the length field.
pkt[1] is the second byte of the length field,
and so on.
Writing a packet does not do any integrity checking on
the packet aside from checking the packet length. Checking
the packet length requires checking that the value of the
length field (as indicated by the first four bytes
of the packet) is 11 or greater. Consequently the length of
the byte array provided to this method, that is
pkt.length, must be 11 or more, and must be equal
or greater than the value of the length field. If the
length of the byte array is greater than the value of
the length field then all bytes from element
pkt[length] onwards are ignored. In other words,
any additional bytes that follow the packet in the byte
array are ignored and will not be transmitted to the target
VM.
A write operation may block or may complete immediately.
The exact circumstances when an operation blocks depends on
the transport service. In the case of a TCP/IP connection to
the target VM, the writePacket method may block if there is
network congestion or there is insufficient space to buffer
the packet in the underlying network system.
This method may be invoked at any time. If another thread has
already initiated a write operation upon this Connection then
a subsequent invocation of this method will block until the first
operation is complete.
Parameters:
pkt - The packet to write to the target VM.
throws:
ClosedConnectionException - If the connection is closed, or another thread closesthe connection while the write operation is in progress.
throws:
java.io.IOException - If an I/O error occurs.
throws:
IllegalArgumentException - If the value of the length field is invalid,or the byte array is of insufficient length. |
|
|