feat(jdk8): move files to new folder to avoid resources compiled.
This commit is contained in:
380
jdkSrc/jdk8/com/sun/jdi/connect/spi/TransportService.java
Normal file
380
jdkSrc/jdk8/com/sun/jdi/connect/spi/TransportService.java
Normal file
@@ -0,0 +1,380 @@
|
||||
/*
|
||||
* 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;
|
||||
|
||||
}
|
||||
Reference in New Issue
Block a user