Interface EndPoint

All Superinterfaces:
AutoCloseable, Closeable, Content.Sink
All Known Implementing Classes:
AbstractEndPoint, ByteArrayEndPoint, DatagramChannelEndPoint, HTTP2StreamEndPoint, LocalConnector.LocalEndPoint, NetworkTrafficSocketChannelEndPoint, ProxyConnectionFactory.ProxyEndPoint, SelectableChannelEndPoint, SocketChannelEndPoint, SslConnection.SslEndPoint, StreamEndPoint
public interface EndPoint extends Closeable, Content.Sink

EndPoint is the abstraction for I/O communication using bytes.

All the I/O methods are non-blocking; reads may return 0 bytes read, and flushes/writes may write 0 bytes.

Applications are notified of read readiness by registering a Callback via fillInterested(Callback), and then using fill(ByteBuffer) to read the available bytes.

Application may use flush(ByteBuffer...) to transmit bytes; if the flush does not transmit all the bytes, applications must arrange to resume flushing when it will be possible to transmit more bytes. Alternatively, applications may use write(Callback, ByteBuffer...) and be notified via the Callback when the write completes (i.e. all the buffers have been flushed), either successfully or with a failure.

Connection-less reads are performed using receive(ByteBuffer). Similarly, connection-less flushes are performed using send(SocketAddress, ByteBuffer...) and connection-less writes using write(Callback, SocketAddress, ByteBuffer...).

While all the I/O methods are non-blocking, they can be easily converted to blocking using either Blocker or Callback.Completable:

EndPoint endPoint = ...;

// Block until read ready with Blocker.
try (Blocker.Callback blocker = Blocker.callback())
{
    endPoint.fillInterested(blocker);
    blocker.block();
}

// Block until write complete with Callback.Completable.
Callback.Completable completable = new Callback.Completable();
endPoint.write(completable, byteBuffer);
completable.get();

  • Field Details

  • Method Details

    • 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.

    • 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()

      Shuts down the output.

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

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

    • isOutputShutdown

      boolean isOutputShutdown()

      Tests 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()

      Tests 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()

      Closes any backing stream associated with the endpoint.

      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable

    • close

      void close(Throwable cause)

      Closes any backing stream associated with the endpoint, passing a possibly null failure cause.

      Parameters:
      cause - the reason for the close or null

    • fill

      default int fill(ByteBuffer buffer) throws IOException

      Fills 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 its 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.

    • receive

      default SocketAddress receive(ByteBuffer buffer) throws IOException

      Receives data into the given buffer from the returned address.

      This method should be used to receive UDP data.

      Parameters:
      buffer - the buffer to fill with data
      Returns:
      the peer address that sent the data, or EOF
      Throws:
      IOException - if the receive fails

    • flush

      default boolean flush(ByteBuffer... buffer) throws IOException

      Flushes 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.

    • send

      default boolean send(SocketAddress address, ByteBuffer... buffers) throws IOException

      Sends to the given address the data in the given buffers.

      This methods should be used to send UDP data.

      Parameters:
      address - the peer address to send data to
      buffers - the buffers containing the data to send
      Returns:
      true if all the buffers have been consumed
      Throws:
      IOException - if the send fails
      See Also:

    • getTransport

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

    • getIdleTimeout

      long getIdleTimeout()

      Returns the idle timeout in ms.

      The idle timeout is the time the endpoint can be idle before its close is initiated.

      A timeout less than or equal to 0 implies an infinite timeout.

      Returns:
      the idle timeout in ms

    • setIdleTimeout

      void setIdleTimeout(long idleTimeout)

      Sets 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.

    • write

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

      Writes to the given address the data contained in the given buffers, and invokes the given callback when either all the data has been sent, or a failure occurs.

      Parameters:
      callback - the callback to notify of the success or failure of the write operation
      address - the peer address to send data to
      buffers - the buffers containing the data to send
      Throws:
      WritePendingException - if a previous write was initiated but was not yet completed
      See Also:

    • write

      default void write(boolean last, ByteBuffer byteBuffer, Callback callback)
      Description copied from interface: Content.Sink

      Writes the given ByteBuffer, notifying the Callback when the write is complete.

      Implementations guarantee that calls to this method are safely reentrant so that stack overflows are avoided in the case of mutual recursion between the execution of the Callback and a call to this method.

      Specified by:
      write in interface Content.Sink
      Parameters:
      last - whether the ByteBuffer is the last to write
      byteBuffer - the ByteBuffer to write
      callback - the callback to notify when the write operation is complete

    • cancelWrite

      Callback cancelWrite(Throwable cause)
      Cancel any current write(Callback, ByteBuffer...) operation in progress. Calling this method with cause future calls to write(Callback, ByteBuffer...) and its variants, to fail the passed Callback.
      Parameters:
      cause - the cause
      Returns:
      The callback passed to a pending/in progress write or null if there was none.

    • 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

    • getSslSessionData

      default EndPoint.SslSessionData getSslSessionData()

      Returns the SslSessionData of a secure end point.

      Returns:
      A EndPoint.SslSessionData instance (with possibly null field values) if secure, else null.

    • isSecure

      default boolean isSecure()
      Returns:
      whether this EndPoint represents a secure communication.