| /* |
| * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved. |
| * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
| * |
| * This code is free software; you can redistribute it and/or modify it |
| * under the terms of the GNU General Public License version 2 only, as |
| * published by the Free Software Foundation. Oracle designates this |
| * particular file as subject to the "Classpath" exception as provided |
| * by Oracle in the LICENSE file that accompanied this code. |
| * |
| * This code is distributed in the hope that it will be useful, but WITHOUT |
| * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
| * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
| * version 2 for more details (a copy is included in the LICENSE file that |
| * accompanied this code). |
| * |
| * You should have received a copy of the GNU General Public License version |
| * 2 along with this work; if not, write to the Free Software Foundation, |
| * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
| * |
| * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
| * or visit www.oracle.com if you need additional information or have any |
| * questions. |
| */ |
| |
| package com.sun.jdi.connect.spi; |
| |
| import java.io.IOException; |
| import com.sun.jdi.connect.TransportTimeoutException; |
| |
| /** |
| * A transport service for connections between a debugger and |
| * a target VM. |
| * |
| * <p> A transport service is a concrete subclass of this class |
| * that has a zero-argument constructor and implements the abstract |
| * methods specified below. It is the underlying service |
| * used by a {@link com.sun.jdi.connect.Transport} for |
| * connections between a debugger and a target VM. |
| * |
| * <p> A transport service is used to establish a connection |
| * between a debugger and a target VM, and to transport Java |
| * Debug Wire Protocol (JDWP) packets over an underlying |
| * communication protocol. In essence a transport service |
| * implementation binds JDWP (as specified in the |
| * <a href="../../../../../../../../../technotes/guides/jpda/jdwp-spec.html"> |
| * JDWP specification</a>) to an underlying communication |
| * protocol. A transport service implementation provides |
| * a reliable JDWP packet transportation service. JDWP |
| * packets are sent to and from the target VM without duplication |
| * or data loss. A transport service implementation may be |
| * based on an underlying communication protocol that is |
| * reliable or unreliable. If the underlying communication |
| * protocol is reliable then the transport service implementation |
| * may be relatively simple and may only need to transport JDWP |
| * packets as payloads of the underlying communication |
| * protocol. In the case of an unreliable communication |
| * protocol the transport service implementation may include |
| * additional protocol support in order to ensure that packets |
| * are not duplicated and that there is no data loss. The |
| * details of such protocols are specific to the implementation |
| * but may involve techniques such as the <i>positive |
| * acknowledgment with retransmission</i> technique used in |
| * protocols such as the Transmission Control Protocol (TCP) |
| * (see <a href="http://www.ietf.org/rfc/rfc0793.txt"> RFC 793 |
| * </a>). |
| * |
| * <p> A transport service can be used to initiate a connection |
| * to a target VM. This is done by invoking the {@link #attach} |
| * method. Alternatively, a transport service can listen and |
| * accept connections initiated by a target VM. This is done |
| * by invoking the {@link #startListening(String)} method to |
| * put the transport into listen mode. Then the {@link #accept} |
| * method is used to accept a connection initiated by a |
| * target VM. |
| * |
| * @since 1.5 |
| */ |
| |
| @jdk.Exported |
| public abstract class TransportService { |
| |
| /** |
| * Returns a name to identify the transport service. |
| * |
| * @return The name of the transport service |
| */ |
| public abstract String name(); |
| |
| /** |
| * Returns a description of the transport service. |
| * |
| * @return The description of the transport service |
| */ |
| public abstract String description(); |
| |
| /** |
| * The transport service capabilities. |
| */ |
| @jdk.Exported |
| public static abstract class Capabilities { |
| |
| /** |
| * Tells whether or not this transport service can support |
| * multiple concurrent connections to a single address that |
| * it is listening on. |
| * |
| * @return <tt>true</tt> if, and only if, this transport |
| * service supports multiple connections. |
| */ |
| public abstract boolean supportsMultipleConnections(); |
| |
| |
| /** |
| * Tell whether or not this transport service supports a timeout |
| * when attaching to a target VM. |
| * |
| * @return <tt>true</tt> if, and only if, this transport |
| * service supports attaching with a timeout. |
| * |
| * @see #attach(String,long,long) |
| */ |
| public abstract boolean supportsAttachTimeout(); |
| |
| /** |
| * Tell whether or not this transport service supports a |
| * timeout while waiting for a target VM to connect. |
| * |
| * @return <tt>true</tt> if, and only if, this transport |
| * service supports timeout while waiting for |
| * a target VM to connect. |
| * |
| * @see #accept(TransportService.ListenKey,long,long) |
| */ |
| public abstract boolean supportsAcceptTimeout(); |
| |
| /** |
| * Tells whether or not this transport service supports a |
| * timeout when handshaking with the target VM. |
| * |
| * @return <tt>true</tt> if, and only if, this transport |
| * service supports a timeout while handshaking |
| * with the target VM. |
| * |
| * @see #attach(String,long,long) |
| * @see #accept(TransportService.ListenKey,long,long) |
| */ |
| public abstract boolean supportsHandshakeTimeout(); |
| |
| } |
| |
| /** |
| * Returns the capabilities of the transport service. |
| * |
| * @return the transport service capabilities |
| */ |
| public abstract Capabilities capabilities(); |
| |
| /** |
| * Attaches to the specified address. |
| * |
| * <p> Attaches to the specified address and returns a connection |
| * representing the bi-directional communication channel to the |
| * target VM. |
| * |
| * <p> Attaching to the target VM involves two steps: |
| * First, a connection is established to specified address. This |
| * is followed by a handshake to ensure that the connection is |
| * to a target VM. The handshake involves the exchange |
| * of a string <i>JDWP-Handshake</i> as specified in the <a |
| * href="../../../../../../../../../technotes/guides/jpda/jdwp-spec.html"> |
| * Java Debug Wire Protocol</a> specification. |
| * |
| * @param address |
| * The address of the target VM. |
| * |
| * @param attachTimeout |
| * If this transport service supports an attach timeout, |
| * and if <tt>attachTimeout</tt> is positive, then it specifies |
| * the timeout, in milliseconds (more or less), to use |
| * when attaching to the target VM. If the transport service |
| * does not support an attach timeout, or if <tt>attachTimeout</tt> |
| * is specified as zero then attach without any timeout. |
| * |
| * @param handshakeTimeout |
| * If this transport service supports a handshake timeout, |
| * and if <tt>handshakeTimeout</tt> is positive, then it |
| * specifies the timeout, in milliseconds (more or less), to |
| * use when handshaking with the target VM. The exact |
| * usage of the timeout are specific to the transport service. |
| * A transport service may, for example, use the handshake |
| * timeout as the inter-character timeout while waiting for |
| * the <i>JDWP-Handshake</i> message from the target VM. |
| * Alternatively, a transport service may, for example, |
| * use the handshakeTimeout as a timeout for the duration of the |
| * handshake exchange. |
| * If the transport service does not support a handshake |
| * timeout, or if <tt>handshakeTimeout</tt> is specified |
| * as zero then the handshake does not timeout if there |
| * isn't a response from the target VM. |
| * |
| * @return The Connection representing the bi-directional |
| * communication channel to the target VM. |
| * |
| * @throws TransportTimeoutException |
| * If a timeout occurs while establishing the connection. |
| * |
| * @throws IOException |
| * If an I/O error occurs (including a timeout when |
| * handshaking). |
| * |
| * @throws IllegalArgumentException |
| * If the address is invalid or the value of the |
| * attach timeout or handshake timeout is negative. |
| * |
| * @see TransportService.Capabilities#supportsAttachTimeout() |
| */ |
| public abstract Connection attach(String address, long attachTimeout, |
| long handshakeTimeout) throws IOException; |
| |
| /** |
| * A <i>listen key</i>. |
| * |
| * <p> A <tt>TransportService</tt> may listen on multiple, yet |
| * different, addresses at the same time. To uniquely identify |
| * each <tt>listener</tt> a listen key is created each time that |
| * {@link #startListening startListening} is called. The listen |
| * key is used in calls to the {@link #accept accept} method |
| * to accept inbound connections to that listener. A listen |
| * key is valid until it is used as an argument to {@link |
| * #stopListening stopListening} to stop the transport |
| * service from listening on an address. |
| */ |
| @jdk.Exported |
| public static abstract class ListenKey { |
| |
| /** |
| * Returns a string representation of the listen key. |
| */ |
| public abstract String address(); |
| } |
| |
| /** |
| * Listens on the specified address for inbound connections. |
| * |
| * <p> This method starts the transport service listening on |
| * the specified address so that it can subsequently accept |
| * an inbound connection. It does not wait until an inbound |
| * connection is established. |
| * |
| * @param address |
| * The address to start listening for connections, |
| * or <tt>null</tt> to listen on an address chosen |
| * by the transport service. |
| * |
| * @return a listen key to be used in subsequent calls to be |
| * {@link #accept accept} or {@link #stopListening |
| * stopListening} methods. |
| * |
| * @throws IOException |
| * If an I/O error occurs. |
| * |
| * @throws IllegalArgumentException |
| * If the specific address is invalid |
| */ |
| public abstract ListenKey startListening(String address) throws IOException; |
| |
| /** |
| * Listens on an address chosen by the transport service. |
| * |
| * <p> This convenience method works as if by invoking {@link |
| * #startListening(String) startListening(<tt>null</tt>)}. </p> |
| * |
| * @return a listen key to be used in subsequent calls to be |
| * {@link #accept accept} or {@link #stopListening |
| * stopListening} methods. |
| * |
| * @throws IOException |
| * If an I/O error occurs. |
| */ |
| public abstract ListenKey startListening() throws IOException; |
| |
| /** |
| * Stop listening for inbound connections. |
| * |
| * <p> Invoking this method while another thread is blocked |
| * in {@link #accept accept}, with the same listen key, |
| * waiting to accept a connection will cause that thread to |
| * throw an IOException. If the thread blocked in accept |
| * has already accepted a connection from a target VM and |
| * is in the process of handshaking with the target VM then |
| * invoking this method will not cause the thread to throw |
| * an exception. |
| * |
| * @param listenKey |
| * The listen key obtained from a previous call to {@link |
| * #startListening(String)} or {@link #startListening()}. |
| * |
| * @throws IllegalArgumentException |
| * If the listen key is invalid |
| * |
| * @throws IOException |
| * If an I/O error occurs. |
| */ |
| public abstract void stopListening(ListenKey listenKey) throws IOException; |
| |
| /** |
| * Accept a connection from a target VM. |
| * |
| * <p> Waits (indefinitely or with timeout) to accept a connection |
| * from a target VM. Returns a connection representing the |
| * bi-directional communication channel to the target VM. |
| * |
| * <p> Accepting a connection from a target VM involves two |
| * steps. First, the transport service waits to accept |
| * the connection from the target VM. Once the connection is |
| * established a handshake is performed to ensure that the |
| * connection is indeed to a target VM. The handshake involves |
| * the exchange of a string <i>JDWP-Handshake</i> as specified |
| * in the <a |
| * href="../../../../../../../../../technotes/guides/jpda/jdwp-spec.html"> |
| * Java Debug Wire Protocol</a> specification. |
| * |
| * @param listenKey |
| * A listen key obtained from a previous call to {@link |
| * #startListening(String)} or {@link #startListening()}. |
| * |
| * @param acceptTimeout |
| * if this transport service supports an accept timeout, and |
| * if <tt>acceptTimeout</tt> is positive then block for up to |
| * <tt>acceptTimeout</tt> milliseconds, more or less, while waiting |
| * for the target VM to connect. |
| * If the transport service does not support an accept timeout |
| * or if <tt>acceptTimeout</tt> is zero then block indefinitely |
| * for a target VM to connect. |
| * |
| * @param handshakeTimeout |
| * If this transport service supports a handshake timeout, |
| * and if <tt>handshakeTimeout</tt> is positive, then it |
| * specifies the timeout, in milliseconds (more or less), to |
| * use when handshaking with the target VM. The exact |
| * usage of the timeout is specific to the transport service. |
| * A transport service may, for example, use the handshake |
| * timeout as the inter-character timeout while waiting for |
| * the <i>JDWP-Handshake</i> message from the target VM. |
| * Alternatively, a transport service may, for example, |
| * use the timeout as a timeout for the duration of the |
| * handshake exchange. |
| * If the transport service does not support a handshake |
| * timeout, of if <tt>handshakeTimeout</tt> is specified |
| * as zero then the handshake does not timeout if there |
| * isn't a response from the target VM. |
| * |
| * @return The Connection representing the bi-directional |
| * communication channel to the target VM. |
| * |
| * @throws TransportTimeoutException |
| * If a timeout occurs while waiting for a target VM |
| * to connect. |
| * |
| * @throws IOException |
| * If an I/O error occurs (including a timeout when |
| * handshaking). |
| * |
| * @throws IllegalArgumentException |
| * If the value of the acceptTimeout argument, or |
| * handshakeTimeout is negative, or an invalid listen key |
| * is provided. |
| * |
| * @throws IllegalStateException |
| * If {@link #stopListening stopListening} has already been |
| * called with this listen key and the transport service |
| * is no longer listening for inbound connections. |
| * |
| * @see TransportService.Capabilities#supportsAcceptTimeout() |
| */ |
| public abstract Connection accept(ListenKey listenKey, long acceptTimeout, |
| long handshakeTimeout) throws IOException; |
| |
| } |
