org.xsocket.connection
Interface INonBlockingConnection

All Superinterfaces:

Channel, Closeable, Flushable, GatheringByteChannel, IConnection, IDataSink, IDataSource, ReadableByteChannel, WritableByteChannel

All Known Implementing Classes:

NonBlockingConnection

public interface INonBlockingConnection
extends IConnection, IDataSource, IDataSink, GatheringByteChannel, ReadableByteChannel, WritableByteChannel, Flushable

A connection which accesses the underlying channel in a non-blocking manner.

Author:

grro@xsocket.org

Nested Class Summary

Nested classes/interfaces inherited from interface org.xsocket.connection.IConnection

IConnection.FlushMode

Field Summary

static int

UNLIMITED

Fields inherited from interface org.xsocket.connection.IConnection

DEFAULT_AUTOFLUSH, DEFAULT_CONNECTION_TIMEOUT_MILLIS, DEFAULT_FLUSH_MODE, DEFAULT_IDLE_TIMEOUT_MILLIS, INITIAL_DEFAULT_ENCODING, MAX_TIMEOUT_MILLIS, SO_KEEPALIVE, SO_LINGER, SO_RCVBUF, SO_REUSEADDR, SO_SNDBUF, SO_TIMEOUT, TCP_NODELAY

Method Summary

void	activateSecuredMode() ad hoc activation of a secured mode (SSL).
int	available() get the number of available bytes to read
void	deactivateSecuredMode() ad hoc deactivation of a secured mode (SSL).
void	flush() flush the send buffer.
String	getEncoding() gets the encoding (used by string related methods like write(String) ...)
IConnection.FlushMode	getFlushmode() return the flush mode
IHandler	getHandler() gets the connection handler
int	getMaxReadBufferThreshold() get the max app read buffer size.
int	getPendingWriteDataSize() returns the size of the data which have already been written, but not yet transferred to the underlying socket.
int	getReadBufferVersion() get the version of read buffer.
Executor	getWorkerpool() return the worker pool which is used to process the call back methods
int	getWriteTransferRate() gets the send delay time.
int	indexOf(String str) Returns the index of the first occurrence of the given string.
int	indexOf(String str, String encoding) Returns the index of the first occurrence of the given string.
boolean	isAutoflush() get autoflush
boolean	isOpen() return if the data source is open.
boolean	isReceivingSuspended() returns true if receiving is suspended
boolean	isSecure() returns if the connection is in secured mode
boolean	isSecuredModeActivateable() returns if secured mode is activateable
void	markReadPosition() Marks the read position in the connection.
void	markWritePosition() Marks the write position in the connection.
ByteBuffer[]	readByteBufferByDelimiter(String delimiter, String encoding) read a ByteBuffer by using a delimiter.
ByteBuffer[]	readByteBufferByDelimiter(String delimiter, String encoding, int maxLength) read a ByteBuffer by using a delimiter For performance reasons, the ByteBuffer readByteBuffer method is generally preferable to get bytes
byte[]	readBytesByDelimiter(String delimiter, String encoding) read a byte array by using a delimiter For performance reasons, the ByteBuffer readByteBuffer method is generally preferable to get bytes
byte[]	readBytesByDelimiter(String delimiter, String encoding, int maxLength) read a byte array by using a delimiter For performance reasons, the ByteBuffer readByteBuffer method is generally preferable to get bytes
String	readStringByDelimiter(String delimiter, String encoding) read a string by using a delimiter
String	readStringByDelimiter(String delimiter, String encoding, int maxLength) read a string by using a delimiter
String	readStringByLength(int length, String encoding) read a string by using a length definition
void	removeReadMark() remove the read mark
void	removeWriteMark() remove the write mark
boolean	resetToReadMark() Resets to the marked read position.
boolean	resetToWriteMark() Resets to the marked write position.
void	resumeReceiving() resume receiving data from the underlying subsystem
void	setAutoflush(boolean autoflush) set autoflush.
void	setEncoding(String encoding) sets the encoding (used by string related methods like write(String) ...)
void	setFlushmode(IConnection.FlushMode flushMode) sets the flush mode.
void	setHandler(IHandler handler) set the connection handler.
void	setMaxReadBufferThreshold(int size) set the max app read buffer threshold
void	setWorkerpool(Executor workerpool) sets the worker pool which is used to process the call back methods
void	setWriteTransferRate(int bytesPerSecond) set the send delay time.
void	suspendReceiving() suspend receiving data from the underlying subsystem
long	transferFrom(FileChannel source) transfer the data of the file channel to this data sink
void	unread(byte[] bytes) returns the bytes to the top of the read queue.
void	unread(ByteBuffer buffer) returns the ByteBuffer to the top of the read queue.
void	unread(ByteBuffer[] buffers) returns the ByteBuffers to the top of the read queue.
void	unread(String text) returns the text to the top of the read queue.
void	write(byte[] bytes, int offset, int length, IWriteCompletionHandler writeCompletionHandler) writes bytes to the data sink.
void	write(byte[] bytes, IWriteCompletionHandler writeCompletionHandler) writes bytes to the data sink.
void	write(ByteBuffer[] srcs, int offset, int length, IWriteCompletionHandler writeCompletionHandler) writes a byte buffer array.
void	write(ByteBuffer[] buffers, IWriteCompletionHandler writeCompletionHandler) writes a byte buffer array.
void	write(ByteBuffer buffer, IWriteCompletionHandler writeCompletionHandler) writes a byte buffer.
void	write(List<ByteBuffer> buffers, IWriteCompletionHandler writeCompletionHandler) writes a list of bytes to the data sink.
int	write(String message, String encoding) write a message
void	write(String message, String encoding, IWriteCompletionHandler writeCompletionHandler) writes a message.

Methods inherited from interface org.xsocket.connection.IConnection

getAttachment, getConnectionTimeoutMillis, getId, getIdleTimeoutMillis, getLocalAddress, getLocalPort, getOption, getOptions, getRemainingMillisToConnectionTimeout, getRemainingMillisToIdleTimeout, getRemoteAddress, getRemotePort, isServerSide, setAttachment, setConnectionTimeoutMillis, setIdleTimeoutMillis, setOption

Methods inherited from interface org.xsocket.IDataSource

read, readByte, readByteBufferByDelimiter, readByteBufferByDelimiter, readByteBufferByLength, readBytesByDelimiter, readBytesByDelimiter, readBytesByLength, readDouble, readInt, readLong, readShort, readStringByDelimiter, readStringByDelimiter, readStringByLength, transferTo

Methods inherited from interface org.xsocket.IDataSink

transferFrom, transferFrom, write, write, write, write, write, write, write, write, write, write, write, write

Methods inherited from interface java.nio.channels.GatheringByteChannel

write, write

Methods inherited from interface java.nio.channels.WritableByteChannel

write

Methods inherited from interface java.nio.channels.ReadableByteChannel

read

Field Detail

UNLIMITED

static final int UNLIMITED

See Also:

Constant Field Values

Method Detail

setHandler

void setHandler(IHandler handler)
                throws IOException

set the connection handler.

Parameters:

handler - the handler

Throws:

IOException - If some other I/O error occurs

getHandler

IHandler getHandler()

gets the connection handler

Returns:

the handler

getEncoding

String getEncoding()

gets the encoding (used by string related methods like write(String) ...)

Returns:

the encoding

setEncoding

void setEncoding(String encoding)

sets the encoding (used by string related methods like write(String) ...)

Parameters:

encoding - the encoding

setAutoflush

void setAutoflush(boolean autoflush)

set autoflush. If autoflush is activated, each write call will cause a flush.

Parameters:

autoflush - true if autoflush should be activated

isAutoflush

boolean isAutoflush()

get autoflush

Returns:

true, if autoflush is activated

flush

void flush()
           throws ClosedChannelException,
                  IOException,
                  SocketTimeoutException

flush the send buffer. The method call will block until the outgoing data has been flushed into the underlying os-specific send buffer.

Specified by:

flush in interface Flushable

Throws:

IOException - If some other I/O error occurs

SocketTimeoutException - If the timeout has been reached

ClosedChannelException - if the underlying channel is closed

isSecuredModeActivateable

boolean isSecuredModeActivateable()

returns if secured mode is activateable

Returns:

true, if secured mode is activateable

activateSecuredMode

void activateSecuredMode()
                         throws IOException

ad hoc activation of a secured mode (SSL). By performing of this method all remaining data to send will be flushed. After this all data will be sent and received in the secured mode

Throws:

IOException - If some other I/O error occurs

deactivateSecuredMode

void deactivateSecuredMode()
                           throws IOException

ad hoc deactivation of a secured mode (SSL). By performing of this method all remaining data to send will be flushed. After this all data will be sent and received in the plain mode

Throws:

IOException - If some other I/O error occurs

isSecure

boolean isSecure()

returns if the connection is in secured mode

Returns:

true, if the connection is in secured mode

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

suspendReceiving

void suspendReceiving()
                      throws IOException

suspend receiving data from the underlying subsystem

Throws:

IOException - If some other I/O error occurs

resumeReceiving

void resumeReceiving()
                     throws IOException

resume receiving data from the underlying subsystem

Throws:

IOException - If some other I/O error occurs

isReceivingSuspended

boolean isReceivingSuspended()

returns true if receiving is suspended

Returns:

true, if receiving is suspended

write

int write(String message,
          String encoding)
          throws IOException,
                 BufferOverflowException

write a message

Parameters:

message - the message to write

encoding - the encoding which should be used th encode the chars into byte (e.g. `US-ASCII` or `UTF-8`)

Returns:

the number of written bytes

Throws:

BufferOverflowException - If the no enough space is available

IOException - If some other I/O error occurs

write

void write(ByteBuffer[] buffers,
           IWriteCompletionHandler writeCompletionHandler)
           throws IOException

writes a byte buffer array. Typically this write mthod will be used in async flush mode

Parameters:

buffers - the buffers to write

writeCompletionHandler - the completionHandler

Throws:

IOException - If some I/O error occurs

write

void write(ByteBuffer buffer,
           IWriteCompletionHandler writeCompletionHandler)
           throws IOException

writes a byte buffer. Typically this write mthod will be used in async flush mode

Parameters:

buffer - the buffer to write

writeCompletionHandler - the completionHandler

Throws:

IOException - If some I/O error occurs

write

void write(ByteBuffer[] srcs,
           int offset,
           int length,
           IWriteCompletionHandler writeCompletionHandler)
           throws IOException

writes a byte buffer array. Typically this write mthod will be used in async flush mode

Parameters:

srcs - the buffers

offset - the offset

length - the length

writeCompletionHandler - the completionHandler

Throws:

IOException - If some I/O error occurs

write

void write(List<ByteBuffer> buffers,
           IWriteCompletionHandler writeCompletionHandler)
           throws IOException

writes a list of bytes to the data sink. Typically this write mthod will be used in async flush mode

Parameters:

buffers - the bytes to write

writeCompletionHandler - the completionHandler

Throws:

BufferOverflowException - If the no enough space is available

IOException - If some other I/O error occurs

write

void write(byte[] bytes,
           IWriteCompletionHandler writeCompletionHandler)
           throws IOException

writes bytes to the data sink. Typically this write mthod will be used in async flush mode

Parameters:

bytes - the bytes to write

writeCompletionHandler - the completion handler

Throws:

BufferOverflowException - If the no enough space is available

IOException - If some other I/O error occurs

write

void write(byte[] bytes,
           int offset,
           int length,
           IWriteCompletionHandler writeCompletionHandler)
           throws IOException

writes bytes to the data sink. Typically this write mthod will be used in async flush mode

Parameters:

bytes - the bytes to write

offset - the offset of the sub array to be used; must be non-negative and no larger than array.length. The new buffer`s position will be set to this value.

length - the length of the sub array to be used; must be non-negative and no larger than array.length - offset. The new buffer`s limit will be set to offset + length.

writeCompletionHandler - the completion handler

Throws:

BufferOverflowException - If the no enough space is available

IOException - If some other I/O error occurs

write

void write(String message,
           String encoding,
           IWriteCompletionHandler writeCompletionHandler)
           throws IOException

writes a message. Typically this write mthod will be used in async flush mode

Parameters:

message - the message to write

encoding - the encoding which should be used th encode the chars into byte (e.g. `US-ASCII` or `UTF-8`)

writeCompletionHandler - the completion handler

Throws:

BufferOverflowException - If the no enough space is available

IOException - If some other I/O error occurs

unread

void unread(ByteBuffer[] buffers)
            throws IOException

returns the ByteBuffers to the top of the read queue.

Parameters:

buffers - the buffers to return

Throws:

IOException - if an exception occurs

unread

void unread(ByteBuffer buffer)
            throws IOException

returns the ByteBuffer to the top of the read queue.

Parameters:

buffer - the buffer to return

Throws:

IOException - if an exception occurs

unread

void unread(byte[] bytes)
            throws IOException

returns the bytes to the top of the read queue.

Parameters:

bytes - the bytes to return

Throws:

IOException - if an exception occurs

unread

void unread(String text)
            throws IOException

returns the text to the top of the read queue.

Parameters:

text - the text to return

Throws:

IOException - if an exception occurs

readByteBufferByDelimiter

ByteBuffer[] readByteBufferByDelimiter(String delimiter,
                                       String encoding)
                                       throws IOException,
                                              BufferUnderflowException

read a ByteBuffer by using a delimiter. The default encoding will be used to decode the delimiter For performance reasons, the ByteBuffer readByteBuffer method is generally preferable to get bytes

Parameters:

delimiter - the delimiter

encoding - the encoding to use

Returns:

the ByteBuffer

Throws:

BufferUnderflowException - If not enough data is available

IOException - If some other I/O error occurs

readByteBufferByDelimiter

ByteBuffer[] readByteBufferByDelimiter(String delimiter,
                                       String encoding,
                                       int maxLength)
                                       throws IOException,
                                              BufferUnderflowException,
                                              MaxReadSizeExceededException

read a ByteBuffer by using a delimiter For performance reasons, the ByteBuffer readByteBuffer method is generally preferable to get bytes

Parameters:

delimiter - the delimiter

encoding - the encoding of the delimiter

maxLength - the max length of bytes that should be read. If the limit is exceeded a MaxReadSizeExceededException will been thrown

Returns:

the ByteBuffer

Throws:

BufferUnderflowException - If not enough data is available

MaxReadSizeExceededException - If the max read length has been exceeded and the delimiter hasn�t been found

IOException - If some other I/O error occurs

readBytesByDelimiter

byte[] readBytesByDelimiter(String delimiter,
                            String encoding)
                            throws IOException,
                                   BufferUnderflowException

read a byte array by using a delimiter For performance reasons, the ByteBuffer readByteBuffer method is generally preferable to get bytes

Parameters:

delimiter - the delimiter

encoding - the encoding to use

Returns:

the read bytes

Throws:

BufferUnderflowException - If not enough data is available

IOException - If some other I/O error occurs

readBytesByDelimiter

byte[] readBytesByDelimiter(String delimiter,
                            String encoding,
                            int maxLength)
                            throws IOException,
                                   BufferUnderflowException,
                                   MaxReadSizeExceededException

read a byte array by using a delimiter For performance reasons, the ByteBuffer readByteBuffer method is generally preferable to get bytes

Parameters:

delimiter - the delimiter

encoding - the encoding to use

maxLength - the max length of bytes that should be read. If the limit is exceeded a MaxReadSizeExceededException will been thrown

Returns:

the read bytes

Throws:

BufferUnderflowException - If not enough data is available

MaxReadSizeExceededException - If the max read length has been exceeded and the delimiter hasn�t been found

IOException - If some other I/O error occurs

readStringByDelimiter

String readStringByDelimiter(String delimiter,
                             String encoding)
                             throws IOException,
                                    BufferUnderflowException,
                                    UnsupportedEncodingException,
                                    MaxReadSizeExceededException

read a string by using a delimiter

Parameters:

delimiter - the delimiter

encoding - the encoding to use

Returns:

the string

Throws:

MaxReadSizeExceededException - If the max read length has been exceeded and the delimiter hasn�t been found

IOException - If some other I/O error occurs

BufferUnderflowException - If not enough data is available

UnsupportedEncodingException - if the given encoding is not supported

readStringByDelimiter

String readStringByDelimiter(String delimiter,
                             String encoding,
                             int maxLength)
                             throws IOException,
                                    BufferUnderflowException,
                                    UnsupportedEncodingException,
                                    MaxReadSizeExceededException

read a string by using a delimiter

Parameters:

delimiter - the delimiter

encoding - the encoding to use

maxLength - the max length of bytes that should be read. If the limit is exceeded a MaxReadSizeExceededException will been thrown

Returns:

the string

Throws:

BufferUnderflowException - If not enough data is available

MaxReadSizeExceededException - If the max read length has been exceeded and the delimiter hasn�t been found

IOException - If some other I/O error occurs

UnsupportedEncodingException - If the given encoding is not supported

readStringByLength

String readStringByLength(int length,
                          String encoding)
                          throws IOException,
                                 BufferUnderflowException,
                                 UnsupportedEncodingException

read a string by using a length definition

Parameters:

length - the amount of bytes to read.

encoding - the encoding to use

Returns:

the string

Throws:

IOException - If some other I/O error occurs

BufferUnderflowException - If not enough data is available

UnsupportedEncodingException - if the given encoding is not supported

IllegalArgumentException, - if the length parameter is negative

transferFrom

long transferFrom(FileChannel source)
                  throws IOException,
                         BufferOverflowException

transfer the data of the file channel to this data sink

Specified by:

transferFrom in interface IDataSink

Parameters:

source - the source channel

Returns:

the number of transfered bytes

Throws:

BufferOverflowException - If the no enough space is available

IOException - If some other I/O error occurs

indexOf

int indexOf(String str)
            throws IOException

Returns the index of the first occurrence of the given string.

Parameters:

str - any string

Returns:

if the string argument occurs as a substring within this object, then the index of the first character of the first such substring is returned; if it does not occur as a substring, -1 is returned.

Throws:

IOException - If some other I/O error occurs

indexOf

int indexOf(String str,
            String encoding)
            throws IOException

Returns the index of the first occurrence of the given string.

Parameters:

str - any string

encoding - the encoding to use

Returns:

if the string argument occurs as a substring within this object, then the index of the first character of the first such substring is returned; if it does not occur as a substring, -1 is returned.

Throws:

IOException - If some other I/O error occurs

MaxReadSizeExceededException - If the max read length has been exceeded and the delimiter hasn�t been found

setWriteTransferRate

void setWriteTransferRate(int bytesPerSecond)
                          throws ClosedChannelException,
                                 IOException

set the send delay time. Data to write will be buffered internally and be written to the underlying subsystem based on the given write rate. The write methods will not block for this time.
By default the write transfer rate is set with UNLIMITED

Reduced write transfer is only supported for FlushMode.ASYNC. see INonBlockingConnection#setFlushmode(org.xsocket.connection.IConnection.FlushMode))

Parameters:

bytesPerSecond - the transfer rate of the outgoing data

Throws:

ClosedChannelException - If the underlying socket is already closed

IOException - If some other I/O error occurs

getWriteTransferRate

int getWriteTransferRate()
                         throws ClosedChannelException,
                                IOException

gets the send delay time.

Returns:

the transfer rate of the outgoing data

Throws:

ClosedChannelException - If the underlying socket is already closed

IOException - If some other I/O error occurs

available

int available()
              throws IOException

get the number of available bytes to read

Returns:

the number of available bytes, possibly zero, or -1 if the channel has reached end-of-stream

Throws:

IOException

getReadBufferVersion

int getReadBufferVersion()
                         throws IOException

get the version of read buffer. The version number increases, if the read buffer queue has been modified

Returns:

the version of the read buffer

Throws:

IOException - If some other I/O error occurs

isOpen

boolean isOpen()

return if the data source is open. Default is true

Specified by:

isOpen in interface Channel

Specified by:

isOpen in interface IConnection

Returns:

true, if the data source is open

getWorkerpool

Executor getWorkerpool()

return the worker pool which is used to process the call back methods

Returns:

the worker pool

setWorkerpool

void setWorkerpool(Executor workerpool)

sets the worker pool which is used to process the call back methods

Parameters:

workerpool - the workerpool

resetToWriteMark

boolean resetToWriteMark()

Resets to the marked write position. If the connection has been marked, then attempt to reposition it at the mark.

Returns:

true, if reset was successful

resetToReadMark

boolean resetToReadMark()

Resets to the marked read position. If the connection has been marked, then attempt to reposition it at the mark.

Returns:

true, if reset was successful

markWritePosition

void markWritePosition()

Marks the write position in the connection.

markReadPosition

void markReadPosition()

Marks the read position in the connection. Subsequent calls to resetToReadMark() will attempt to reposition the connection to this point.

removeReadMark

void removeReadMark()

remove the read mark

removeWriteMark

void removeWriteMark()

remove the write mark

getMaxReadBufferThreshold

int getMaxReadBufferThreshold()

get the max app read buffer size. If the read buffer size exceeds this limit the connection will stop receiving data. The read buffer size can be higher the limit (max size = maxReadBufferThreshold + socket read buffer size * 2)

Returns:

the max read buffer threshold

setMaxReadBufferThreshold

void setMaxReadBufferThreshold(int size)

set the max app read buffer threshold

Parameters:

maxSize - the max read buffer threshold

setFlushmode

void setFlushmode(IConnection.FlushMode flushMode)

sets the flush mode. If the flush mode is set toASYNC (default is SYNC), the data will be transferred to the underlying connection in a asynchronous way.

By using the WritableByteChannel interface methods write(ByteBuffer) and write(ByteBuffer[]) some restriction exits. Calling such a write method in mode ASYNC causes that the byte buffer will be read asynchronously by the internal I/O thread. If the byte buffer will be accessed (reused) after calling the write method, race conditions will occur. The write(ByteBuffer) and write(ByteBuffer[]) should only called in ASNC mode, if the byte buffer will not be accessed (reused) after the write operation. E.g.

 
   File file = new File(filename);
   RandomAccessFile raf = new RandomAccessFile(file, "r");
   ReadableByteChannel fc = raf.getChannel();
  
   INonBlockingConnection connection = new NonBlockingConnection(host, port);

   // using a copy buffer (which will be reused for the read operations) 
   // requires FlushMode SYNC which is default (for writing)!  
   ByteBuffer copyBuffer = ByteBuffer.allocate(4096); 
   
   int read = 0;
   while (read >= 0) {
      // read channel
      read = fc.read(copyBuffer);
      copyBuffer.flip();
      
      if (read > 0) {
         // write channel
         connection.write(copyBuffer);
         if (copyBuffer.hasRemaining()) {
            copyBuffer.compact();
         } else {
            copyBuffer.clear();
         }
      }
   }
 

Parameters:

flushMode - FlushMode#ASYNC if flush should be performed asynchronous, FlushMode#SYNC if flush should be perform synchronous

getFlushmode

IConnection.FlushMode getFlushmode()

return the flush mode

Returns:

the flush mode