org.eclipse.net4j.buffer
Interface IBuffer

All Known Subinterfaces:
InternalBuffer

public interface IBuffer

Basic unit of transport in Net4j.

A buffer is well prepared for the usage with asynchronous IChannels but can also be used with pure SocketChannels. All methods of IBuffer are non-blocking.

Usually buffers are obtained from a IBufferProvider. Buffers can be accessed, passed around and finally released to their original provider. The capacity of a buffer is determined by its provider.

In addition to its payload data each buffer contains an internal header of four bytes, two of them representing a channel identifier the other two of them denoting the length of the payload data. The payload data may be accessed through a ByteBuffer.

This interface is not intended to be implemented by clients.

Class Diagram:

State Machine Diagram:

An example for putting values into a buffer and writing it to a SocketChannel:

 // Obtain a fresh buffer
 Buffer buffer = bufferProvider.getBuffer(); // Start filling the buffer for channelIndex 4711 ByteBuffer byteBuffer =
 buffer.startPutting(4711); byteBuffer.putDouble(15.47); // Write the contents of the Buffer to a // SocketChannel
 without blocking while (!buffer.write(socketChannel)) { // Do something else } 
An example for reading a buffer from a SocketChannel and getting values from it:

 // Obtain a fresh buffer
 Buffer buffer = bufferProvider.getBuffer(); // Read the contents of the Buffer from a // SocketChannel without
 blocking ByteBuffer byteBuffer; while ((byteBuffer = buffer.startGetting(socketChannel)) == null) { // Do something
 else } // Access the contents of the buffer and // release it to its provider double value = byteBuffer.getDouble();
 buffer.release(); 

See Also:
IBufferProvider, IChannel.sendBuffer(IBuffer), IChannel.setReceiveHandler(IBufferHandler), IBufferHandler.handleBuffer(IBuffer)

Field Summary
static short HEADER_SIZE
           
static short NO_CHANNEL
          Possible argument value of startPutting(short) and possible return value of getChannelIndex() that indicates that this buffer is not intended to be passed to a SocketChannel.
 
Method Summary
 void clear()
          Turns the state of this buffer from any state into INITIAL.
 void flip()
          Turns the state of this buffer from PUTTING into GETTING.
 java.lang.String formatContent(boolean showHeader)
           
 IBufferProvider getBufferProvider()
          Returns the IBufferProvider that has provided this buffer and that this buffer will be returned to when its release() method is called.
 java.nio.ByteBuffer getByteBuffer()
          Returns the ByteBuffer that can be used for putting or getting data.
 short getCapacity()
          Returns the capacity of this buffer.
 short getChannelIndex()
          Returns the channel index value stored in the header of this buffer.
 BufferState getState()
          Returns the internal state of this buffer.
 boolean isEOS()
          Returns the End Of Stream flag to indicate whether this buffer is the last buffer in a stream of buffers.
 void release()
          Releases this buffer to its original IBufferProvider.
 void setEOS(boolean eos)
          Sets the End Of Stream flag to indicate whether this buffer is the last buffer in a stream of buffers.
 java.nio.ByteBuffer startGetting(java.nio.channels.SocketChannel socketChannel)
          Tries to read a ByteBuffer from a SocketChannel that can be used for getting data.
 java.nio.ByteBuffer startPutting(short channelIndex)
          Returns a ByteBuffer that can be used for putting data.
 boolean write(java.nio.channels.SocketChannel socketChannel)
          Tries to write the data of this buffer to a SocketChannel.
 

Field Detail

NO_CHANNEL

static final short NO_CHANNEL
Possible argument value of startPutting(short) and possible return value of getChannelIndex() that indicates that this buffer is not intended to be passed to a SocketChannel.

See Also:
Constant Field Values

HEADER_SIZE

static final short HEADER_SIZE
See Also:
Constant Field Values
Method Detail

getBufferProvider

IBufferProvider getBufferProvider()
Returns the IBufferProvider that has provided this buffer and that this buffer will be returned to when its release() method is called.


getChannelIndex

short getChannelIndex()
Returns the channel index value stored in the header of this buffer.


getCapacity

short getCapacity()
Returns the capacity of this buffer.

The capacity of this buffer is equal to the capacity of the IBufferProvider that has provided this buffer.


getState

BufferState getState()
Returns the internal state of this buffer.


startGetting

java.nio.ByteBuffer startGetting(java.nio.channels.SocketChannel socketChannel)
                                 throws java.lang.IllegalStateException,
                                        java.io.IOException
Tries to read a ByteBuffer from a SocketChannel that can be used for getting data.

This method is non-blocking and it can be necessary to repeatedly call it. If it was not possible to read a complete header from the SocketChannel null is returned and the state of this buffer is READING_HEADER. If it was not possible to read a complete body from the SocketChannel null is returned and the state of this buffer is READING_BODY.

If a ByteBuffer is returned it may only be used for getting data. It is left to the responsibility of the caller that only the following methods of that ByteBuffer are used:

Parameters:
socketChannel - The socketChannel to read the ByteBuffer from.
Returns:
A ByteBuffer that can be used for getting data if it was possible to completely read the data from the given SocketChannel, null otherwise.
Throws:
java.lang.IllegalStateException - If the state of this buffer is not INITIAL, READING_HEADER or READING_BODY.
java.io.IOException - If the SocketChannel has been closed or discovers other I/O problems.

startPutting

java.nio.ByteBuffer startPutting(short channelIndex)
                                 throws java.lang.IllegalStateException
Returns a ByteBuffer that can be used for putting data.

Turns the state of this buffer into PUTTING.

The returned ByteBuffer may only be used for putting data. It is left to the responsibility of the caller that only the following methods of that ByteBuffer are used:

Parameters:
channelIndex - The index of an IChannel that this buffer is intended to be passed to later or NO_CHANNEL .
Returns:
A ByteBuffer that can be used for putting data.
Throws:
java.lang.IllegalStateException - If the state of this buffer is not INITIAL (PUTTING is allowed but meaningless if and only if the given channelIndex is equal to the existing channelIndex of this buffer).

write

boolean write(java.nio.channels.SocketChannel socketChannel)
              throws java.lang.IllegalStateException,
                     java.io.IOException
Tries to write the data of this buffer to a SocketChannel.

This method is non-blocking and it can be necessary to repeatedly call it. If it was not possible to completely write the data to the SocketChannel false is returned and the state of this buffer remains WRITING.

Parameters:
socketChannel - The socketChannel to write the data to.
Returns:
true if it was possible to completely write the data to the SocketChannel, false otherwise.
Throws:
java.lang.IllegalStateException - If the state of this buffer is not PUTTING or WRITING.
java.io.IOException - If the SocketChannel has been closed or discovers other I/O problems.

flip

void flip()
          throws java.lang.IllegalStateException
Turns the state of this buffer from PUTTING into GETTING.

Throws:
java.lang.IllegalStateException - If the state of this buffer is not PUTTING.

getByteBuffer

java.nio.ByteBuffer getByteBuffer()
                                  throws java.lang.IllegalStateException
Returns the ByteBuffer that can be used for putting or getting data.

Throws:
java.lang.IllegalStateException - If the state of this buffer is not PUTTING or GETTING.

isEOS

boolean isEOS()
Returns the End Of Stream flag to indicate whether this buffer is the last buffer in a stream of buffers.


setEOS

void setEOS(boolean eos)
Sets the End Of Stream flag to indicate whether this buffer is the last buffer in a stream of buffers.


release

void release()
Releases this buffer to its original IBufferProvider.


clear

void clear()
Turns the state of this buffer from any state into INITIAL.


formatContent

java.lang.String formatContent(boolean showHeader)

Copyright (c) 2004 - 2008 Eike Stepper, Germany.
All Rights Reserved.