lib/jetty/org/eclipse/jetty/io/Connection.java

   1 //
   2 //  ========================================================================
   3 //  Copyright (c) 1995-2016 Mort Bay Consulting Pty. Ltd.
   4 //  ------------------------------------------------------------------------
   5 //  All rights reserved. This program and the accompanying materials
   6 //  are made available under the terms of the Eclipse Public License v1.0
   7 //  and Apache License v2.0 which accompanies this distribution.
   8 //
   9 //      The Eclipse Public License is available at
  10 //      http://www.eclipse.org/legal/epl-v10.html
  11 //
  12 //      The Apache License v2.0 is available at
  13 //      http://www.opensource.org/licenses/apache2.0.php
  14 //
  15 //  You may elect to redistribute this code under either of these licenses.
  16 //  ========================================================================
  17 //
  18
  19 package org.eclipse.jetty.io;
  20
  21 import java.io.Closeable;
  22 import java.nio.ByteBuffer;
  23
  24 /**
  25  * <p>A {@link Connection} is associated to an {@link EndPoint} so that I/O events
  26  * happening on the {@link EndPoint} can be processed by the {@link Connection}.</p>
  27  * <p>A typical implementation of {@link Connection} overrides {@link #onOpen(ByteBuffer)} to
  28  * {@link EndPoint#fillInterested(Callback) set read interest} on the {@link EndPoint},
  29  * and when the {@link EndPoint} signals read readyness, this {@link Connection} can
  30  * read bytes from the network and interpret them.</p>
  31  */
  32 public interface Connection extends Closeable
  33 {
  34     public void addListener(Listener listener);
  35
  36     public void onOpen();
  37
  38     /**
  39      * <p>Callback method invoked when this {@link Connection} is closed.</p>
  40      * <p>Creators of the connection implementation are responsible for calling this method.</p>
  41      */
  42     public void onClose();
  43
  44     /**
  45      * @return the {@link EndPoint} associated with this {@link Connection}
  46      */
  47     public EndPoint getEndPoint();
  48
  49     /**
  50      * <p>Performs a logical close of this connection.</p>
  51      * <p>For simple connections, this may just mean to delegate the close to the associated
  52      * {@link EndPoint} but, for example, SSL connections should write the SSL close message
  53      * before closing the associated {@link EndPoint}.</p>
  54      */
  55     @Override
  56     public void close();
  57
  58     public int getMessagesIn();
  59     public int getMessagesOut();
  60     public long getBytesIn();
  61     public long getBytesOut();
  62     public long getCreatedTimeStamp();
  63
  64     public interface UpgradeFrom extends Connection
  65     {
  66         /* ------------------------------------------------------------ */
  67         /** Take the input buffer from the connection on upgrade.
  68          * <p>This method is used to take any unconsumed input from
  69          * a connection during an upgrade.
  70          * @return A buffer of unconsumed input. The caller must return the buffer
  71          * to the bufferpool when consumed and this connection must not.
  72          */
  73         ByteBuffer onUpgradeFrom();
  74     }
  75
  76     public interface UpgradeTo extends Connection
  77     {
  78         /**
  79          * <p>Callback method invoked when this {@link Connection} is upgraded.</p>
  80          * <p>This must be called before {@link #onOpen()}.</p>
  81          * @param prefilledBuffer An optional buffer that can contain prefilled data. Typically this
  82          * results from an upgrade of one protocol to the other where the old connection has buffered
  83          * data destined for the new connection.  The new connection must take ownership of the buffer
  84          * and is responsible for returning it to the buffer pool
  85          */
  86         void onUpgradeTo(ByteBuffer prefilled);
  87     }
  88
  89     public interface Listener
  90     {
  91         public void onOpened(Connection connection);
  92
  93         public void onClosed(Connection connection);
  94
  95         public static class Adapter implements Listener
  96         {
  97             @Override
  98             public void onOpened(Connection connection)
  99             {
 100             }
 101
 102             @Override
 103             public void onClosed(Connection connection)
 104             {
 105             }
 106         }
 107     }
 108 }