org.xsocket.connection
Interface IDataHandler

All Superinterfaces:

IHandler

All Known Implementing Classes:

HandlerChain

public interface IDataHandler
extends IHandler

Reads and processes the incoming data. This method will be called each time when data is available or the connection is closed. Because this depends on the underlying tcp protocol, it is not predictable how often and when this method will be call. Please note, that on network level data can be fragmented on several TCP packets as well as data can be bundled into one TCP packet.

Performing a write operation like connection.write("hello it's me. What I have to say is.") on the client side doesn�t mean that exact one onData call occurs on the server side. A common pattern to solve this is to identify logical parts by a delimiter or a leading length field. xSocket provides methods to support this pattern. E.g. the IDataSource.readStringByDelimiter(String) method only returns a record if the whole part (identified by the delimiter) has been received, or if not, a BufferUnderflowException will be thrown. In contrast to IBlockingConnection, a INonBlockingConnection read method always returns immediately and could thrown a BufferUnderflowException. The BufferUnderflowException will be swallowed by the framework, if the DataHandler doesn�t catch this exception. It is a common pattern not to handle such an exception by the DataHandler.

 public final class MyHandler implements IDataHandler, IConnectionScoped {
   ...
   public boolean onData(INonBlockingConnection connection) throws IOException, BufferUnderflowException, MaxReadSizeExceededException {
        ...
      // BufferUnderflowException will been thrown if delimiter has not been found.
      // A MaxReadSizeExceededException will be thrown if the max read size has been exceeded. Not handling this exception causes
      // that the server closes the underlying connection
      String command = connection.readStringByDelimiter("\r\n", "US-ASCII", 5000);
      ...
      connection.write(response, "US-ASCII");
      return true;
   }
 }
 

Author:

grro@xsocket.org

Field Summary

Fields inherited from interface org.xsocket.connection.IHandler

DEFAULT_EXECUTION_MODE

Method Summary

boolean

onData(INonBlockingConnection connection) processes the incoming data based on the given connection.

Method Detail

onData

boolean onData(INonBlockingConnection connection)
               throws IOException,
                      BufferUnderflowException,
                      ClosedChannelException,
                      MaxReadSizeExceededException

processes the incoming data based on the given connection.

Please note, that the onData call back method can also be called for if an connection will be closed. In this case the isOpen call within the onData Method will return false. Reading of already received data will not fail. To detect if a connection has been closed the callback method onDisconnect should be implemented. The correct call back order will be managed by the xSocket.

Parameters:

connection - the underlying connection

Returns:

true for positive result of handling, false for negative result of handling. The return value will be used by the HandlerChain to interrupted the chaining (if result is true)

Throws:

IOException - If some other I/O error occurs. Throwing this exception causes that the underlying connection will be closed.

BufferUnderflowException - if more incoming data is required to process (e.g. delimiter hasn't yet received -> readByDelimiter methods or size of the available, received data is smaller than the required size -> readByLength). The BufferUnderflowException will be swallowed by the framework

ClosedChannelException - if the connection is closed

MaxReadSizeExceededException - if the max read size has been reached (e.g. by calling method IDataSource.readStringByDelimiter(String, int)). Throwing this exception causes that the underlying connection will be closed.

RuntimeException - if an runtime exception occurs. Throwing this exception causes that the underlying connection will be closed. *