Package org.eclipse.jetty.io

Interface EndPoint

  • All Superinterfaces:
    java.lang.AutoCloseable, java.io.Closeable
    All Known Implementing Classes:
    AbstractEndPoint, ByteArrayEndPoint, ChannelEndPoint, LocalConnector.LocalEndPoint, NetworkTrafficSelectChannelEndPoint, NetworkTrafficSocketChannelEndPoint, ProxyConnectionFactory.ProxyEndPoint, SelectChannelEndPoint, SocketChannelEndPoint, SslConnection.DecryptedEndPoint, UnixSocketEndPoint
    public interface EndPoint
extends java.io.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 Detail

      • getLocalAddress

        java.net.InetSocketAddress getLocalAddress()
        Returns:
        The local Inet address to which this EndPoint is bound, or null if this EndPoint does not represent a network connection.

      • getRemoteAddress

        java.net.InetSocketAddress getRemoteAddress()
        Returns:
        The remote Inet address to which this EndPoint is bound, or null if this EndPoint does not represent a network connection.

      • 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

        void close()
        Close any backing stream associated with the endpoint
        Specified by:
        close in interface java.lang.AutoCloseable
        Specified by:
        close in interface java.io.Closeable

      • fill

        int fill​(java.nio.ByteBuffer buffer)
  throws java.io.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:
        java.io.IOException - if the endpoint is closed.

      • flush

        boolean flush​(java.nio.ByteBuffer... buffer)
       throws java.io.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:
        java.io.IOException - If the endpoint is closed or output is shutdown.

      • getTransport

        java.lang.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 java.nio.channels.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:
        java.nio.channels.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

      • write

        void write​(Callback callback,
           java.nio.ByteBuffer... buffers)
    throws java.nio.channels.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:
        java.nio.channels.WritePendingException - if another write operation is concurrent.

      • onOpen

        void onOpen()

        Callback method invoked when this EndPoint is opened.

        See Also:
        onClose()

      • onClose

        void onClose()

        Callback method invoked when this EndPoint is close.

        See Also:
        onOpen()

      • isOptimizedForDirectBuffers

        boolean isOptimizedForDirectBuffers()
        Is the endpoint optimized for DirectBuffer usage
        Returns:
        True if direct buffers can be used optimally.

      • 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