lib/jetty/org/eclipse/jetty/io/EndPoint.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.io.IOException;
  23 import java.net.InetSocketAddress;
  24 import java.nio.ByteBuffer;
  25 import java.nio.channels.ReadPendingException;
  26 import java.nio.channels.WritePendingException;
  27
  28 import org.eclipse.jetty.util.Callback;
  29
  30 /**
  31  *
  32  * A transport EndPoint
  33  *
  34  * <h3>Asynchronous Methods</h3>
  35  * <p>The asynchronous scheduling methods of {@link EndPoint}
  36  * has been influenced by NIO.2 Futures and Completion
  37  * handlers, but does not use those actual interfaces because they have
  38  * some inefficiencies.</p>
  39  * <p>This class will frequently be used in conjunction with some of the utility
  40  * implementations of {@link Callback}, such as {@link FutureCallback} and
  41  * {@link ExecutorCallback}. Examples are:</p>
  42  *
  43  * <h3>Blocking Read</h3>
  44  * <p>A FutureCallback can be used to block until an endpoint is ready to be filled
  45  * from:
  46  * <blockquote><pre>
  47  * FutureCallback&lt;String&gt; future = new FutureCallback&lt;&gt;();
  48  * endpoint.fillInterested("ContextObj",future);
  49  * ...
  50  * String context = future.get(); // This blocks
  51  * int filled=endpoint.fill(mybuffer);
  52  * </pre></blockquote></p>
  53  *
  54  * <h3>Dispatched Read</h3>
  55  * <p>By using a different callback, the read can be done asynchronously in its own dispatched thread:
  56  * <blockquote><pre>
  57  * endpoint.fillInterested("ContextObj",new ExecutorCallback&lt;String&gt;(executor)
  58  * {
  59  *   public void onCompleted(String context)
  60  *   {
  61  *     int filled=endpoint.fill(mybuffer);
  62  *     ...
  63  *   }
  64  *   public void onFailed(String context,Throwable cause) {...}
  65  * });
  66  * </pre></blockquote></p>
  67  * <p>The executor callback can also be customized to not dispatch in some circumstances when
  68  * it knows it can use the callback thread and does not need to dispatch.</p>
  69  *
  70  * <h3>Blocking Write</h3>
  71  * <p>The write contract is that the callback complete is not called until all data has been
  72  * written or there is a failure.  For blocking this looks like:
  73  * <blockquote><pre>
  74  * FutureCallback&lt;String&gt; future = new FutureCallback&lt;&gt;();
  75  * endpoint.write("ContextObj",future,headerBuffer,contentBuffer);
  76  * String context = future.get(); // This blocks
  77  * </pre></blockquote></p>
  78  *
  79  * <h3>Dispatched Write</h3>
  80  * <p>Note also that multiple buffers may be passed in write so that gather writes
  81  * can be done:
  82  * <blockquote><pre>
  83  * endpoint.write("ContextObj",new ExecutorCallback&lt;String&gt;(executor)
  84  * {
  85  *   public void onCompleted(String context)
  86  *   {
  87  *     int filled=endpoint.fill(mybuffer);
  88  *     ...
  89  *   }
  90  *   public void onFailed(String context,Throwable cause) {...}
  91  * },headerBuffer,contentBuffer);
  92  * </pre></blockquote></p>
  93  */
  94 public interface EndPoint extends Closeable
  95 {
  96     /* ------------------------------------------------------------ */
  97     /**
  98      * @return The local Inet address to which this <code>EndPoint</code> is bound, or <code>null</code>
  99      * if this <code>EndPoint</code> does not represent a network connection.
 100      */
 101     InetSocketAddress getLocalAddress();
 102
 103     /* ------------------------------------------------------------ */
 104     /**
 105      * @return The remote Inet address to which this <code>EndPoint</code> is bound, or <code>null</code>
 106      * if this <code>EndPoint</code> does not represent a network connection.
 107      */
 108     InetSocketAddress getRemoteAddress();
 109
 110     /* ------------------------------------------------------------ */
 111     boolean isOpen();
 112
 113     /* ------------------------------------------------------------ */
 114     long getCreatedTimeStamp();
 115
 116     /* ------------------------------------------------------------ */
 117     /** Shutdown the output.
 118      * <p>This call indicates that no more data will be sent on this endpoint that
 119      * that the remote end should read an EOF once all previously sent data has been
 120      * consumed. Shutdown may be done either at the TCP/IP level, as a protocol exchange (Eg
 121      * TLS close handshake) or both.
 122      * <p>
 123      * If the endpoint has {@link #isInputShutdown()} true, then this call has the same effect
 124      * as {@link #close()}.
 125      */
 126     void shutdownOutput();
 127
 128     /* ------------------------------------------------------------ */
 129     /** Test if output is shutdown.
 130      * The output is shutdown by a call to {@link #shutdownOutput()}
 131      * or {@link #close()}.
 132      * @return true if the output is shutdown or the endpoint is closed.
 133      */
 134     boolean isOutputShutdown();
 135
 136     /* ------------------------------------------------------------ */
 137     /** Test if the input is shutdown.
 138      * The input is shutdown if an EOF has been read while doing
 139      * a {@link #fill(ByteBuffer)}.   Once the input is shutdown, all calls to
 140      * {@link #fill(ByteBuffer)} will  return -1, until such time as the
 141      * end point is close, when they will return {@link EofException}.
 142      * @return True if the input is shutdown or the endpoint is closed.
 143      */
 144     boolean isInputShutdown();
 145
 146     /**
 147      * Close any backing stream associated with the endpoint
 148      */
 149     @Override
 150     void close();
 151
 152     /**
 153      * Fill the passed buffer with data from this endpoint.  The bytes are appended to any
 154      * data already in the buffer by writing from the buffers limit up to it's capacity.
 155      * The limit is updated to include the filled bytes.
 156      *
 157      * @param buffer The buffer to fill. The position and limit are modified during the fill. After the
 158      * operation, the position is unchanged and the limit is increased to reflect the new data filled.
 159      * @return an <code>int</code> value indicating the number of bytes
 160      * filled or -1 if EOF is read or the input is shutdown.
 161      * @throws EofException If the endpoint is closed.
 162      */
 163     int fill(ByteBuffer buffer) throws IOException;
 164
 165
 166     /**
 167      * Flush data from the passed header/buffer to this endpoint.  As many bytes as can be consumed
 168      * are taken from the header/buffer position up until the buffer limit.  The header/buffers position
 169      * is updated to indicate how many bytes have been consumed.
 170      * @return True IFF all the buffers have been consumed and the endpoint has flushed the data to its
 171      * destination (ie is not buffering any data).
 172      *
 173      * @throws EofException If the endpoint is closed or output is shutdown.
 174      */
 175     boolean flush(ByteBuffer... buffer) throws IOException;
 176
 177     /* ------------------------------------------------------------ */
 178     /**
 179      * @return The underlying transport object (socket, channel, etc.)
 180      */
 181     Object getTransport();
 182
 183     /* ------------------------------------------------------------ */
 184     /** Get the max idle time in ms.
 185      * <p>The max idle time is the time the endpoint can be idle before
 186      * extraordinary handling takes place.
 187      * @return the max idle time in ms or if ms <= 0 implies an infinite timeout
 188      */
 189     long getIdleTimeout();
 190
 191     /* ------------------------------------------------------------ */
 192     /** Set the idle timeout.
 193      * @param idleTimeout the idle timeout in MS. Timeout <= 0 implies an infinite timeout
 194      */
 195     void setIdleTimeout(long idleTimeout);
 196
 197
 198     /**
 199      * <p>Requests callback methods to be invoked when a call to {@link #fill(ByteBuffer)} would return data or EOF.</p>
 200      *
 201      * @param callback the callback to call when an error occurs or we are readable.
 202      * @throws ReadPendingException if another read operation is concurrent.
 203      */
 204     void fillInterested(Callback callback) throws ReadPendingException;
 205
 206     /**
 207      * <p>Writes the given buffers via {@link #flush(ByteBuffer...)} and invokes callback methods when either
 208      * all the data has been flushed or an error occurs.</p>
 209      *
 210      * @param callback the callback to call when an error occurs or the write completed.
 211      * @param buffers one or more {@link ByteBuffer}s that will be flushed.
 212      * @throws WritePendingException if another write operation is concurrent.
 213      */
 214     void write(Callback callback, ByteBuffer... buffers) throws WritePendingException;
 215
 216     /**
 217      * @return the {@link Connection} associated with this {@link EndPoint}
 218      * @see #setConnection(Connection)
 219      */
 220     Connection getConnection();
 221
 222     /**
 223      * @param connection the {@link Connection} associated with this {@link EndPoint}
 224      * @see #getConnection()
 225      * @see #upgrade(Connection)
 226      */
 227     void setConnection(Connection connection);
 228
 229     /**
 230      * <p>Callback method invoked when this {@link EndPoint} is opened.</p>
 231      * @see #onClose()
 232      */
 233     void onOpen();
 234
 235     /**
 236      * <p>Callback method invoked when this {@link EndPoint} is close.</p>
 237      * @see #onOpen()
 238      */
 239     void onClose();
 240
 241
 242     /** Upgrade connections.
 243      * Close the old connection, update the endpoint and open the new connection.
 244      * If the oldConnection is an instance of {@link Connection.UpgradeFrom} then
 245      * a prefilled buffer is requested and passed to the newConnection if it is an instance
 246      * of {@link Connection.UpgradeTo}
 247      * @param newConnection The connection to upgrade to
 248      */
 249     public void upgrade(Connection newConnection);
 250 }