/*
* Copyright (c) 2003, 2006, 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
*/
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.
*/
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.
*/
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 choosen
* 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 choosen 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;
}