< prev index next >

src/jdk.jdi/share/classes/com/sun/jdi/connect/spi/TransportService.java

Print this page
rev 17275 : 8181417: Code cleanups in com.sun.jdi


   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 }
< prev index next >