com.devexperts.connector

Interface ConnectionAdapter

All Known Implementing Classes:

MARSConnectionAdapter

public interface ConnectionAdapter

ConnectionAdapter is used to mate single connection (network socket) with corresponding data structures. It is created whenever new connection is established and is destroyed when that connection is closed. Therefore, it is a stateful object with lifetime equal to that of the corresponding connection.

Method Summary

Modifier and Type	Method and Description
void	close() Closes this connection adapter.
int	readData() Performs single blocking read operation from connection (network socket).
void	setListener(ConnectionAdapterListener listener) Sets new listener to receive notifications about connection adapter state changes.
void	start() Starts this connection adapter.
int	writeData() Performs single blocking write operation into connection (network socket).
int	writeHeartbeat() Performs single blocking write operation into connection (network socket) of special heartbeat packet as specified by communication protocol.

Method Detail

setListener

void setListener(ConnectionAdapterListener listener)

Sets new listener to receive notifications about connection adapter state changes. Called once immediately after connection adapter is created and before it is started.

start

void start()

Starts this connection adapter. May allocate additional resources if required. Called once after listener was set and before any read/write operations.

close

void close()

Closes this connection adapter. Shall release all allocated resources. May be called several times (though shall not) and even during read/write operations.

readData

int readData()
      throws Throwable

Performs single blocking read operation from connection (network socket). Called by dedicated thread in infinite loop until connection is closed.

NOTE: This method may block either during socket read itself or during data processing.

This method shall return number of bytes read from connection. If it returns negative number, then it will be considered an EOF signal and connection will be closed.

This method generally shall pass through any exceptions to the caller. If any exception is thrown, then it will be considered an error and connection will be closed.

Throws:

Throwable

writeData

int writeData()
       throws Throwable

Performs single blocking write operation into connection (network socket). Called by dedicated thread in infinite loop until connection is closed.

NOTE: This method may block only during socket write itself; it shall not block while waiting for more data availability. If this method finds that there is no data to write, it shall return immediately. When new data become available, the corresponding listener shall be notified. If this method writes only part of available data and wants to be immediately called again to write remaining data, it shall notify corresponding listener that data is available (it is allowed to do so directly from this method).

This method shall return number of bytes written into connection. If it returns negative number, then it will be considered an EOF signal and connection will be closed.

This method generally shall pass through any exceptions to the caller. If any exception is thrown, then it will be considered an error and connection will be closed.

Throws:

Throwable

writeHeartbeat

int writeHeartbeat()
            throws Throwable

Performs single blocking write operation into connection (network socket) of special heartbeat packet as specified by communication protocol. Called by the same dedicated thread which calls writeData() method whenever it detects that no data was written into connection for specified heartbeat period and that new heartbeat packet shall be written instead.

NOTE: This method may block only during socket write itself. Actually, this method shall not perform any other actions except writing heartbeat packet into socket. It shall not, in particular, check for business data availability to write it instead. When new data become available, the corresponding listener shall be notified.

This method shall return number of bytes written into connection. If it returns negative number, then it will be considered an EOF signal and connection will be closed.
NOTE: If this method returns 0 bytes (i.e. no heartbeat packet was written), then it might be immediately called again in an infinite loop fashion until heartbeat packet is written, or business data is available, or connection is closed. Therefore, if heartbeats are not specified by communication protocol, then heartbeat period and timeout both shall be configured to 0 as indication that no heartbeats are required.

This method generally shall pass through any exceptions to the caller. If any exception is thrown, then it will be considered an error and connection will be closed.

Throws:

Throwable