1 /* 2 * Copyright (c) 2003, 2013, Oracle and/or its affiliates. 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. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package com.sun.jdi.connect.spi; 27 28 import java.io.IOException; 29 import com.sun.jdi.connect.TransportTimeoutException; 30 31 /** 32 * A transport service for connections between a debugger and 33 * a target VM. 34 * 35 * <p> A transport service is a concrete subclass of this class 36 * that has a zero-argument constructor and implements the abstract 37 * methods specified below. It is the underlying service 38 * used by a {@link com.sun.jdi.connect.Transport} for 39 * connections between a debugger and a target VM. 40 * 41 * <p> A transport service is used to establish a connection 42 * between a debugger and a target VM, and to transport Java 43 * Debug Wire Protocol (JDWP) packets over an underlying 44 * communication protocol. In essence a transport service 45 * implementation binds JDWP (as specified in the 46 * <a href="../../../../../../../../../technotes/guides/jpda/jdwp-spec.html"> 47 * JDWP specification</a>) to an underlying communication 48 * protocol. A transport service implementation provides 49 * a reliable JDWP packet transportation service. JDWP 50 * packets are sent to and from the target VM without duplication 51 * or data loss. A transport service implementation may be 52 * based on an underlying communication protocol that is 53 * reliable or unreliable. If the underlying communication 54 * protocol is reliable then the transport service implementation 55 * may be relatively simple and may only need to transport JDWP 56 * packets as payloads of the underlying communication 57 * protocol. In the case of an unreliable communication 58 * protocol the transport service implementation may include 59 * additional protocol support in order to ensure that packets 60 * are not duplicated and that there is no data loss. The 61 * details of such protocols are specific to the implementation 62 * but may involve techniques such as the <i>positive 63 * acknowledgment with retransmission</i> technique used in 64 * protocols such as the Transmission Control Protocol (TCP) 65 * (see <a href="http://www.ietf.org/rfc/rfc0793.txt"> RFC 793 66 * </a>). 67 * 68 * <p> A transport service can be used to initiate a connection 69 * to a target VM. This is done by invoking the {@link #attach} 70 * method. Alternatively, a transport service can listen and 71 * accept connections initiated by a target VM. This is done 72 * by invoking the {@link #startListening(String)} method to 73 * put the transport into listen mode. Then the {@link #accept} 74 * method is used to accept a connection initiated by a 75 * target VM. 76 * 77 * @since 1.5 78 */ 79 80 @jdk.Exported 81 public abstract class TransportService { 82 83 /** 84 * Returns a name to identify the transport service. 85 * 86 * @return The name of the transport service 87 */ name()88 public abstract String name(); 89 90 /** 91 * Returns a description of the transport service. 92 * 93 * @return The description of the transport service 94 */ description()95 public abstract String description(); 96 97 /** 98 * The transport service capabilities. 99 */ 100 @jdk.Exported 101 public static abstract class Capabilities { 102 103 /** 104 * Tells whether or not this transport service can support 105 * multiple concurrent connections to a single address that 106 * it is listening on. 107 * 108 * @return <tt>true</tt> if, and only if, this transport 109 * service supports multiple connections. 110 */ supportsMultipleConnections()111 public abstract boolean supportsMultipleConnections(); 112 113 114 /** 115 * Tell whether or not this transport service supports a timeout 116 * when attaching to a target VM. 117 * 118 * @return <tt>true</tt> if, and only if, this transport 119 * service supports attaching with a timeout. 120 * 121 * @see #attach(String,long,long) 122 */ supportsAttachTimeout()123 public abstract boolean supportsAttachTimeout(); 124 125 /** 126 * Tell whether or not this transport service supports a 127 * timeout while waiting for a target VM to connect. 128 * 129 * @return <tt>true</tt> if, and only if, this transport 130 * service supports timeout while waiting for 131 * a target VM to connect. 132 * 133 * @see #accept(TransportService.ListenKey,long,long) 134 */ supportsAcceptTimeout()135 public abstract boolean supportsAcceptTimeout(); 136 137 /** 138 * Tells whether or not this transport service supports a 139 * timeout when handshaking with the target VM. 140 * 141 * @return <tt>true</tt> if, and only if, this transport 142 * service supports a timeout while handshaking 143 * with the target VM. 144 * 145 * @see #attach(String,long,long) 146 * @see #accept(TransportService.ListenKey,long,long) 147 */ supportsHandshakeTimeout()148 public abstract boolean supportsHandshakeTimeout(); 149 150 } 151 152 /** 153 * Returns the capabilities of the transport service. 154 * 155 * @return the transport service capabilities 156 */ capabilities()157 public abstract Capabilities capabilities(); 158 159 /** 160 * Attaches to the specified address. 161 * 162 * <p> Attaches to the specified address and returns a connection 163 * representing the bi-directional communication channel to the 164 * target VM. 165 * 166 * <p> Attaching to the target VM involves two steps: 167 * First, a connection is established to specified address. This 168 * is followed by a handshake to ensure that the connection is 169 * to a target VM. The handshake involves the exchange 170 * of a string <i>JDWP-Handshake</i> as specified in the <a 171 * href="../../../../../../../../../technotes/guides/jpda/jdwp-spec.html"> 172 * Java Debug Wire Protocol</a> specification. 173 * 174 * @param address 175 * The address of the target VM. 176 * 177 * @param attachTimeout 178 * If this transport service supports an attach timeout, 179 * and if <tt>attachTimeout</tt> is positive, then it specifies 180 * the timeout, in milliseconds (more or less), to use 181 * when attaching to the target VM. If the transport service 182 * does not support an attach timeout, or if <tt>attachTimeout</tt> 183 * is specified as zero then attach without any timeout. 184 * 185 * @param handshakeTimeout 186 * If this transport service supports a handshake timeout, 187 * and if <tt>handshakeTimeout</tt> is positive, then it 188 * specifies the timeout, in milliseconds (more or less), to 189 * use when handshaking with the target VM. The exact 190 * usage of the timeout are specific to the transport service. 191 * A transport service may, for example, use the handshake 192 * timeout as the inter-character timeout while waiting for 193 * the <i>JDWP-Handshake</i> message from the target VM. 194 * Alternatively, a transport service may, for example, 195 * use the handshakeTimeout as a timeout for the duration of the 196 * handshake exchange. 197 * If the transport service does not support a handshake 198 * timeout, or if <tt>handshakeTimeout</tt> is specified 199 * as zero then the handshake does not timeout if there 200 * isn't a response from the target VM. 201 * 202 * @return The Connection representing the bi-directional 203 * communication channel to the target VM. 204 * 205 * @throws TransportTimeoutException 206 * If a timeout occurs while establishing the connection. 207 * 208 * @throws IOException 209 * If an I/O error occurs (including a timeout when 210 * handshaking). 211 * 212 * @throws IllegalArgumentException 213 * If the address is invalid or the value of the 214 * attach timeout or handshake timeout is negative. 215 * 216 * @see TransportService.Capabilities#supportsAttachTimeout() 217 */ attach(String address, long attachTimeout, long handshakeTimeout)218 public abstract Connection attach(String address, long attachTimeout, 219 long handshakeTimeout) throws IOException; 220 221 /** 222 * A <i>listen key</i>. 223 * 224 * <p> A <tt>TransportService</tt> may listen on multiple, yet 225 * different, addresses at the same time. To uniquely identify 226 * each <tt>listener</tt> a listen key is created each time that 227 * {@link #startListening startListening} is called. The listen 228 * key is used in calls to the {@link #accept accept} method 229 * to accept inbound connections to that listener. A listen 230 * key is valid until it is used as an argument to {@link 231 * #stopListening stopListening} to stop the transport 232 * service from listening on an address. 233 */ 234 @jdk.Exported 235 public static abstract class ListenKey { 236 237 /** 238 * Returns a string representation of the listen key. 239 */ address()240 public abstract String address(); 241 } 242 243 /** 244 * Listens on the specified address for inbound connections. 245 * 246 * <p> This method starts the transport service listening on 247 * the specified address so that it can subsequently accept 248 * an inbound connection. It does not wait until an inbound 249 * connection is established. 250 * 251 * @param address 252 * The address to start listening for connections, 253 * or <tt>null</tt> to listen on an address chosen 254 * by the transport service. 255 * 256 * @return a listen key to be used in subsequent calls to be 257 * {@link #accept accept} or {@link #stopListening 258 * stopListening} methods. 259 * 260 * @throws IOException 261 * If an I/O error occurs. 262 * 263 * @throws IllegalArgumentException 264 * If the specific address is invalid 265 */ startListening(String address)266 public abstract ListenKey startListening(String address) throws IOException; 267 268 /** 269 * Listens on an address chosen by the transport service. 270 * 271 * <p> This convenience method works as if by invoking {@link 272 * #startListening(String) startListening(<tt>null</tt>)}. </p> 273 * 274 * @return a listen key to be used in subsequent calls to be 275 * {@link #accept accept} or {@link #stopListening 276 * stopListening} methods. 277 * 278 * @throws IOException 279 * If an I/O error occurs. 280 */ startListening()281 public abstract ListenKey startListening() throws IOException; 282 283 /** 284 * Stop listening for inbound connections. 285 * 286 * <p> Invoking this method while another thread is blocked 287 * in {@link #accept accept}, with the same listen key, 288 * waiting to accept a connection will cause that thread to 289 * throw an IOException. If the thread blocked in accept 290 * has already accepted a connection from a target VM and 291 * is in the process of handshaking with the target VM then 292 * invoking this method will not cause the thread to throw 293 * an exception. 294 * 295 * @param listenKey 296 * The listen key obtained from a previous call to {@link 297 * #startListening(String)} or {@link #startListening()}. 298 * 299 * @throws IllegalArgumentException 300 * If the listen key is invalid 301 * 302 * @throws IOException 303 * If an I/O error occurs. 304 */ stopListening(ListenKey listenKey)305 public abstract void stopListening(ListenKey listenKey) throws IOException; 306 307 /** 308 * Accept a connection from a target VM. 309 * 310 * <p> Waits (indefinitely or with timeout) to accept a connection 311 * from a target VM. Returns a connection representing the 312 * bi-directional communication channel to the target VM. 313 * 314 * <p> Accepting a connection from a target VM involves two 315 * steps. First, the transport service waits to accept 316 * the connection from the target VM. Once the connection is 317 * established a handshake is performed to ensure that the 318 * connection is indeed to a target VM. The handshake involves 319 * the exchange of a string <i>JDWP-Handshake</i> as specified 320 * in the <a 321 * href="../../../../../../../../../technotes/guides/jpda/jdwp-spec.html"> 322 * Java Debug Wire Protocol</a> specification. 323 * 324 * @param listenKey 325 * A listen key obtained from a previous call to {@link 326 * #startListening(String)} or {@link #startListening()}. 327 * 328 * @param acceptTimeout 329 * if this transport service supports an accept timeout, and 330 * if <tt>acceptTimeout</tt> is positive then block for up to 331 * <tt>acceptTimeout</tt> milliseconds, more or less, while waiting 332 * for the target VM to connect. 333 * If the transport service does not support an accept timeout 334 * or if <tt>acceptTimeout</tt> is zero then block indefinitely 335 * for a target VM to connect. 336 * 337 * @param handshakeTimeout 338 * If this transport service supports a handshake timeout, 339 * and if <tt>handshakeTimeout</tt> is positive, then it 340 * specifies the timeout, in milliseconds (more or less), to 341 * use when handshaking with the target VM. The exact 342 * usage of the timeout is specific to the transport service. 343 * A transport service may, for example, use the handshake 344 * timeout as the inter-character timeout while waiting for 345 * the <i>JDWP-Handshake</i> message from the target VM. 346 * Alternatively, a transport service may, for example, 347 * use the timeout as a timeout for the duration of the 348 * handshake exchange. 349 * If the transport service does not support a handshake 350 * timeout, of if <tt>handshakeTimeout</tt> is specified 351 * as zero then the handshake does not timeout if there 352 * isn't a response from the target VM. 353 * 354 * @return The Connection representing the bi-directional 355 * communication channel to the target VM. 356 * 357 * @throws TransportTimeoutException 358 * If a timeout occurs while waiting for a target VM 359 * to connect. 360 * 361 * @throws IOException 362 * If an I/O error occurs (including a timeout when 363 * handshaking). 364 * 365 * @throws IllegalArgumentException 366 * If the value of the acceptTimeout argument, or 367 * handshakeTimeout is negative, or an invalid listen key 368 * is provided. 369 * 370 * @throws IllegalStateException 371 * If {@link #stopListening stopListening} has already been 372 * called with this listen key and the transport service 373 * is no longer listening for inbound connections. 374 * 375 * @see TransportService.Capabilities#supportsAcceptTimeout() 376 */ accept(ListenKey listenKey, long acceptTimeout, long handshakeTimeout)377 public abstract Connection accept(ListenKey listenKey, long acceptTimeout, 378 long handshakeTimeout) throws IOException; 379 380 } 381