Channel (ETA)

All Known Implementing Classes:

JNIChannel, RsslSeqMulticastSocketChannel
```
public interface Channel
```
The ETA Channel is used to represent a connection that can send or receive information across a network. This class is used to represent a connection, regardless of if that was an outbound connection or a connection that was accepted by a listening socket. Any memory associated with a Channel object is internally managed by the ETA Transport Package, and the application does not need to create nor destroy any memory associated with a Channel. The Channel is typically used to perform any action on the connection that it represents (e.g. reading, writing, disconnecting, * etc).

Method Summary

All Methods Instance Methods Abstract Methods Default Methods Deprecated Methods
Modifier and Type	Method and Description
`boolean`	`blocking()` The blocking mode of the channel.
`int`	`bufferUsage(Error error)` Returns the total number of used buffers for this channel. Typical use: This method can be called to find out the number of used buffers for the calling channel.
`int`	`close(Error error)` Closes a Channel. Typical use: When done using a Channel, this call closes it.
`int`	`connectionType()` The connection type associated with the `Channel`.
`default int`	`encryptedConnectionType()` Encrypted connection type associated with the `Channel`.
`int`	`flush(Error error)` Flushes data waiting to be written on a given channel. Typical use: This method pushes the data in the write buffer out to the network.
`TransportBuffer`	`getBuffer(int size, boolean packedBuffer, Error error)` Retrieves a `TransportBuffer` for use. Typical use: This is called when a buffer is needed to write data to.
`java.lang.String`	`hostname()` For NIProvider and Consumer applications, remote server host name associated with the `Channel`.
`int`	`info(ChannelInfo info, Error error)` Gets information about the channel. Typical use: If information about the `Channel` is needed, such as maxFragmentSize or maxOutputBuffers, this method can be called to retrieve this information.
`int`	`init(InProgInfo inProg, Error error)` Continues channel initialization for non-blocking channels. Typical use: 1.
`int`	`ioctl(int code, int value, Error error)` Allows changing some I/O values programmatically.
`int`	`ioctl(int code, java.lang.Object value, Error error)` Allows changing some I/O values programmatically.
`int`	`majorVersion()` When a `Channel` becomes active for a client or server, this is populated with the negotiated major version number that is associated with the content being sent on this connection.
`int`	`minorVersion()` When a `Channel` becomes active for a client or server, this is populated with the negotiated minor version number that is associated with the content being sent on this connection.
`java.nio.channels.SocketChannel`	`oldScktChannel()` Deprecated. use `oldSelectableChannel()` instead
`java.nio.channels.SelectableChannel`	`oldSelectableChannel()` It is possible for a channel to change over time, typically due to some kind of connection keep-alive mechanism.
`int`	`packBuffer(TransportBuffer buffer, Error error)` Allows user to pack multiple ETA encoded messages into the same ETA Buffer. Typical use: This is called when the application wants to perform message packing.
`int`	`ping(Error error)` Sends a heartbeat message. Typical use: This method is called to send some type of ping or heartbeat message.
`int`	`pingTimeout()` When a `Channel` becomes active for a client or server, this is populated with the negotiated ping timeout value.
`default int`	`port()` For NIProvider and Consumer applications, remote server port number associated with the `Channel`.
`int`	`protocolType()` When a `Channel` becomes active for a client or server, this is populated with the protocolType associated with the content being sent on this connection.
`TransportBuffer`	`read(ReadArgs readArgs, Error error)` Reads on a given channel. Typical use: This method is called and returns a buffer with any data read from the channel.
`int`	`reconnectClient(Error error)` Used for tunneling solutions to reconnect and bridge connections.
`int`	`releaseBuffer(TransportBuffer buffer, Error error)` Releases a `TransportBuffer` after use. A buffer obtained through getBuffer() call is returned to the buffer pool by write() method or releaseBuffer() method.
`java.nio.channels.SocketChannel`	`scktChannel()` Deprecated. use `selectableChannel()` instead
`java.nio.channels.SelectableChannel`	`selectableChannel()` java.nio.channels.SelectableChannel of the channel.
`int`	`state()` The state associated with the `Channel`.
`java.lang.Object`	`userSpecObject()` A user specified object, possibly a closure.This value can be set directly or via the connection options and is not modified by the transport.
`int`	`write(TransportBuffer buffer, WriteArgs writeArgs, Error error)` Writes on a given channel. Typical use: This method is called after buffer is populated with a message.

- Method Detail
  - info
```
int info(ChannelInfo info,
         Error error)
```
    Gets information about the channel.
    Typical use:
    If information about the Channel is needed, such as maxFragmentSize or maxOutputBuffers, this method can be called to retrieve this information. If the channel is closed by the far end, this method returns error and the channel state is set to CLOSED.
    
    Parameters:
    
    info - Channel Info structure to be populated
    
    error - Error, to be populated in event of an error
    
    Returns:
    
    TransportReturnCodes
    
    See Also:
    
    ChannelInfo
  - ioctl
```
int ioctl(int code,
          java.lang.Object value,
          Error error)
```
    Allows changing some I/O values programmatically. Typical use:
    If an I/O value needs to be changed, this method is used.
    Valid codes are:
    - IoctlCodes.PRIORITY_FLUSH_ORDER
    Parameters:
    
    code - IoctlCodes code of I/O Option to change
    
    value - Value to change Option to
    
    error - Error to be populated in event of an error
    
    Returns:
    
    TransportReturnCodes
    
    See Also:
    
    IoctlCodes
  - ioctl
```
int ioctl(int code,
          int value,
          Error error)
```
    Allows changing some I/O values programmatically. Typical use:
    If an I/O value needs to be changed, this method is used.
    Valid codes are:
    - IoctlCodes.MAX_NUM_BUFFERS - the return code will be the new value of maxOutputBuffers or TransportReturnCodes.FAILURE. If the specified value is less than guaranteedOutputBuffers, the guaranteedOutputBuffers value will be used.
    - IoctlCodes.NUM_GUARANTEED_BUFFERS - the return code will be the new value of guarenteedOutputBuffers or TransportReturnCodes.FAILURE. If the specified value is larger than maxOutputBuffers, maxOutputBuffers will be set to the value. If the value is less than the number of free buffers in the guaranteed pool (due to buffers being in use), the guaranteed pool will be reduced by the number of free buffers.
    - IoctlCodes.HIGH_WATER_MARK
    - IoctlCodes.SYSTEM_READ_BUFFERS - for values larger than 64K, use ConnectOptions.sysRecvBufSize(int) to set the receive buffer size, prior to calling Transport.connect(ConnectOptions, Error).
    - IoctlCodes.SYSTEM_WRITE_BUFFERS
    - IoctlCodes.COMPRESSION_THRESHOLD
    - If the channel is closed by the far end, this method returns error and the channel state is set to CLOSED.
    Parameters:
    
    code - IoctlCodes code of I/O Option to change.
    
    value - Value to change Option to
    
    error - Error to be populated in event of an error
    
    Returns:
    
    TransportReturnCodes or a positive number specific to the specified code.
    
    See Also:
    
    ChannelInfo
  - bufferUsage
```
int bufferUsage(Error error)
```
    Returns the total number of used buffers for this channel.
    Typical use:
    This method can be called to find out the number of used buffers for the calling channel. This, in combination with the maxOutputBuffers obtained from the getInfo call, can be used to monitor and potentially throttle buffer usage.
    
    Parameters:
    
    error - Error, to be populated in event of an error
    
    Returns:
    
    If less than 0, this is a TransportReturnCodes, otherwise it is the total number of buffers in use by this channel
  - init
```
int init(InProgInfo inProg,
         Error error)
```
    Continues channel initialization for non-blocking channels.
    Typical use:
    1. Connect using Transport.connect
    2. While Channel state is INITIALIZING and the channel detects data to read, call this method.
    Note: This method is not necessary for blocking channels, which will return in the ACTIVE state after the Transport.connect call.
    
    Parameters:
    
    inProg - InProg Info for compatibility mode reconnection
    
    error - Error, to be populated in event of an error
    
    Returns:
    
    TransportReturnCodes
    
    See Also:
    
    InProgInfo, ChannelState
  - close
```
int close(Error error)
```
    Closes a Channel.
    Typical use:
    When done using a Channel, this call closes it. This method should also be used when any method on the channel returned error and the channel state is CLOSED. This method sets the channel's state to INACTIVE. Before calling this method, all TransportBuffers that has been obtained through getBuffer() method and were not written (through write() method) should be released to pool by calling releaseBuffer() method. This method returns this channel to the channel pool.
    
    Parameters:
    
    error - Error, to be populated in event of an error
    
    Returns:
    
    TransportReturnCodes
  - read
```
TransportBuffer read(ReadArgs readArgs,
                     Error error)
```
    Reads on a given channel.
    Typical use:
    This method is called and returns a buffer with any data read from the channel. The buffer is only good until the next time this method is called. The buffer used for reading is populated by this call and it is not necessary to use getBuffer to create a buffer. This method will assign ReadArgs.readRetVal() a positive value if there is more data to read, TransportReturnCodes.READ_WOULD_BLOCK if the read call is blocked, or a failure code. If the socket of the channel is closed by the far end, this method returns error and the channel state is set to CLOSED.
    
    Parameters:
    
    readArgs - read arguments
    
    error - Error, to be populated in event of an error
    
    Returns:
    
    Buffer that contains data read from network
    
    See Also:
    
    ReadArgs
  - getBuffer
```
TransportBuffer getBuffer(int size,
                          boolean packedBuffer,
                          Error error)
```
    Retrieves a TransportBuffer for use.
    Typical use:
    This is called when a buffer is needed to write data to. Generally, the user will populate the TransportBuffer structure and then pass it to the write method.
    
    Parameters:
    
    size - Size of the requested buffer
    
    packedBuffer - Set to true if you plan on packing multiple messages into the same buffer
    
    error - Error, to be populated in event of an error
    
    Returns:
    
    buffer to be filled in with valid memory (null returned for no more buffers or error condition)
    
    See Also:
    
    TransportBuffer
  - releaseBuffer
```
int releaseBuffer(TransportBuffer buffer,
                  Error error)
```
    Releases a TransportBuffer after use.
    A buffer obtained through getBuffer() call is returned to the buffer pool by write() method or releaseBuffer() method. In successful scenarios this method is not used since the buffers are returned to pool in write(). This method must be called when write returned error. It also must be called for each buffer that has not been written before the channel is closed (i.e. by calling close() method.)
    
    Parameters:
    
    buffer - buffer to be released
    
    error - Error, to be populated in event of an error
    
    Returns:
    
    TransportReturnCodes
    
    See Also:
    
    TransportBuffer
  - packBuffer
```
int packBuffer(TransportBuffer buffer,
               Error error)
```
    Allows user to pack multiple ETA encoded messages into the same ETA Buffer.
    Typical use:
    This is called when the application wants to perform message packing.
    - Call getBuffer (with packedBuffer set to true) to get a new buffer.
    - Call necessary encode methods.
    - Call this method to write size of packed buffer and prepare for next packed buffer.
    - Repeat above two steps until ready to write, or until there is not enough available bytes remaining to continue packing into the buffer.
    - Call write with the packed buffer.
    - Repeat the entire procedure until all messages are written.
    Parameters:
    
    buffer - buffer to be packed
    
    error - Error, to be populated in event of an error
    
    Returns:
    
    TransportReturnCodes or the amount of available bytes remaining in the buffer for packing.
    
    See Also:
    
    TransportBuffer
  - write
```
int write(TransportBuffer buffer,
          WriteArgs writeArgs,
          Error error)
```
    Writes on a given channel.
    Typical use:
    This method is called after buffer is populated with a message. This message is then written to the channel internal write buffer. If write is successful, the passed in buffer will be released automatically. In the event of a failure the user needs to call releaseBuffer. In the success case, this method will return the number of bytes pending flush. Note: Data is not written across the network until flush is called. If the channel is closed by the far end, this method returns error and the channel state is set to CLOSED.
    
    Parameters:
    
    buffer - Buffer to write to the network
    
    writeArgs - Arguments for writing the buffer (WriteArgs)
    
    error - Error, to be populated in event of an error
    
    Returns:
    
    TransportReturnCodes or the number of bytes pending flush
    
    See Also:
    
    WriteArgs
  - flush
```
int flush(Error error)
```
    Flushes data waiting to be written on a given channel.
    Typical use:
    This method pushes the data in the write buffer out to the network. This should be called when write returns that there is data to flush. Under certain circumstances, write will automatically flush data. If the channel is closed by the far end, this method returns error and the channel state is set to CLOSED.
    
    Parameters:
    
    error - Error, to be populated in event of an error
    
    Returns:
    
    TransportReturnCodes or the number of bytes pending flush
  - ping
```
int ping(Error error)
```
    Sends a heartbeat message.
    Typical use:
    This method is called to send some type of ping or heartbeat message. This will send only the message header across the network. This helps reduce overhead on the network, and does not incur any cost of parsing or assembling a special ping message type. It is the user's responsibility to send the ping message in the correct time frame. Since it is assumed a ping or heartbeat is only sent when other writing is not taking place, flush is automatically called once. The return value will be the number of bytes left to flush. If the channel is closed by the far end, this method returns error and the channel state is set to CLOSED.
    
    Parameters:
    
    error - Error, to be populated in event of an error
    
    Returns:
    
    TransportReturnCodes or the number of bytes pending flush
  - majorVersion
```
int majorVersion()
```
    When a Channel becomes active for a client or server, this is populated with the negotiated major version number that is associated with the content being sent on this connection. Typically, a major version increase is associated with the introduction of incompatible change. The transport layer is data neutral and does not change nor depend on any information in content being distributed. This information is provided to help client and server applications manage the information they are communicating.
    
    Returns:
    
    the majorVersion
  - minorVersion
```
int minorVersion()
```
    When a Channel becomes active for a client or server, this is populated with the negotiated minor version number that is associated with the content being sent on this connection. Typically, a minor version increase is associated with a fully backward compatible change or extension. The transport layer is data neutral and does not change nor depend on any information in content being distributed. This information is provided to help client and server applications manage the information they are communicating.
    
    Returns:
    
    the minorVersion
  - protocolType
```
int protocolType()
```
    When a Channel becomes active for a client or server, this is populated with the protocolType associated with the content being sent on this connection. If the protocolType indicated by a server does not match the protocolType that a client specifies, the connection will be rejected. The transport layer is data neutral and does not change nor depend on any information in content being distributed. This information is provided to help client and server applications manage the information they are communicating.
    
    Returns:
    
    the protocolType
  - state
```
int state()
```
    The state associated with the Channel. Until the channel has completed its initialization handshake and has transitioned to an active state, no reading or writing can be performed.
    
    Returns:
    
    the state
    
    See Also:
    
    ChannelState
  - scktChannel
```
@Deprecated
java.nio.channels.SocketChannel scktChannel()
```
    Deprecated. use selectableChannel() instead
    
    java.nio.channels.SocketChannel of the channel.
    
    Returns:
    
    the scktChannel
  - oldScktChannel
```
@Deprecated
java.nio.channels.SocketChannel oldScktChannel()
```
    Deprecated. use oldSelectableChannel() instead
    
    It is possible for a socket channel to change over time, typically due to some kind of connection keep-alive mechanism. If this occurs, this is typically communicated via a return code of TransportReturnCodes.READ_FD_CHANGE. The previous socketId is stored in oldSocketId so the application can properly unregister and then register the new socketId with their I/O notification mechanism.
    
    Returns:
    
    the oldScktChannel
  - selectableChannel
```
java.nio.channels.SelectableChannel selectableChannel()
```
    java.nio.channels.SelectableChannel of the channel.
    
    Returns:
    
    the selectableChannel
  - oldSelectableChannel
```
java.nio.channels.SelectableChannel oldSelectableChannel()
```
    It is possible for a channel to change over time, typically due to some kind of connection keep-alive mechanism. If this occurs, this is typically communicated via a return code of TransportReturnCodes.READ_FD_CHANGE. The previous socketId is stored in oldSocketId so the application can properly unregister and then register the new socketId with their I/O notification mechanism.
    
    Returns:
    
    the oldSelectableChannel
  - pingTimeout
```
int pingTimeout()
```
    When a Channel becomes active for a client or server, this is populated with the negotiated ping timeout value. This is the number of seconds after which no communication can result in a connection being terminated. Both client and server applications should send heartbeat information within this interval. The typically used rule of thumb is to send a heartbeat every pingTimeout/3 seconds.
    
    Returns:
    
    the pingTimeout
  - userSpecObject
```
java.lang.Object userSpecObject()
```
    A user specified object, possibly a closure.This value can be set directly or via the connection options and is not modified by the transport. This information can be useful for coupling this Channel with other user created information, such as a watch list associated with this connection.
    
    Returns:
    
    the userSpecObject
  - blocking
```
boolean blocking()
```
    The blocking mode of the channel.
    
    Returns:
    
    the blocking mode
  - reconnectClient
```
int reconnectClient(Error error)
```
    Used for tunneling solutions to reconnect and bridge connections. This only applies to http and encrypted connections, where it might be needed to keep connections alive through proxy servers.
    
    Parameters:
    
    error - Error, to be populated in event of an error
    
    Returns:
    
    TransportReturnCodes
  - connectionType
```
int connectionType()
```
    The connection type associated with the Channel.
    
    Returns:
    
    the connection type
    
    See Also:
    
    ConnectionTypes
  - hostname
```
java.lang.String hostname()
```
    For NIProvider and Consumer applications, remote server host name associated with the Channel.
    
    Returns:
    
    the host name
  - port
```
default int port()
```
    For NIProvider and Consumer applications, remote server port number associated with the Channel. Relevant for Socket connection, zero for other
    
    Returns:
    
    the port number
  - encryptedConnectionType
```
default int encryptedConnectionType()
```
    Encrypted connection type associated with the Channel. This method is used when connectionType() is ConnectionTypes.ENCRYPTED
    
    Returns:
    
    the encrypted connection type

Interface Channel

Method Summary

Method Detail

info

ioctl

ioctl

bufferUsage

init

close

read

getBuffer

releaseBuffer

packBuffer

write

flush

ping

majorVersion

minorVersion

protocolType

state

scktChannel

oldScktChannel

selectableChannel

oldSelectableChannel

pingTimeout

userSpecObject

blocking

reconnectClient

connectionType

hostname

port

encryptedConnectionType