org.xsocket.stream.io.spi
Interface IIoHandler

public interface IIoHandler

The IIoHandler is responsible to perform the low level io operation of a IConnection. Each connection holds a dedicated io handler. There is always a 1:1 life cycle relationship between the connection instance and the io handler instance. Because a connection object is stateful, the io handler is (implicit) stateful, too. The io handler has to handle the read and write operations independently. There is no implicit call behaviour like request-response.
The io handler is responsible to notify io events by calling the assigned IIoHandlerContext reference.

The implementation needn`t to be threadsafe This class is experimental and is subject to change

Method Summary

void	close(boolean immediate) non-blocking close of the handler.
java.util.LinkedList<java.nio.ByteBuffer>	drainIncoming() drains the handler`s read buffer.
int	getConnectionTimeoutSec() returns the connection timeout.
java.lang.String	getId() return a unique conection id
int	getIdleTimeoutSec() returns the idle timeout.
java.net.InetAddress	getLocalAddress() returns the local address of the underlying connection.
int	getLocalPort() returns the local port of the underlying connection.
java.lang.Object	getOption(java.lang.String name) returns the vlaue of a option
java.util.Map<java.lang.String,java.lang.Class>	getOptions() Returns an unmodifiable map of the options supported by this endpont.
int	getPendingWriteDataSize() returns the size of the data which have already been written, but not yet transferred to the underlying socket.
java.net.InetAddress	getRemoteAddress() returns the address of the remote host of the underlying connection.
int	getRemotePort() returns the port of the remote host of the underlying connection.
void	init(IIoHandlerCallback callbackHandler) "starts" the handler.
boolean	isOpen() check, if the handler (underlying connection) is open.
void	resumeRead() resume reading data from the underlying subsystem
void	setConnectionTimeoutSec(int timeout) sets the connection timout.
void	setIdleTimeoutSec(int timeout) sets the idle timeout.
void	setOption(java.lang.String name, java.lang.Object value) set a option
void	suspendRead() suspend reading data from the underlying subsystem
void	writeOutgoing(java.nio.ByteBuffer buffer) non-blocking write.
void	writeOutgoing(java.util.LinkedList<java.nio.ByteBuffer> buffers) non-blocking write.

Method Detail

init

void init(IIoHandlerCallback callbackHandler)
          throws java.io.IOException

"starts" the handler. Callback methods will not be called before this method has been performed.

Parameters:

callbackHandler - the callback handler

Throws:

java.io.IOException

getLocalAddress

java.net.InetAddress getLocalAddress()

returns the local address of the underlying connection.

Returns:

the local address of the underlying connection

getLocalPort

int getLocalPort()

returns the local port of the underlying connection.

Returns:

the local port of the underlying connection

getRemoteAddress

java.net.InetAddress getRemoteAddress()

returns the address of the remote host of the underlying connection.

Returns:

the address of the remote host of the underlying connection

getRemotePort

int getRemotePort()

returns the port of the remote host of the underlying connection.

Returns:

the port of the remote host of the underlying connection

setIdleTimeoutSec

void setIdleTimeoutSec(int timeout)

sets the idle timeout.

Parameters:

timeout - the idle timeout

getId

java.lang.String getId()

return a unique conection id

Returns:

unique conection is

setConnectionTimeoutSec

void setConnectionTimeoutSec(int timeout)

sets the connection timout.

Parameters:

timeout - the connection timeout

getConnectionTimeoutSec

int getConnectionTimeoutSec()

returns the connection timeout.

Returns:

the connection timeout

getIdleTimeoutSec

int getIdleTimeoutSec()

returns the idle timeout.

Returns:

the idle timeout

getOption

java.lang.Object getOption(java.lang.String name)
                           throws java.io.IOException

returns the vlaue of a option

Parameters:

name - the name of the option

Returns:

the value of the option

Throws:

java.io.IOException - In an I/O error occurs

getOptions

java.util.Map<java.lang.String,java.lang.Class> getOptions()

Returns an unmodifiable map of the options supported by this endpont. The key in the returned map is the name of a option, and its value is the type of the option value. The returned map will never contain null keys or values.

Returns:

An unmodifiable map of the options supported by this channel

setOption

void setOption(java.lang.String name,
               java.lang.Object value)
               throws java.io.IOException

set a option

Parameters:

name - the option name

value - the option value

Throws:

java.io.IOException - In an I/O error occurs

isOpen

boolean isOpen()

check, if the handler (underlying connection) is open.

Returns:

true, if the handler is open

close

void close(boolean immediate)
           throws java.io.IOException

non-blocking close of the handler.

The implementation has to be threadsafe

Parameters:

immediate - if true, close the connection immediate. If false remaining out buffers (collected by the writOutgoing methods) has to written before closing

Throws:

java.io.IOException - If some other I/O error occurs

writeOutgoing

void writeOutgoing(java.nio.ByteBuffer buffer)
                   throws ClosedConnectionException,
                          java.io.IOException

non-blocking write. Because the IIoHandler is free to write the given buffer within a backgound avtivity, the caller can`t reuse the buffer, util the IIoHandlerCallback#onWritten(IOException) call back method has been called.

Parameters:

buffer - the data to add into the out buffer

Throws:

ClosedConnectionException - if the underlying connection is already closed

java.io.IOException - If some other I/O error occurs

writeOutgoing

void writeOutgoing(java.util.LinkedList<java.nio.ByteBuffer> buffers)
                   throws ClosedConnectionException,
                          java.io.IOException

non-blocking write. Because the IIoHandler is free to write the given buffers within a backgound avtivity, the caller can`t reuse the buffers, util the IIoHandlerCallback#onWritten(IOException) call back method has been called.

Parameters:

buffers - the datas to add into the out buffer

Throws:

ClosedConnectionException - if the underlying connection is already closed

java.io.IOException - If some other I/O error occurs

getPendingWriteDataSize

int getPendingWriteDataSize()

returns the size of the data which have already been written, but not yet transferred to the underlying socket.

Returns:

the size of the pending data to write

suspendRead

void suspendRead()
                 throws java.io.IOException

suspend reading data from the underlying subsystem

Throws:

java.io.IOException - If some other I/O error occurs

resumeRead

void resumeRead()
                throws java.io.IOException

resume reading data from the underlying subsystem

Throws:

java.io.IOException - If some other I/O error occurs

drainIncoming

java.util.LinkedList<java.nio.ByteBuffer> drainIncoming()

drains the handler`s read buffer. Because the buffers can be store temporally by the connection and accessed later, the passed over buffers are not subject of reuse.
This method will only be called within the same thread, which performs the IIoHandlerCallback.onDataRead() method.

 Example Stacktrace:  
 [DataReaderThread]
  <IIoHandler>.drainIncomming()
  <IIoHandlerCallback>.onDataRead()
  ...
 

Returns:

the content of the handler`s read buffer