Channel (hazelcast-client-protocol 1.5.0-2 API)

All Superinterfaces:

AutoCloseable, Closeable

All Known Implementing Classes:

AbstractChannel, NioChannel, SpinningChannel
```
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 be 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

All Methods Instance Methods Abstract Methods
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.
`SocketAddress`	`getLocalSocketAddress()`
`SocketAddress`	`getRemoteSocketAddress()`
`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.
`int`	`read(ByteBuffer dst)` This method will be removed from the Channel in the near future.
`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.
  - getRemoteSocketAddress
```
SocketAddress getRemoteSocketAddress()
```
    Returns:
    
    the remote address. Returned value could be null.
  - getLocalSocketAddress
```
SocketAddress getLocalSocketAddress()
```
    Returns:
    
    the local address. Returned value could be null
  - lastReadTimeMillis
```
long lastReadTimeMillis()
```
    Returns the last Clock.currentTimeMillis() a read of the socket was done.
    
    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.
    
    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. 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.
    
    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.
    
    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.
    
    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.

Interface Channel

Future note

Fragmentation

Ordering

Reliability

Flow and congestion control

UDP

Method Summary

Method Detail

attributeMap

socket

getRemoteSocketAddress

getLocalSocketAddress

lastReadTimeMillis

lastWriteTimeMillis

read

write

closeInbound

closeOutbound

close

isClosed

addCloseListener

isClientMode

write

flush