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
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 public abstract class TransportService {
81
82 /**
83 * Returns a name to identify the transport service.
84 *
85 * @return The name of the transport service
86 */
87 public abstract String name();
88
89 /**
90 * Returns a description of the transport service.
91 *
92 * @return The description of the transport service
93 */
94 public abstract String description();
95
96 /**
97 * The transport service capabilities.
98 */
99 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 {@code true} if, and only if, this transport
107 * service supports multiple connections.
108 */
109 public abstract boolean supportsMultipleConnections();
110
111
112 /**
113 * Tell whether or not this transport service supports a timeout
114 * when attaching to a target VM.
115 *
116 * @return {@code true} if, and only if, this transport
117 * service supports attaching with a timeout.
118 *
119 * @see #attach(String,long,long)
120 */
121 public abstract boolean supportsAttachTimeout();
122
123 /**
124 * Tell whether or not this transport service supports a
125 * timeout while waiting for a target VM to connect.
126 *
127 * @return {@code true} if, and only if, this transport
128 * service supports timeout while waiting for
129 * a target VM to connect.
130 *
131 * @see #accept(TransportService.ListenKey,long,long)
132 */
133 public abstract boolean supportsAcceptTimeout();
134
135 /**
136 * Tells whether or not this transport service supports a
137 * timeout when handshaking with the target VM.
138 *
139 * @return {@code true} if, and only if, this transport
140 * service supports a timeout while handshaking
141 * with the target VM.
142 *
143 * @see #attach(String,long,long)
144 * @see #accept(TransportService.ListenKey,long,long)
145 */
146 public abstract boolean supportsHandshakeTimeout();
147
148 }
149
150 /**
151 * Returns the capabilities of the transport service.
152 *
153 * @return the transport service capabilities
154 */
155 public abstract Capabilities capabilities();
156
157 /**
158 * Attaches to the specified address.
159 *
160 * <p> Attaches to the specified address and returns a connection
161 * representing the bi-directional communication channel to the
162 * target VM.
163 *
164 * <p> Attaching to the target VM involves two steps:
165 * First, a connection is established to specified address. This
166 * is followed by a handshake to ensure that the connection is
167 * to a target VM. The handshake involves the exchange
356 * to connect.
357 *
358 * @throws IOException
359 * If an I/O error occurs (including a timeout when
360 * handshaking).
361 *
362 * @throws IllegalArgumentException
363 * If the value of the acceptTimeout argument, or
364 * handshakeTimeout is negative, or an invalid listen key
365 * is provided.
366 *
367 * @throws IllegalStateException
368 * If {@link #stopListening stopListening} has already been
369 * called with this listen key and the transport service
370 * is no longer listening for inbound connections.
371 *
372 * @see TransportService.Capabilities#supportsAcceptTimeout()
373 */
374 public abstract Connection accept(ListenKey listenKey, long acceptTimeout,
375 long handshakeTimeout) throws IOException;
376
377 }
|
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
30 import com.sun.jdi.connect.TransportTimeoutException;
31
32 /**
33 * A transport service for connections between a debugger and
34 * a target VM.
35 *
36 * <p> A transport service is a concrete subclass of this class
37 * that has a zero-argument constructor and implements the abstract
38 * methods specified below. It is the underlying service
39 * used by a {@link com.sun.jdi.connect.Transport} for
40 * connections between a debugger and a target VM.
41 *
42 * <p> A transport service is used to establish a connection
43 * between a debugger and a target VM, and to transport Java
44 * Debug Wire Protocol (JDWP) packets over an underlying
45 * communication protocol. In essence a transport service
46 * implementation binds JDWP (as specified in the
47 * <a href="../../../../../../../../../technotes/guides/jpda/jdwp-spec.html">
48 * JDWP specification</a>) to an underlying communication
49 * protocol. A transport service implementation provides
60 * additional protocol support in order to ensure that packets
61 * are not duplicated and that there is no data loss. The
62 * details of such protocols are specific to the implementation
63 * but may involve techniques such as the <i>positive
64 * acknowledgment with retransmission</i> technique used in
65 * protocols such as the Transmission Control Protocol (TCP)
66 * (see <a href="http://www.ietf.org/rfc/rfc0793.txt"> RFC 793
67 * </a>).
68 *
69 * <p> A transport service can be used to initiate a connection
70 * to a target VM. This is done by invoking the {@link #attach}
71 * method. Alternatively, a transport service can listen and
72 * accept connections initiated by a target VM. This is done
73 * by invoking the {@link #startListening(String)} method to
74 * put the transport into listen mode. Then the {@link #accept}
75 * method is used to accept a connection initiated by a
76 * target VM.
77 *
78 * @since 1.5
79 */
80 public abstract class TransportService {
81
82 /**
83 * Returns a name to identify the transport service.
84 *
85 * @return The name of the transport service
86 */
87 public abstract String name();
88
89 /**
90 * Returns a description of the transport service.
91 *
92 * @return The description of the transport service
93 */
94 public abstract String description();
95
96 /**
97 * The transport service capabilities.
98 */
99 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 {@code true} 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 {@code true} 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 {@code true} 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 {@code true} 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 * Returns the capabilities of the transport service.
150 *
151 * @return the transport service capabilities
152 */
153 public abstract Capabilities capabilities();
154
155 /**
156 * Attaches to the specified address.
157 *
158 * <p> Attaches to the specified address and returns a connection
159 * representing the bi-directional communication channel to the
160 * target VM.
161 *
162 * <p> Attaching to the target VM involves two steps:
163 * First, a connection is established to specified address. This
164 * is followed by a handshake to ensure that the connection is
165 * to a target VM. The handshake involves the exchange
354 * to connect.
355 *
356 * @throws IOException
357 * If an I/O error occurs (including a timeout when
358 * handshaking).
359 *
360 * @throws IllegalArgumentException
361 * If the value of the acceptTimeout argument, or
362 * handshakeTimeout is negative, or an invalid listen key
363 * is provided.
364 *
365 * @throws IllegalStateException
366 * If {@link #stopListening stopListening} has already been
367 * called with this listen key and the transport service
368 * is no longer listening for inbound connections.
369 *
370 * @see TransportService.Capabilities#supportsAcceptTimeout()
371 */
372 public abstract Connection accept(ListenKey listenKey, long acceptTimeout,
373 long handshakeTimeout) throws IOException;
374 }
|