Channel (Hazelcast Root 3.11 API)

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 InboundHandler. E.g data from a socket is received and needs to get processed. The InboundHandler can convert this to e.g. a Packet. Channel data is written using a OutboundHandler. 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

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`	`connect(InetSocketAddress address, int timeoutMillis)` Connects the channel.
`InboundPipeline`	`inboundPipeline()` Returns the `InboundPipeline` that belongs to this Channel.
`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 time epoch time in ms a read of the socket was done.
`long`	`lastWriteTimeMillis()` Returns the last time epoch time in ms a write to the socket was done.
`SocketAddress`	`localSocketAddress()`
`ChannelOptions`	`options()` Returns the `ChannelOptions` of this Channel.
`OutboundPipeline`	`outboundPipeline()` Returns the `OutboundPipeline` that belongs to this Channel.
`SocketAddress`	`remoteSocketAddress()`
`Socket`	`socket()`
`void`	`start()` Starts the Channel.
`boolean`	`write(OutboundFrame frame)` Queues the `OutboundFrame` to be written at some point in the future.

- Method Detail
  - options
```
ChannelOptions options()
```
    Returns the ChannelOptions of this Channel. Call is threadsafe; but calls to the ChannelOptions are not.
    
    Returns:
    
    the config for this channel. Returned value will never be null.
  - 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.
  - inboundPipeline
```
InboundPipeline inboundPipeline()
```
    Returns the InboundPipeline that belongs to this Channel. This method is threadsafe, but most methods on the InboundPipeline are not!
    
    Returns:
    
    the InboundPipeline.
  - outboundPipeline
```
OutboundPipeline outboundPipeline()
```
    Returns the OutboundPipeline that belongs to this Channel. This method is threadsafe, but most methods on the OutboundPipeline are not!
    
    Returns:
    
    the OutboundPipeline.
  - 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 time epoch time in ms 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 time epoch time in ms a write to the socket was done. 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 network-buffer. This method is thread-safe.
    
    Returns:
    
    the last time something was written to the socket.
  - start
```
void start()
```
    Starts the Channel. In case of a client-mode channel, the connect(InetSocketAddress, int) should be called before start is called. When the Channel is started, the ChannelInitializer will be called to initialize the channel and to start with processing inbound and outbound data. This method is not threadsafe and should be made only once.
  - close
```
void close()
    throws IOException
```
    Closes the Channel. It could be that the actual closing of the Channel is executed asynchronous and completes at some point in the future. This is important for e.g. TLS goodbye handshake. 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
  - connect
```
void connect(InetSocketAddress address,
             int timeoutMillis)
      throws IOException
```
    Connects the channel. This call should only be made once and is not threadsafe. This call blocks until:
    1. the connect succeeds
    2. the connect fails
    3. if there is a timeout.
    In case of failure, channel is closed automatically and exception is thrown to user.
    Parameters:
    
    address - the address to connect to.
    
    timeoutMillis - the timeout in millis, or 0 if waiting indefinitely.
    
    Throws:
    
    IOException - if connecting fails.
  - 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.

Interface Channel

Future note

Fragmentation

Ordering

Reliability

Flow and congestion control

UDP

Method Summary

Method Detail

options

attributeMap

inboundPipeline

outboundPipeline

socket

remoteSocketAddress

localSocketAddress

lastReadTimeMillis

lastWriteTimeMillis

start

close

connect

isClosed

addCloseListener

isClientMode

write