1 /*
   2  * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   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 /**
  31  * A connection between a debugger and a target VM which it debugs.
  32  *
  33  * <p> A Connection represents a bi-directional communication channel
  34  * between a debugger and a target VM. A Connection is created when
  35  * {@link com.sun.jdi.connect.spi.TransportService TransportService}
  36  * establishes a connection and successfully handshakes with a target
  37  * VM. A TransportService implementation provides a reliable
  38  * JDWP packet transportation service and consequently a Connection
  39  * provides a reliable flow of JDWP packets between the debugger
  40  * and the target VM. A Connection is stream oriented, that is, the
  41  * JDWP packets written to a connection are read by the target VM
  42  * in the order in which they were written. Similiarly packets written
  43  * to a Connection by the target VM are read by the debugger in the
  44  * order in which they were written.
  45  *
  46  * <p> A connection is either open or closed. It is open upon creation,
  47  * and remains open until it is closed. Once closed, it remains closed,
  48  * and any attempt to invoke an I/O operation upon it will cause a
  49  * {@link ClosedConnectionException} to be thrown. A connection can
  50  * be tested by invoking the {@link #isOpen isOpen} method.
  51  *
  52  * <p> A Connection is safe for access by multiple concurrent threads,
  53  * although at most one thread may be reading and at most one thread may
  54  * be writing at any given time.
  55  *
  56  * @since 1.5
  57  */
  58 
  59 public abstract class Connection {
  60 
  61     /**
  62      * Reads a packet from the target VM.
  63      *
  64      * <p> Attempts to read a JDWP packet from the target VM.
  65      * A read operation may block indefinitely and only returns
  66      * when it reads all bytes of a packet, or in the case of a
  67      * transport service that is based on a stream-oriented
  68      * communication protocol, the end of stream is encountered.
  69      *
  70      * <p> Reading a packet does not do any integrity checking on
  71      * the packet aside from a check that the length of the packet
  72      * (as indicated by the value of the {@code length} field, the
  73      * first four bytes of the packet) is 11 or more bytes.
  74      * If the value of the {@code length} value is less then 11
  75      * then an {@code IOException} is thrown.
  76      *
  77      * <p> Returns a byte array of a length equal to the length
  78      * of the received packet, or a byte array of length 0 when an

   1 /*
   2  * Copyright (c) 2003, 2017, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   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 /**
  31  * A connection between a debugger and a target VM which it debugs.
  32  *
  33  * <p> A Connection represents a bi-directional communication channel
  34  * between a debugger and a target VM. A Connection is created when
  35  * {@link TransportService TransportService}
  36  * establishes a connection and successfully handshakes with a target
  37  * VM. A TransportService implementation provides a reliable
  38  * JDWP packet transportation service and consequently a Connection
  39  * provides a reliable flow of JDWP packets between the debugger
  40  * and the target VM. A Connection is stream oriented, that is, the
  41  * JDWP packets written to a connection are read by the target VM
  42  * in the order in which they were written. Similarly packets written
  43  * to a Connection by the target VM are read by the debugger in the
  44  * order in which they were written.
  45  *
  46  * <p> A connection is either open or closed. It is open upon creation,
  47  * and remains open until it is closed. Once closed, it remains closed,
  48  * and any attempt to invoke an I/O operation upon it will cause a
  49  * {@link ClosedConnectionException} to be thrown. A connection can
  50  * be tested by invoking the {@link #isOpen isOpen} method.
  51  *
  52  * <p> A Connection is safe for access by multiple concurrent threads,
  53  * although at most one thread may be reading and at most one thread may
  54  * be writing at any given time.
  55  *
  56  * @since 1.5
  57  */

  58 public abstract class Connection {
  59 
  60     /**
  61      * Reads a packet from the target VM.
  62      *
  63      * <p> Attempts to read a JDWP packet from the target VM.
  64      * A read operation may block indefinitely and only returns
  65      * when it reads all bytes of a packet, or in the case of a
  66      * transport service that is based on a stream-oriented
  67      * communication protocol, the end of stream is encountered.
  68      *
  69      * <p> Reading a packet does not do any integrity checking on
  70      * the packet aside from a check that the length of the packet
  71      * (as indicated by the value of the {@code length} field, the
  72      * first four bytes of the packet) is 11 or more bytes.
  73      * If the value of the {@code length} value is less then 11
  74      * then an {@code IOException} is thrown.
  75      *
  76      * <p> Returns a byte array of a length equal to the length
  77      * of the received packet, or a byte array of length 0 when an