Package org.eclipse.jetty.io

Interface EndPoint

All Superinterfaces:
AutoCloseable, Closeable
All Known Implementing Classes:
AbstractEndPoint, ByteArrayEndPoint, ClientHTTP2StreamEndPoint, DatagramChannelEndPoint, HTTP2StreamEndPoint, LocalConnector.LocalEndPoint, NetworkTrafficSocketChannelEndPoint, ProxyConnectionFactory.ProxyEndPoint, QuicStreamEndPoint, SelectableChannelEndPoint, ServerHTTP2StreamEndPoint, SocketChannelEndPoint, SslConnection.DecryptedEndPoint, UnixSocketEndPoint
public interface EndPoint extends Closeable

EndPoint is the abstraction for an I/O channel that transports bytes.

Asynchronous Methods

The asynchronous scheduling methods of EndPoint has been influenced by NIO.2 Futures and Completion handlers, but does not use those actual interfaces because they have some inefficiencies.

This class will frequently be used in conjunction with some of the utility implementations of Callback, such as FutureCallback and IteratingCallback.

Reads

A FutureCallback can be used to block until an endpoint is ready to fill bytes - the notification will be emitted by the NIO subsystem:

 FutureCallback callback = new FutureCallback();
 endPoint.fillInterested(callback);

 // Blocks until read to fill bytes.
 callback.get();

 // Now bytes can be filled in a ByteBuffer.
 int filled = endPoint.fill(byteBuffer);

Asynchronous Reads

A Callback can be used to read asynchronously in its own dispatched thread:

 endPoint.fillInterested(new Callback()
 {
   public void onSucceeded()
   {
     executor.execute(() ->
     {
       // Fill bytes in a different thread.
       int filled = endPoint.fill(byteBuffer);
     });
   }
   public void onFailed(Throwable failure)
   {
     endPoint.close();
   }
 });

Blocking Writes

The write contract is that the callback is completed when all the bytes have been written or there is a failure. Blocking writes look like this:

 FutureCallback callback = new FutureCallback();
 endpoint.write(callback, headerBuffer, contentBuffer);

 // Blocks until the write succeeds or fails.
 future.get();

Note also that multiple buffers may be passed in write(Callback, ByteBuffer...) so that gather writes can be performed for efficiency.

  • Method Details

    • getLocalAddress

      @Deprecated InetSocketAddress getLocalAddress()
      Deprecated.
      use getLocalSocketAddress() instead
      Returns:
      The local InetSocketAddress to which this EndPoint is bound, or null if this EndPoint is not bound to a Socket address.

    • getLocalSocketAddress

      default SocketAddress getLocalSocketAddress()
      Returns:
      the local SocketAddress to which this EndPoint is bound or null if this EndPoint is not bound to a Socket address.

    • getRemoteAddress

      @Deprecated InetSocketAddress getRemoteAddress()
      Deprecated.
      use getRemoteSocketAddress() instead.
      Returns:
      The remote InetSocketAddress to which this EndPoint is connected, or null if this EndPoint is not connected to a Socket address.

    • getRemoteSocketAddress

      default SocketAddress getRemoteSocketAddress()
      Returns:
      The remote SocketAddress to which this EndPoint is connected, or null if this EndPoint is not connected to a Socket address.

    • isOpen

      boolean isOpen()
      Returns:
      whether this EndPoint is open

    • getCreatedTimeStamp

      long getCreatedTimeStamp()
      Returns:
      the epoch time in milliseconds when this EndPoint was created

    • shutdownOutput

      void shutdownOutput()
      Shutdown the output.

      This call indicates that no more data will be sent on this endpoint that that the remote end should read an EOF once all previously sent data has been consumed. Shutdown may be done either at the TCP/IP level, as a protocol exchange (Eg TLS close handshake) or both.

      If the endpoint has isInputShutdown() true, then this call has the same effect as close().

    • isOutputShutdown

      boolean isOutputShutdown()
      Test if output is shutdown. The output is shutdown by a call to shutdownOutput() or close().
      Returns:
      true if the output is shutdown or the endpoint is closed.

    • isInputShutdown

      boolean isInputShutdown()
      Test if the input is shutdown. The input is shutdown if an EOF has been read while doing a fill(ByteBuffer). Once the input is shutdown, all calls to fill(ByteBuffer) will return -1, until such time as the end point is close, when they will return EofException.
      Returns:
      True if the input is shutdown or the endpoint is closed.

    • close

      default void close()
      Close any backing stream associated with the endpoint
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable

    • close

      void close(Throwable cause)
      Close any backing stream associated with the endpoint, passing a cause
      Parameters:
      cause - the reason for the close or null

    • fill

      default int fill(ByteBuffer buffer) throws IOException
      Fill the passed buffer with data from this endpoint. The bytes are appended to any data already in the buffer by writing from the buffers limit up to it's capacity. The limit is updated to include the filled bytes.
      Parameters:
      buffer - The buffer to fill. The position and limit are modified during the fill. After the operation, the position is unchanged and the limit is increased to reflect the new data filled.
      Returns:
      an int value indicating the number of bytes filled or -1 if EOF is read or the input is shutdown.
      Throws:
      IOException - if the endpoint is closed.

    • flush

      default boolean flush(ByteBuffer... buffer) throws IOException
      Flush data from the passed header/buffer to this endpoint. As many bytes as can be consumed are taken from the header/buffer position up until the buffer limit. The header/buffers position is updated to indicate how many bytes have been consumed.
      Parameters:
      buffer - the buffers to flush
      Returns:
      True IFF all the buffers have been consumed and the endpoint has flushed the data to its destination (ie is not buffering any data).
      Throws:
      IOException - If the endpoint is closed or output is shutdown.

    • getTransport

      Object getTransport()
      Returns:
      The underlying transport object (socket, channel, etc.)

    • getIdleTimeout

      long getIdleTimeout()
      Get the max idle time in ms.

      The max idle time is the time the endpoint can be idle before extraordinary handling takes place.

      Returns:
      the max idle time in ms or if ms <= 0 implies an infinite timeout

    • setIdleTimeout

      void setIdleTimeout(long idleTimeout)
      Set the idle timeout.
      Parameters:
      idleTimeout - the idle timeout in MS. Timeout <= 0 implies an infinite timeout

    • fillInterested

      void fillInterested(Callback callback) throws ReadPendingException

      Requests callback methods to be invoked when a call to fill(ByteBuffer) would return data or EOF.

      Parameters:
      callback - the callback to call when an error occurs or we are readable. The callback may implement the Invocable interface to self declare its blocking status. Non-blocking callbacks may be called more efficiently without dispatch delays.
      Throws:
      ReadPendingException - if another read operation is concurrent.

    • tryFillInterested

      boolean tryFillInterested(Callback callback)

      Requests callback methods to be invoked when a call to fill(ByteBuffer) would return data or EOF.

      Parameters:
      callback - the callback to call when an error occurs or we are readable. The callback may implement the Invocable interface to self declare its blocking status. Non-blocking callbacks may be called more efficiently without dispatch delays.
      Returns:
      true if set

    • isFillInterested

      boolean isFillInterested()
      Returns:
      whether fillInterested(Callback) has been called, but fill(ByteBuffer) has not yet been called

    • write

      default void write(Callback callback, ByteBuffer... buffers) throws WritePendingException

      Writes the given buffers via flush(ByteBuffer...) and invokes callback methods when either all the data has been flushed or an error occurs.

      Parameters:
      callback - the callback to call when an error occurs or the write completed. The callback may implement the Invocable interface to self declare its blocking status. Non-blocking callbacks may be called more efficiently without dispatch delays.
      buffers - one or more ByteBuffers that will be flushed.
      Throws:
      WritePendingException - if another write operation is concurrent.

    • getConnection

      Connection getConnection()
      Returns:
      the Connection associated with this EndPoint
      See Also:

    • setConnection

      void setConnection(Connection connection)
      Parameters:
      connection - the Connection associated with this EndPoint
      See Also:

    • onOpen

      void onOpen()

      Callback method invoked when this EndPoint is opened.

      See Also:

    • onClose

      void onClose(Throwable cause)

      Callback method invoked when this EndPoint is closed.

      Parameters:
      cause - The reason for the close, or null if a normal close.
      See Also:

    • upgrade

      void upgrade(Connection newConnection)

      Upgrades this EndPoint from the current connection to the given new connection.

      Closes the current connection, links this EndPoint to the new connection and then opens the new connection.

      If the current connection is an instance of Connection.UpgradeFrom then a buffer of unconsumed bytes is requested. If the buffer of unconsumed bytes is non-null and non-empty, then the new connection is tested: if it is an instance of Connection.UpgradeTo, then the unconsumed buffer is passed to the new connection; otherwise, an exception is thrown since there are unconsumed bytes that cannot be consumed by the new connection.

      Parameters:
      newConnection - the connection to upgrade to