Package org.eclipse.jetty.io

Interface EndPoint

  • All Superinterfaces:
    AutoCloseable, Closeable
    All Known Implementing Classes:
    AbstractEndPoint, ByteArrayEndPoint, ChannelEndPoint, NetworkTrafficSelectChannelEndPoint, SelectChannelEndPoint, SocketChannelEndPoint, SslConnection.DecryptedEndPoint
    public interface EndPoint
extends Closeable
    A transport EndPoint

    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. Examples are:

    Blocking Read

    A FutureCallback can be used to block until an endpoint is ready to be filled from:

     FutureCallback<String> future = new FutureCallback<>();
 endpoint.fillInterested("ContextObj",future);
 ...
 String context = future.get(); // This blocks
 int filled=endpoint.fill(mybuffer);

    Dispatched Read

    By using a different callback, the read can be done asynchronously in its own dispatched thread:

     endpoint.fillInterested("ContextObj",new ExecutorCallback<String>(executor)
 {
   public void onCompleted(String context)
   {
     int filled=endpoint.fill(mybuffer);
     ...
   }
   public void onFailed(String context,Throwable cause) {...}
 });

    The executor callback can also be customized to not dispatch in some circumstances when it knows it can use the callback thread and does not need to dispatch.

    Blocking Write

    The write contract is that the callback complete is not called until all data has been written or there is a failure. For blocking this looks like:

     FutureCallback<String> future = new FutureCallback<>();
 endpoint.write("ContextObj",future,headerBuffer,contentBuffer);
 String context = future.get(); // This blocks

    Dispatched Write

    Note also that multiple buffers may be passed in write so that gather writes can be done:

     endpoint.write("ContextObj",new ExecutorCallback<String>(executor)
 {
   public void onCompleted(String context)
   {
     int filled=endpoint.fill(mybuffer);
     ...
   }
   public void onFailed(String context,Throwable cause) {...}
 },headerBuffer,contentBuffer);

    • Method Detail

      • getLocalAddress

        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

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

      • getCreatedTimeStamp

        long getCreatedTimeStamp()

      • 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 AutoCloseable
        Specified by:
        close in interface Closeable

      • fill

        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

        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​(org.eclipse.jetty.util.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​(org.eclipse.jetty.util.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​(org.eclipse.jetty.util.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.

      • 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)
        Upgrade connections. Close the old connection, update the endpoint and open the new connection. If the oldConnection is an instance of Connection.UpgradeFrom then a prefilled buffer is requested and passed to the newConnection if it is an instance of Connection.UpgradeTo
        Parameters:
        newConnection - The connection to upgrade to