001: /*
002: * Copyright 2003-2006 Sun Microsystems, Inc. All Rights Reserved.
003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004: *
005: * This code is free software; you can redistribute it and/or modify it
006: * under the terms of the GNU General Public License version 2 only, as
007: * published by the Free Software Foundation. Sun designates this
008: * particular file as subject to the "Classpath" exception as provided
009: * by Sun in the LICENSE file that accompanied this code.
010: *
011: * This code is distributed in the hope that it will be useful, but WITHOUT
012: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014: * version 2 for more details (a copy is included in the LICENSE file that
015: * accompanied this code).
016: *
017: * You should have received a copy of the GNU General Public License version
018: * 2 along with this work; if not, write to the Free Software Foundation,
019: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022: * CA 95054 USA or visit www.sun.com if you need additional information or
023: * have any questions.
024: */
025:
026: package com.sun.jdi.connect.spi;
027:
028: import java.io.IOException;
029: import com.sun.jdi.connect.TransportTimeoutException;
030:
031: /**
032: * A transport service for connections between a debugger and
033: * a target VM.
034: *
035: * <p> A transport service is a concrete subclass of this class
036: * that has a zero-argument constructor and implements the abstract
037: * methods specified below. It is the underlying service
038: * used by a {@link com.sun.jdi.connect.Transport} for
039: * connections between a debugger and a target VM.
040: *
041: * <p> A transport service is used to establish a connection
042: * between a debugger and a target VM, and to transport Java
043: * Debug Wire Protocol (JDWP) packets over an underlying
044: * communication protocol. In essence a transport service
045: * implementation binds JDWP (as specified in the
046: * <a href="../../../../../../../../../technotes/guides/jpda/jdwp-spec.html">
047: * JDWP specification</a>) to an underlying communication
048: * protocol. A transport service implementation provides
049: * a reliable JDWP packet transportation service. JDWP
050: * packets are sent to and from the target VM without duplication
051: * or data loss. A transport service implementation may be
052: * based on an underlying communication protocol that is
053: * reliable or unreliable. If the underlying communication
054: * protocol is reliable then the transport service implementation
055: * may be relatively simple and may only need to transport JDWP
056: * packets as payloads of the underlying communication
057: * protocol. In the case of an unreliable communication
058: * protocol the transport service implementation may include
059: * additional protocol support in order to ensure that packets
060: * are not duplicated and that there is no data loss. The
061: * details of such protocols are specific to the implementation
062: * but may involve techniques such as the <i>positive
063: * acknowledgment with retransmission</i> technique used in
064: * protocols such as the Transmission Control Protocol (TCP)
065: * (see <a href="http://www.ietf.org/rfc/rfc0793.txt"> RFC 793
066: * </a>).
067: *
068: * <p> A transport service can be used to initiate a connection
069: * to a target VM. This is done by invoking the {@link #attach}
070: * method. Alternatively, a transport service can listen and
071: * accept connections initiated by a target VM. This is done
072: * by invoking the {@link #startListening(String)} method to
073: * put the transport into listen mode. Then the {@link #accept}
074: * method is used to accept a connection initiated by a
075: * target VM.
076: *
077: * @since 1.5
078: */
079:
080: public abstract class TransportService {
081:
082: /**
083: * Returns a name to identify the transport service.
084: *
085: * @return The name of the transport service
086: */
087: public abstract String name();
088:
089: /**
090: * Returns a description of the transport service.
091: *
092: * @return The description of the transport service
093: */
094: public abstract String description();
095:
096: /**
097: * The transport service capabilities.
098: */
099: public static abstract class Capabilities {
100:
101: /**
102: * Tells whether or not this transport service can support
103: * multiple concurrent connections to a single address that
104: * it is listening on.
105: *
106: * @return <tt>true</tt> if, and only if, this transport
107: * service supports multiple connections.
108: */
109: public abstract boolean supportsMultipleConnections();
110:
111: /**
112: * Tell whether or not this transport service supports a timeout
113: * when attaching to a target VM.
114: *
115: * @return <tt>true</tt> if, and only if, this transport
116: * service supports attaching with a timeout.
117: *
118: * @see #attach(String,long,long)
119: */
120: public abstract boolean supportsAttachTimeout();
121:
122: /**
123: * Tell whether or not this transport service supports a
124: * timeout while waiting for a target VM to connect.
125: *
126: * @return <tt>true</tt> if, and only if, this transport
127: * service supports timeout while waiting for
128: * a target VM to connect.
129: *
130: * @see #accept(TransportService.ListenKey,long,long)
131: */
132: public abstract boolean supportsAcceptTimeout();
133:
134: /**
135: * Tells whether or not this transport service supports a
136: * timeout when handshaking with the target VM.
137: *
138: * @return <tt>true</tt> if, and only if, this transport
139: * service supports a timeout while handshaking
140: * with the target VM.
141: *
142: * @see #attach(String,long,long)
143: * @see #accept(TransportService.ListenKey,long,long)
144: */
145: public abstract boolean supportsHandshakeTimeout();
146:
147: }
148:
149: /**
150: * Returns the capabilities of the transport service.
151: *
152: * @return the transport service capabilities
153: */
154: public abstract Capabilities capabilities();
155:
156: /**
157: * Attaches to the specified address.
158: *
159: * <p> Attaches to the specified address and returns a connection
160: * representing the bi-directional communication channel to the
161: * target VM.
162: *
163: * <p> Attaching to the target VM involves two steps:
164: * First, a connection is established to specified address. This
165: * is followed by a handshake to ensure that the connection is
166: * to a target VM. The handshake involves the exchange
167: * of a string <i>JDWP-Handshake</i> as specified in the <a
168: * href="../../../../../../../../../technotes/guides/jpda/jdwp-spec.html">
169: * Java Debug Wire Protocol</a> specification.
170: *
171: * @param address
172: * The address of the target VM.
173: *
174: * @param attachTimeout
175: * If this transport service supports an attach timeout,
176: * and if <tt>attachTimeout</tt> is positive, then it specifies
177: * the timeout, in milliseconds (more or less), to use
178: * when attaching to the target VM. If the transport service
179: * does not support an attach timeout, or if <tt>attachTimeout</tt>
180: * is specified as zero then attach without any timeout.
181: *
182: * @param handshakeTimeout
183: * If this transport service supports a handshake timeout,
184: * and if <tt>handshakeTimeout</tt> is positive, then it
185: * specifies the timeout, in milliseconds (more or less), to
186: * use when handshaking with the target VM. The exact
187: * usage of the timeout are specific to the transport service.
188: * A transport service may, for example, use the handshake
189: * timeout as the inter-character timeout while waiting for
190: * the <i>JDWP-Handshake</i> message from the target VM.
191: * Alternatively, a transport service may, for example,
192: * use the handshakeTimeout as a timeout for the duration of the
193: * handshake exchange.
194: * If the transport service does not support a handshake
195: * timeout, or if <tt>handshakeTimeout</tt> is specified
196: * as zero then the handshake does not timeout if there
197: * isn't a response from the target VM.
198: *
199: * @return The Connection representing the bi-directional
200: * communication channel to the target VM.
201: *
202: * @throws TransportTimeoutException
203: * If a timeout occurs while establishing the connection.
204: *
205: * @throws IOException
206: * If an I/O error occurs (including a timeout when
207: * handshaking).
208: *
209: * @throws IllegalArgumentException
210: * If the address is invalid or the value of the
211: * attach timeout or handshake timeout is negative.
212: *
213: * @see TransportService.Capabilities#supportsAttachTimeout()
214: */
215: public abstract Connection attach(String address,
216: long attachTimeout, long handshakeTimeout)
217: throws IOException;
218:
219: /**
220: * A <i>listen key</i>.
221: *
222: * <p> A <tt>TransportService</tt> may listen on multiple, yet
223: * different, addresses at the same time. To uniquely identify
224: * each <tt>listener</tt> a listen key is created each time that
225: * {@link #startListening startListening} is called. The listen
226: * key is used in calls to the {@link #accept accept} method
227: * to accept inbound connections to that listener. A listen
228: * key is valid until it is used as an argument to {@link
229: * #stopListening stopListening} to stop the transport
230: * service from listening on an address.
231: */
232: public static abstract class ListenKey {
233:
234: /**
235: * Returns a string representation of the listen key.
236: */
237: public abstract String address();
238: }
239:
240: /**
241: * Listens on the specified address for inbound connections.
242: *
243: * <p> This method starts the transport service listening on
244: * the specified address so that it can subsequently accept
245: * an inbound connection. It does not wait until an inbound
246: * connection is established.
247: *
248: * @param address
249: * The address to start listening for connections,
250: * or <tt>null</tt> to listen on an address choosen
251: * by the transport service.
252: *
253: * @return a listen key to be used in subsequent calls to be
254: * {@link #accept accept} or {@link #stopListening
255: * stopListening} methods.
256: *
257: * @throws IOException
258: * If an I/O error occurs.
259: *
260: * @throws IllegalArgumentException
261: * If the specific address is invalid
262: */
263: public abstract ListenKey startListening(String address)
264: throws IOException;
265:
266: /**
267: * Listens on an address choosen by the transport service.
268: *
269: * <p> This convenience method works as if by invoking {@link
270: * #startListening(String) startListening(<tt>null</tt>)}. </p>
271: *
272: * @return a listen key to be used in subsequent calls to be
273: * {@link #accept accept} or {@link #stopListening
274: * stopListening} methods.
275: *
276: * @throws IOException
277: * If an I/O error occurs.
278: */
279: public abstract ListenKey startListening() throws IOException;
280:
281: /**
282: * Stop listening for inbound connections.
283: *
284: * <p> Invoking this method while another thread is blocked
285: * in {@link #accept accept}, with the same listen key,
286: * waiting to accept a connection will cause that thread to
287: * throw an IOException. If the thread blocked in accept
288: * has already accepted a connection from a target VM and
289: * is in the process of handshaking with the target VM then
290: * invoking this method will not cause the thread to throw
291: * an exception.
292: *
293: * @param listenKey
294: * The listen key obtained from a previous call to {@link
295: * #startListening(String)} or {@link #startListening()}.
296: *
297: * @throws IllegalArgumentException
298: * If the listen key is invalid
299: *
300: * @throws IOException
301: * If an I/O error occurs.
302: */
303: public abstract void stopListening(ListenKey listenKey)
304: throws IOException;
305:
306: /**
307: * Accept a connection from a target VM.
308: *
309: * <p> Waits (indefinitely or with timeout) to accept a connection
310: * from a target VM. Returns a connection representing the
311: * bi-directional communication channel to the target VM.
312: *
313: * <p> Accepting a connection from a target VM involves two
314: * steps. First, the transport service waits to accept
315: * the connection from the target VM. Once the connection is
316: * established a handshake is performed to ensure that the
317: * connection is indeed to a target VM. The handshake involves
318: * the exchange of a string <i>JDWP-Handshake</i> as specified
319: * in the <a
320: * href="../../../../../../../../../technotes/guides/jpda/jdwp-spec.html">
321: * Java Debug Wire Protocol</a> specification.
322: *
323: * @param listenKey
324: * A listen key obtained from a previous call to {@link
325: * #startListening(String)} or {@link #startListening()}.
326: *
327: * @param acceptTimeout
328: * if this transport service supports an accept timeout, and
329: * if <tt>acceptTimeout</tt> is positive then block for up to
330: * <tt>acceptTimeout</tt> milliseconds, more or less, while waiting
331: * for the target VM to connect.
332: * If the transport service does not support an accept timeout
333: * or if <tt>acceptTimeout</tt> is zero then block indefinitely
334: * for a target VM to connect.
335: *
336: * @param handshakeTimeout
337: * If this transport service supports a handshake timeout,
338: * and if <tt>handshakeTimeout</tt> is positive, then it
339: * specifies the timeout, in milliseconds (more or less), to
340: * use when handshaking with the target VM. The exact
341: * usage of the timeout is specific to the transport service.
342: * A transport service may, for example, use the handshake
343: * timeout as the inter-character timeout while waiting for
344: * the <i>JDWP-Handshake</i> message from the target VM.
345: * Alternatively, a transport service may, for example,
346: * use the timeout as a timeout for the duration of the
347: * handshake exchange.
348: * If the transport service does not support a handshake
349: * timeout, of if <tt>handshakeTimeout</tt> is specified
350: * as zero then the handshake does not timeout if there
351: * isn't a response from the target VM.
352: *
353: * @return The Connection representing the bi-directional
354: * communication channel to the target VM.
355: *
356: * @throws TransportTimeoutException
357: * If a timeout occurs while waiting for a target VM
358: * to connect.
359: *
360: * @throws IOException
361: * If an I/O error occurs (including a timeout when
362: * handshaking).
363: *
364: * @throws IllegalArgumentException
365: * If the value of the acceptTimeout argument, or
366: * handshakeTimeout is negative, or an invalid listen key
367: * is provided.
368: *
369: * @throws IllegalStateException
370: * If {@link #stopListening stopListening} has already been
371: * called with this listen key and the transport service
372: * is no longer listening for inbound connections.
373: *
374: * @see TransportService.Capabilities#supportsAcceptTimeout()
375: */
376: public abstract Connection accept(ListenKey listenKey,
377: long acceptTimeout, long handshakeTimeout)
378: throws IOException;
379:
380: }
|