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.

Nested and Inner Type Summary

Modifier and Type	Class and Description
public static interface	EndPoint.SslSessionData Interface representing bundle of SSLSession associated data.
public static interface	EndPoint.Wrapper Marks an `EndPoint` that wraps another `EndPoint`.

Method Summary

Modifier and Type	Method and Description
public default void	close() Implements java.io.Closeable.close. Close any backing stream associated with the endpoint
public void	close(Throwable the reason for the close or null cause) Close any backing stream associated with the endpoint, passing a cause
public default int	Returns: an `int` value indicating the number of bytes filled or -1 if EOF is read or the input is shutdown. fill(ByteBuffer 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. buffer) Fill the passed buffer with data from this endpoint.
public void	fillInterested(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. callback) Requests callback methods to be invoked when a call to `fill(ByteBuffer)` would return data or EOF.
public default boolean	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). flush(ByteBuffer... the buffers to flush buffer) Flush data from the passed header/buffer to this endpoint.
public Connection	getConnection() Returns: the `Connection` associated with this EndPoint
public long	getCreatedTimeStamp() Returns: the epoch time in milliseconds when this EndPoint was created
public long	Returns: the max idle time in ms or if ms <= 0 implies an infinite timeout getIdleTimeout() Get the max idle time in ms.
public 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.
public 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.
public 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.
public 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.
public default EndPoint.SslSessionData	Returns: A `SslSessionData` instance (with possibly null field values) if secure, else `null`. getSslSessionData() Get the SslSessionData of a secure end point.
public Object	getTransport() Returns: The underlying transport object (socket, channel, etc.)
public boolean	isFillInterested() Returns: whether `fillInterested(Callback)` has been called, but `fill(ByteBuffer)` has not yet been called
public boolean	Returns: True if the input is shutdown or the endpoint is closed. isInputShutdown() Test if the input is shutdown.
public boolean	isOpen() Returns: whether this EndPoint is open
public boolean	Returns: true if the output is shutdown or the endpoint is closed. isOutputShutdown() Test if output is shutdown.
public default boolean	isSecure() Returns: whether this EndPoint represents a secure communication.
public void	onClose(Throwable The reason for the close, or null if a normal close. cause) Callback method invoked when this `EndPoint` is closed.
public void	onOpen() Callback method invoked when this EndPoint is opened.
public void	setConnection(Connection the `Connection` associated with this EndPoint connection)
public void	setIdleTimeout(long the idle timeout in MS. Timeout <= 0 implies an infinite timeout idleTimeout) Set the idle timeout.
public void	shutdownOutput() Shutdown the output.
public boolean	Returns: true if set tryFillInterested(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. callback) Requests callback methods to be invoked when a call to `fill(ByteBuffer)` would return data or EOF.
public void	upgrade(Connection the connection to upgrade to newConnection) Upgrades this EndPoint from the current connection to the given new connection.
public default void	write(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. callback, ByteBuffer... one or more `ByteBuffer`s that will be flushed. buffers) Writes the given buffers via `flush(ByteBuffer...)` and invokes callback methods when either all the data has been flushed or an error occurs.

Method Detail

close	back to summary
public default void close() Implements java.io.Closeable.close. Close any backing stream associated with the endpoint Annotations @Override

back to summary

public default void close()

Implements java.io.Closeable.close.

Close any backing stream associated with the endpoint

Annotations

@Override

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

back to summary

public void close(Throwable cause)

Close any backing stream associated with the endpoint, passing a cause

Parameters

cause:Throwable: the reason for the close or null

fill back to summary

fill	back to summary
public 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:ByteBuffer 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:int an `int` value indicating the number of bytes filled or -1 if EOF is read or the input is shutdown. Exceptions IOException: if the endpoint is closed.

public 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:ByteBuffer: 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:int

an int value indicating the number of bytes filled or -1 if EOF is read or the input is shutdown.

Exceptions

IOException:: if the endpoint is closed.

fillInterested back to summary

fillInterested	back to summary
public 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: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. Exceptions ReadPendingException: if another read operation is concurrent.

public 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: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.

Exceptions

ReadPendingException:: if another read operation is concurrent.

flush	back to summary
public 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:ByteBuffer[] the buffers to flush Returns:boolean True IFF all the buffers have been consumed and the endpoint has flushed the data to its destination (ie is not buffering any data). Exceptions IOException: If the endpoint is closed or output is shutdown.

flush

back to summary

public 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:ByteBuffer[]: the buffers to flush

Returns:boolean

True IFF all the buffers have been consumed and the endpoint has flushed the data to its destination (ie is not buffering any data).

Exceptions

IOException:: If the endpoint is closed or output is shutdown.

getConnection	back to summary
public Connection getConnection() Returns:Connection the `Connection` associated with this EndPoint See Also `setConnection(Connection)`

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

getIdleTimeout	back to summary
public 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:long the max idle time in ms or if ms <= 0 implies an infinite timeout

getIdleTimeout

back to summary

public 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:long: the max idle time in ms or if ms <= 0 implies an infinite timeout

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

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

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

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

getSslSessionData back to summary

getSslSessionData	back to summary
public default EndPoint.SslSessionData getSslSessionData() Get the SslSessionData of a secure end point. Returns:EndPoint.SslSessionData A `SslSessionData` instance (with possibly null field values) if secure, else `null`.

public default EndPoint.SslSessionData getSslSessionData()

Get the SslSessionData of a secure end point.

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

getTransport	back to summary
public Object getTransport() Returns:Object The underlying transport object (socket, channel, etc.)

isFillInterested	back to summary
public boolean isFillInterested() Returns:boolean whether `fillInterested(Callback)` has been called, but `fill(ByteBuffer)` has not yet been called

isInputShutdown back to summary

isInputShutdown	back to summary
public 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:boolean True if the input is shutdown or the endpoint is closed.

public 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:boolean: True if the input is shutdown or the endpoint is closed.

isOpen	back to summary
public boolean isOpen() Returns:boolean whether this EndPoint is open

isOutputShutdown back to summary

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

public boolean isOutputShutdown()

Test if output is shutdown. The output is shutdown by a call to shutdownOutput() or close().

Returns:boolean: true if the output is shutdown or the endpoint is closed.

isSecure	back to summary
public default boolean isSecure() Returns:boolean whether this EndPoint represents a secure communication.

onClose back to summary

onClose	back to summary
public void onClose(Throwable cause) Callback method invoked when this `EndPoint` is closed. Parameters cause:Throwable The reason for the close, or null if a normal close. See Also `onOpen()`

public void onClose(Throwable cause)

Callback method invoked when this EndPoint is closed.

Parameters

cause:Throwable: The reason for the close, or null if a normal close.

See Also

onOpen()

onOpen back to summary

onOpen	back to summary
public void onOpen() Callback method invoked when this EndPoint is opened. See Also `onClose(Throwable)`

public void onOpen()

Callback method invoked when this EndPoint is opened.

See Also: onClose(Throwable)

setConnection	back to summary
public void setConnection(Connection connection) Parameters connection:Connection the `Connection` associated with this EndPoint See Also `getConnection()`, `upgrade(Connection)`

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

setIdleTimeout

back to summary

public void setIdleTimeout(long idleTimeout)

Set the idle timeout.

Parameters

idleTimeout:long: the idle timeout in MS. Timeout <= 0 implies an infinite timeout

shutdownOutput back to summary

shutdownOutput	back to summary
public 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()`.

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

tryFillInterested back to summary

tryFillInterested	back to summary
public boolean tryFillInterested(Callback callback) Requests callback methods to be invoked when a call to `fill(ByteBuffer)` would return data or EOF. Parameters callback: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:boolean true if set

public boolean tryFillInterested(Callback callback)

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

Parameters

callback: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:boolean

true if set

upgrade back to summary

upgrade	back to summary
public 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:Connection the connection to upgrade to

public 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:Connection: the connection to upgrade to

write back to summary

write	back to summary
public 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: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:ByteBuffer[] one or more `ByteBuffer`s that will be flushed. Exceptions WritePendingException: if another write operation is concurrent.

public 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: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:ByteBuffer[]: one or more ByteBuffers that will be flushed.

Exceptions

WritePendingException:: if another write operation is concurrent.

org.eclipse.jetty.io back to summary

public Interface EndPoint.SslSessionData

Interface representing bundle of SSLSession associated data.

Field Summary

Modifier and Type	Field and Description
public static final String	ATTRIBUTE The name at which an `SslSessionData` instance may be found as a request `Attribute` or from `SSLSession#getValue(String)`.

Method Summary

Modifier and Type	Method and Description
public String	cipherSuite() Returns: The `SSLSession#getCipherSuite()` if known, else `null`.
public static EndPoint.SslSessionData	from(SSLSession sslSession, String sslSessionId, String cipherSuite, X509Certificate[] peerCertificates)
public default int	Returns: the key size. keySize() Calculates the key size based on the cipher suite.
public X509Certificate[]	peerCertificates() Returns: The `SSLSession#getPeerCertificates()`s converted to `X509Certificate`, if known, else `null`.
public SSLSession	sslSession() Returns: The `SSLSession` itself, if known, else `null`.
public String	sslSessionId() Returns: The `SSLSession#getId()` rendered as a hex string, if known, else `null`.
public static EndPoint.SslSessionData	withCipherSuite(EndPoint.SslSessionData baseData, String cipherSuite)
public static EndPoint.SslSessionData	withSslSessionId(EndPoint.SslSessionData baseData, String sslSessionId)

Field Detail

ATTRIBUTE	back to summary
public static final String ATTRIBUTE The name at which an `SslSessionData` instance may be found as a request `Attribute` or from `SSLSession#getValue(String)`.

Method Detail

cipherSuite	back to summary
public String cipherSuite() Returns:String The `SSLSession#getCipherSuite()` if known, else `null`.

from	back to summary
public static EndPoint.SslSessionData from(SSLSession sslSession, String sslSessionId, String cipherSuite, X509Certificate[] peerCertificates)

keySize	back to summary
public default int keySize() Calculates the key size based on the cipher suite. Returns:int the key size.

keySize

back to summary

public default int keySize()

Calculates the key size based on the cipher suite.

Returns:int: the key size.

peerCertificates	back to summary
public X509Certificate[] peerCertificates() Returns:X509Certificate[] The `SSLSession#getPeerCertificates()`s converted to `X509Certificate`, if known, else `null`.

sslSession	back to summary
public SSLSession sslSession() Returns:SSLSession The `SSLSession` itself, if known, else `null`.

sslSessionId	back to summary
public String sslSessionId() Returns:String The `SSLSession#getId()` rendered as a hex string, if known, else `null`.

withCipherSuite	back to summary
public static EndPoint.SslSessionData withCipherSuite(EndPoint.SslSessionData baseData, String cipherSuite)

withSslSessionId	back to summary
public static EndPoint.SslSessionData withSslSessionId(EndPoint.SslSessionData baseData, String sslSessionId)

public Interface EndPoint

Nested and Inner Type Summary

Method Summary

Method Detail

public Interface EndPoint.SslSessionData

Field Summary

Method Summary

Field Detail

Method Detail

public Interface EndPoint.Wrapper

Method Summary

Method Detail