com.hazelcast.internal.networking

Interface Channel

All Superinterfaces:

AutoCloseable, Closeable

All Known Implementing Classes:

AbstractChannel, NioChannel

public interface Channel
extends Closeable

A Channel is a construct that can send/receive like Packets/ClientMessages etc. Connections use a channel to do the real work; but there is no dependency of the com.hazelcast.internal.networking to a Connection (no cycles). This means that a Channel can be used perfectly without Connection. The standard channel implementation is the NioChannel that uses TCP in combination with selectors to transport data. In the future also other channel implementations could be added, e.g. UDP based. Channel data is read using a ChannelInboundHandler. E.g data from a socket is received and needs to get processed. The ChannelInboundHandler can convert this to e.g. a Packet. Channel data is written using a ChannelOutboundHandler. E.g. a packet needs to be converted to bytes. A Channel gets initialized using the ChannelInitializer.

Future note

Below you can find some notes about the future of the Channel. This will hopefully act as a guide how to move forward.

Fragmentation

Packets are currently not fragmented, meaning that they are send as 1 atomic unit and this can cause a 2 way communication blackout for operations (since either operation or response can get blocked). Fragmentation needs to be added to make sure the system doesn't suffer from head of line blocking.

Ordering

In a channel messages don't need to remain ordered. Currently they are, but as soon as we add packet fragmentation, packets can get out of order. Under certain conditions you want to keep ordering, e.g. for events. In this case it should be possible to have multiple streams in a channel. Within a stream there will be ordering.

Reliability

A channel doesn't provide reliability. TCP/IP does provide reliability, but 1: who says we want to keep using TCP/IP, but if a TCP/IP connection is lost and needs to be re-established, packets are lost. Reliability can be added, just like TCP/IP adds it; we don't discard the data until it has been acknowledged.

Flow and congestion control

On the Channel level we have no flow of congestion control; frames are always accepted no matter if on the sending side the write-queue is overloaded, or on the receiving side the system is overloaded (e.g. many pending operations on the operation queue). Just like with TCP/IP, flow and congestion control should be added.

UDP

With ordering, reliability and flow and congestion control in place, we can ask ourselves the question if UDP is not a more practical solution.

Method Summary

Modifier and Type	Method and Description
void	addCloseListener(ChannelCloseListener listener) Adds a ChannelCloseListener.
ConcurrentMap	attributeMap() Returns the attribute map.
void	close() Closes the Channel.
void	closeInbound() Closes inbound.
void	closeOutbound() Closes outbound.
void	flush() Flushes whatever needs to be written.
boolean	isClientMode() Checks if this side is the Channel is in client mode or server mode.
boolean	isClosed() Checks if this Channel is closed.
long	lastReadTimeMillis() Returns the last Clock.currentTimeMillis() a read of the socket was done.
long	lastWriteTimeMillis() Returns the last Clock.currentTimeMillis() that a write to the socket completed.
SocketAddress	localSocketAddress()
int	read(ByteBuffer dst) This method will be removed from the Channel in the near future.
SocketAddress	remoteSocketAddress()
Socket	socket()
int	write(ByteBuffer src) This method will be removed from the Channel in the near future.
boolean	write(OutboundFrame frame) Queues the OutboundFrame to be written at some point in the future.

Method Detail

attributeMap

ConcurrentMap attributeMap()

Returns the attribute map. Attribute map can be used to store data into a socket. For example to find the Connection for a Channel, one can store the Connection in this channel using some well known key.

Returns:

the attribute map.

socket

Socket socket()

See Also:

This method will be removed from the interface. Only an explicit cast to NioChannel will expose the Socket. It is very important that the socket isn't closed directly; but one goes through the {@link #close()} method so that interal administration of the channel is in sync with that of the socket.

remoteSocketAddress

SocketAddress remoteSocketAddress()

Returns:

the remote address. Returned value could be null.

localSocketAddress

SocketAddress localSocketAddress()

Returns:

the local address. Returned value could be null

lastReadTimeMillis

long lastReadTimeMillis()

Returns the last Clock.currentTimeMillis() a read of the socket was done. This method is thread-safe.

Returns:

the last time a read from the socket was done.

lastWriteTimeMillis

long lastWriteTimeMillis()

Returns the last Clock.currentTimeMillis() that a write to the socket completed. Writing to the socket doesn't mean that data has been send or received; it means that data was written to the SocketChannel. It could very well be that this data is stuck somewhere in an io-buffer. This method is thread-safe.

Returns:

the last time something was written to the socket.

read

int read(ByteBuffer dst)
  throws IOException

This method will be removed from the Channel in the near future.

Throws:

IOException

See Also:

SocketChannel.read(ByteBuffer)

write

int write(ByteBuffer src)
   throws IOException

This method will be removed from the Channel in the near future.

Throws:

IOException

See Also:

SocketChannel.write(ByteBuffer)

closeInbound

void closeInbound()
           throws IOException

Closes inbound.

Not thread safe. Should be called in channel reader thread.

Method will be removed once the TLS integration doesn't rely on subclassing this channel.

Throws:

IOException

closeOutbound

void closeOutbound()
            throws IOException

Closes outbound.

Not thread safe. Should be called in channel writer thread.

Method will be removed once the TLS integration doesn't rely on subclassing this channel.

Throws:

IOException

close

void close()
    throws IOException

Closes the Channel. This method is thread-safe. When the channel already is closed, the call is ignored.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Throws:

IOException

isClosed

boolean isClosed()

Checks if this Channel is closed. This method is very cheap to make.

Returns:

true if closed, false otherwise.

addCloseListener

void addCloseListener(ChannelCloseListener listener)

Adds a ChannelCloseListener. This method is thread-safe.

Parameters:

listener - the listener to register.

Throws:

NullPointerException - if listener is null.

isClientMode

boolean isClientMode()

Checks if this side is the Channel is in client mode or server mode. A channel is in client-mode if it initiated the connection, and in server-mode if it was the one accepting the connection. One of the reasons this property is valuable is for protocol/handshaking so that it is clear distinction between the side that initiated the connection, or accepted the connection. This method is thread-safe.

Returns:

true if this channel is in client-mode, false when in server-mode.

See Also:

SSLEngine.getUseClientMode()

write

boolean write(OutboundFrame frame)

Queues the OutboundFrame to be written at some point in the future. No guarantee is made that the frame actually is going to be written or received. This method is thread-safe.

Parameters:

frame - the frame to write.

Returns:

true if the frame was queued; false if rejected.

flush

void flush()

Flushes whatever needs to be written. Normally this call doesn't need to be made since write(OutboundFrame) write the content; but in case of protocol and TLS handshaking, such triggers are needed.