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
public interface EndPoint extends java.io.Closeable
A transport EndPointAsynchronous 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 asFutureCallback
andIteratingCallback
. 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 Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description void
close()
Close any backing stream associated with the endpointint
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 tofill(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 usageboolean
isOutputShutdown()
Test if output is shutdown.void
onClose()
Callback method invoked when thisEndPoint
is close.void
onOpen()
Callback method invoked when thisEndPoint
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 tofill(ByteBuffer)
would return data or EOF.void
upgrade(Connection newConnection)
Upgrade connections.void
write(Callback callback, java.nio.ByteBuffer... buffers)
Writes the given buffers viaflush(ByteBuffer...)
and invokes callback methods when either all the data has been flushed or an error occurs.
-
-
-
Method Detail
-
getLocalAddress
java.net.InetSocketAddress getLocalAddress()
- Returns:
- The local Inet address to which this
EndPoint
is bound, ornull
if thisEndPoint
does not represent a network connection.
-
getRemoteAddress
java.net.InetSocketAddress getRemoteAddress()
- Returns:
- The remote Inet address to which this
EndPoint
is bound, ornull
if thisEndPoint
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 asclose()
.
-
isOutputShutdown
boolean isOutputShutdown()
Test if output is shutdown. The output is shutdown by a call toshutdownOutput()
orclose()
.- 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 afill(ByteBuffer)
. Once the input is shutdown, all calls tofill(ByteBuffer)
will return -1, until such time as the end point is close, when they will returnEofException
.- 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 interfacejava.lang.AutoCloseable
- Specified by:
close
in interfacejava.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 theInvocable
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 theInvocable
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, butfill(ByteBuffer)
has not yet been called
-
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 theInvocable
interface to self declare its blocking status. Non-blocking callbacks may be called more efficiently without dispatch delays.buffers
- one or moreByteBuffer
s that will be flushed.- Throws:
java.nio.channels.WritePendingException
- if another write operation is concurrent.
-
getConnection
Connection getConnection()
- Returns:
- the
Connection
associated with thisEndPoint
- See Also:
setConnection(Connection)
-
setConnection
void setConnection(Connection connection)
- Parameters:
connection
- theConnection
associated with thisEndPoint
- See Also:
getConnection()
,upgrade(Connection)
-
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 ofConnection.UpgradeFrom
then a prefilled buffer is requested and passed to the newConnection if it is an instance ofConnection.UpgradeTo
- Parameters:
newConnection
- The connection to upgrade to
-
-