J. Duke | 319a3b9 | 2007-12-01 00:00:00 +0000 | [diff] [blame^] | 1 | /* |
| 2 | * Copyright 2003-2006 Sun Microsystems, Inc. All Rights Reserved. |
| 3 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
| 4 | * |
| 5 | * This code is free software; you can redistribute it and/or modify it |
| 6 | * under the terms of the GNU General Public License version 2 only, as |
| 7 | * published by the Free Software Foundation. Sun designates this |
| 8 | * particular file as subject to the "Classpath" exception as provided |
| 9 | * by Sun in the LICENSE file that accompanied this code. |
| 10 | * |
| 11 | * This code is distributed in the hope that it will be useful, but WITHOUT |
| 12 | * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
| 13 | * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
| 14 | * version 2 for more details (a copy is included in the LICENSE file that |
| 15 | * accompanied this code). |
| 16 | * |
| 17 | * You should have received a copy of the GNU General Public License version |
| 18 | * 2 along with this work; if not, write to the Free Software Foundation, |
| 19 | * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
| 20 | * |
| 21 | * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, |
| 22 | * CA 95054 USA or visit www.sun.com if you need additional information or |
| 23 | * have any questions. |
| 24 | */ |
| 25 | |
| 26 | package com.sun.jdi.connect.spi; |
| 27 | |
| 28 | import java.io.IOException; |
| 29 | |
| 30 | /** |
| 31 | * A connection between a debugger and a target VM which it debugs. |
| 32 | * |
| 33 | * <p> A Connection represents a bi-directional communication channel |
| 34 | * between a debugger and a target VM. A Connection is created when |
| 35 | * {@link com.sun.jdi.connect.spi.TransportService TransportService} |
| 36 | * establishes a connection and successfully handshakes with a target |
| 37 | * VM. A TransportService implementation provides a reliable |
| 38 | * JDWP packet transportation service and consequently a Connection |
| 39 | * provides a reliable flow of JDWP packets between the debugger |
| 40 | * and the target VM. A Connection is stream oriented, that is, the |
| 41 | * JDWP packets written to a connection are read by the target VM |
| 42 | * in the order in which they were written. Similiarly packets written |
| 43 | * to a Connection by the target VM are read by the debugger in the |
| 44 | * order in which they were written. |
| 45 | * |
| 46 | * <p> A connection is either open or closed. It is open upon creation, |
| 47 | * and remains open until it is closed. Once closed, it remains closed, |
| 48 | * and any attempt to invoke an I/O operation upon it will cause a |
| 49 | * {@link ClosedConnectionException} to be thrown. A connection can |
| 50 | * be tested by invoking the {@link #isOpen isOpen} method. |
| 51 | * |
| 52 | * <p> A Connection is safe for access by multiple concurrent threads, |
| 53 | * although at most one thread may be reading and at most one thread may |
| 54 | * be writing at any given time. </p> |
| 55 | * |
| 56 | * @since 1.5 |
| 57 | */ |
| 58 | |
| 59 | public abstract class Connection { |
| 60 | |
| 61 | /** |
| 62 | * Reads a packet from the target VM. |
| 63 | * |
| 64 | * <p> Attempts to read a JDWP packet from the target VM. |
| 65 | * A read operation may block indefinitely and only returns |
| 66 | * when it reads all bytes of a packet, or in the case of a |
| 67 | * transport service that is based on a stream-oriented |
| 68 | * communication protocol, the end of stream is encountered. |
| 69 | * |
| 70 | * <p> Reading a packet does not do any integrity checking on |
| 71 | * the packet aside from a check that the length of the packet |
| 72 | * (as indicated by the value of the <tt>length</tt> field, the |
| 73 | * first four bytes of the packet) is 11 or more bytes. |
| 74 | * If the value of the <tt>length</tt> value is less then 11 |
| 75 | * then an <tt>IOException</tt> is thrown. |
| 76 | * |
| 77 | * <p> Returns a byte array of a length equal to the length |
| 78 | * of the received packet, or a byte array of length 0 when an |
| 79 | * end of stream is encountered. If end of stream is encountered |
| 80 | * after some, but not all bytes of a packet, are read then it |
| 81 | * is considered an I/O error and an <tt>IOException</tt> is |
| 82 | * thrown. The first byte of the packet is stored in element |
| 83 | * <tt>0</tt> of the byte array, the second in element <tt>1</tt>, |
| 84 | * and so on. The bytes in the byte array are laid out as per the |
| 85 | * <a href="../../../../../../../../../technotes/guides/jpda/jdwp-spec.html"> |
| 86 | * JDWP specification</a>. That is, all fields in the packet |
| 87 | * are in big endian order as per the JDWP specification. |
| 88 | * |
| 89 | * <p> This method may be invoked at any time. If another thread has |
| 90 | * already initiated a {@link #readPacket readPacket} on this |
| 91 | * connection then the invocation of this method will block until the |
| 92 | * first operation is complete. </p> |
| 93 | * |
| 94 | * @return the packet read from the target VM |
| 95 | * |
| 96 | * @throws ClosedConnectionException |
| 97 | * If the connection is closed, or another thread closes |
| 98 | * the connection while the readPacket is in progress. |
| 99 | * |
| 100 | * @throws java.io.IOException |
| 101 | * If the length of the packet (as indictaed by the first |
| 102 | * 4 bytes) is less than 11 bytes, or an I/O error occurs. |
| 103 | * |
| 104 | * |
| 105 | */ |
| 106 | public abstract byte[] readPacket() throws IOException; |
| 107 | |
| 108 | /** |
| 109 | * Writes a packet to the target VM. |
| 110 | * |
| 111 | * <p> Attempts to write, or send, a JDWP packet to the target VM. |
| 112 | * A write operation only returns after writing the entire packet |
| 113 | * to the target VM. Writing the entire packet does not mean |
| 114 | * the entire packet has been transmitted to the target VM |
| 115 | * but rather that all bytes have been written to the |
| 116 | * transport service. A transport service based on a TCP/IP connection |
| 117 | * may, for example, buffer some or all of the packet before |
| 118 | * transmission on the network. |
| 119 | * |
| 120 | * <p> The byte array provided to this method should be laid out |
| 121 | * as per the <a |
| 122 | * href="../../../../../../../../../technotes/guides/jpda/jdwp-spec.html"> |
| 123 | * JDWP specification</a>. That is, all fields in the packet |
| 124 | * are in big endian order. The first byte, that is element |
| 125 | * <tt>pkt[0]</tt>, is the first byte of the <tt>length</tt> field. |
| 126 | * <tt>pkt[1]</tt> is the second byte of the <tt>length</tt> field, |
| 127 | * and so on. |
| 128 | * |
| 129 | * <p> Writing a packet does not do any integrity checking on |
| 130 | * the packet aside from checking the packet length. Checking |
| 131 | * the packet length requires checking that the value of the |
| 132 | * <tt>length</tt> field (as indicated by the first four bytes |
| 133 | * of the packet) is 11 or greater. Consequently the length of |
| 134 | * the byte array provided to this method, that is |
| 135 | * <tt>pkt.length</tt>, must be 11 or more, and must be equal |
| 136 | * or greater than the value of the <tt>length</tt> field. If the |
| 137 | * length of the byte array is greater than the value of |
| 138 | * the <tt>length</tt> field then all bytes from element |
| 139 | * <tt>pkt[length]</tt> onwards are ignored. In other words, |
| 140 | * any additional bytes that follow the packet in the byte |
| 141 | * array are ignored and will not be transmitted to the target |
| 142 | * VM. |
| 143 | * |
| 144 | * <p> A write operation may block or may complete immediately. |
| 145 | * The exact circumstances when an operation blocks depends on |
| 146 | * the transport service. In the case of a TCP/IP connection to |
| 147 | * the target VM, the writePacket method may block if there is |
| 148 | * network congestion or there is insufficient space to buffer |
| 149 | * the packet in the underlying network system. |
| 150 | * |
| 151 | * <p> This method may be invoked at any time. If another thread has |
| 152 | * already initiated a write operation upon this Connection then |
| 153 | * a subsequent invocation of this method will block until the first |
| 154 | * operation is complete. </p> |
| 155 | * |
| 156 | * @param pkt |
| 157 | * The packet to write to the target VM. |
| 158 | * |
| 159 | * @throws ClosedConnectionException |
| 160 | * If the connection is closed, or another thread closes |
| 161 | * the connection while the write operation is in progress. |
| 162 | * |
| 163 | * @throws java.io.IOException |
| 164 | * If an I/O error occurs. |
| 165 | * |
| 166 | * @throws IllegalArgumentException |
| 167 | * If the value of the <tt>length</tt> field is invalid, |
| 168 | * or the byte array is of insufficient length. |
| 169 | */ |
| 170 | public abstract void writePacket(byte pkt[]) throws IOException; |
| 171 | |
| 172 | /** |
| 173 | * Closes this connection. |
| 174 | * |
| 175 | * <p> If the connection is already closed then invoking this method |
| 176 | * has no effect. After a connection is closed, any further attempt |
| 177 | * calls to {@link #readPacket readPacket} or {@link #writePacket |
| 178 | * writePacket} will throw a {@link ClosedConnectionException}. |
| 179 | * |
| 180 | * <p> Any thread currently blocked in an I/O operation ({@link |
| 181 | * #readPacket readPacket} or {@link #writePacket writePacket}) |
| 182 | * will throw a {@link ClosedConnectionException}). |
| 183 | * |
| 184 | * <p> This method may be invoked at any time. If some other thread has |
| 185 | * already invoked it, however, then another invocation will block until |
| 186 | * the first invocation is complete, after which it will return without |
| 187 | * effect. </p> |
| 188 | * |
| 189 | * @throws java.io.IOException |
| 190 | * If an I/O error occurs |
| 191 | */ |
| 192 | public abstract void close() throws IOException; |
| 193 | |
| 194 | /** |
| 195 | * Tells whether or not this connection is open. </p> |
| 196 | * |
| 197 | * @return <tt>true</tt> if, and only if, this connection is open |
| 198 | */ |
| 199 | public abstract boolean isOpen(); |
| 200 | } |