public interface EndPoint
extends java.io.Closeable
EndPoint is the abstraction for an I/O channel that transports bytes.
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
.
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);
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(); } });
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.
Modifier and Type | Method and Description |
---|---|
void |
close()
Close any backing stream associated with the endpoint
|
int |
fill(java.nio.ByteBuffer buffer)
Fill the passed buffer with data from this endpoint.
|
void |
fillInterested(Callback callback)
Requests callback methods to be invoked when a call to
fill(ByteBuffer) would return data or EOF. |
boolean |
flush(java.nio.ByteBuffer... buffer)
Flush data from the passed header/buffer to this endpoint.
|
Connection |
getConnection() |
long |
getCreatedTimeStamp() |
long |
getIdleTimeout()
Get the max idle time in ms.
|
java.net.InetSocketAddress |
getLocalAddress() |
java.net.InetSocketAddress |
getRemoteAddress() |
java.lang.Object |
getTransport() |
boolean |
isFillInterested() |
boolean |
isInputShutdown()
Test if the input is shutdown.
|
boolean |
isOpen() |
boolean |
isOptimizedForDirectBuffers()
Is the endpoint optimized for DirectBuffer usage
|
boolean |
isOutputShutdown()
Test if output is shutdown.
|
void |
onClose()
Callback method invoked when this EndPoint is close.
|
void |
onOpen()
Callback method invoked when this EndPoint is opened.
|
void |
setConnection(Connection connection) |
void |
setIdleTimeout(long idleTimeout)
Set the idle timeout.
|
void |
shutdownOutput()
Shutdown the output.
|
boolean |
tryFillInterested(Callback callback)
Requests callback methods to be invoked when a call to
fill(ByteBuffer) would return data or EOF. |
void |
upgrade(Connection newConnection)
Upgrades this EndPoint from the current connection to the given new connection.
|
void |
write(Callback callback,
java.nio.ByteBuffer... buffers)
Writes the given buffers via
flush(ByteBuffer...) and invokes callback methods when either
all the data has been flushed or an error occurs. |
java.net.InetSocketAddress getLocalAddress()
EndPoint
is bound, or null
if this EndPoint
does not represent a network connection.java.net.InetSocketAddress getRemoteAddress()
EndPoint
is bound, or null
if this EndPoint
does not represent a network connection.boolean isOpen()
long getCreatedTimeStamp()
void shutdownOutput()
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()
.
boolean isOutputShutdown()
shutdownOutput()
or close()
.boolean isInputShutdown()
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
.void close()
close
in interface java.lang.AutoCloseable
close
in interface java.io.Closeable
int fill(java.nio.ByteBuffer buffer) throws java.io.IOException
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.int
value indicating the number of bytes
filled or -1 if EOF is read or the input is shutdown.java.io.IOException
- if the endpoint is closed.boolean flush(java.nio.ByteBuffer... buffer) throws java.io.IOException
buffer
- the buffers to flushjava.io.IOException
- If the endpoint is closed or output is shutdown.java.lang.Object getTransport()
long getIdleTimeout()
The max idle time is the time the endpoint can be idle before extraordinary handling takes place.
void setIdleTimeout(long idleTimeout)
idleTimeout
- the idle timeout in MS. Timeout <= 0 implies an infinite timeoutvoid 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.
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.java.nio.channels.ReadPendingException
- if another read operation is concurrent.boolean tryFillInterested(Callback callback)
Requests callback methods to be invoked when a call to fill(ByteBuffer)
would return data or EOF.
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.boolean isFillInterested()
fillInterested(Callback)
has been called, but fill(ByteBuffer)
has not yet
been calledvoid 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.
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 ByteBuffer
s that will be flushed.java.nio.channels.WritePendingException
- if another write operation is concurrent.Connection getConnection()
Connection
associated with this EndPointsetConnection(Connection)
void setConnection(Connection connection)
connection
- the Connection
associated with this EndPointgetConnection()
,
upgrade(Connection)
void onOpen()
Callback method invoked when this EndPoint is opened.
onClose()
void onClose()
Callback method invoked when this EndPoint is close.
onOpen()
boolean isOptimizedForDirectBuffers()
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.
newConnection
- the connection to upgrade toCopyright © 1995–2021 Webtide. All rights reserved.