IBuffer (Net4j Signalling Platform Documentation)

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 channelID 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)
No Implement

This interface is not intended to be implemented by clients.

No Extend

This interface is not intended to be extended by clients.

Field Summary

Fields
Modifier and Type	Field and Description
`static short`	`HEADER_SIZE`
`static short`	`MAX_CHANNEL`
`static short`	`MIN_CHANNEL`
`static short`	`NO_CHANNEL` Possible argument value of `startPutting(short)` and possible return value of `getChannelID()` that indicates that this buffer is not intended to be passed to a `SocketChannel`.

Method Summary

Methods
Modifier and Type	Method and Description
`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`.
`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.
`ByteBuffer`	`getByteBuffer()` Returns the `ByteBuffer` that can be used for putting or getting data.
`short`	`getCapacity()` Returns the capacity of this buffer.
`short`	`getChannelID()` Returns the channel index value stored in the header of this buffer.
`IErrorHandler`	`getErrorHandler()`
`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.
`void`	`setErrorHandler(IErrorHandler errorHandler)`
`ByteBuffer`	`startGetting(SocketChannel socketChannel)` Tries to read a `ByteBuffer` from a `SocketChannel` that can be used for getting data.
`ByteBuffer`	`startPutting(short channelID)` Returns a `ByteBuffer` that can be used for putting data.
`boolean`	`write(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 getChannelID() that indicates that this buffer is not intended to be passed to a SocketChannel.
    
    See Also:
    Constant Field Values
  - MIN_CHANNEL
```
static final short MIN_CHANNEL
```
    Since:
    
    2.0
    
    See Also:
    Constant Field Values
  - MAX_CHANNEL
```
static final short MAX_CHANNEL
```
    Since:
    
    2.0
    
    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.
  - getChannelID
```
short getChannelID()
```
    Returns the channel index value stored in the header of this buffer.
    
    Since:
    
    2.0
  - 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
```
ByteBuffer startGetting(SocketChannel socketChannel)
                        throws IllegalStateException,
                               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:
    
    IllegalStateException - If the state of this buffer is not INITIAL, READING_HEADER or READING_BODY.
    
    IOException - If the SocketChannel has been closed or discovers other I/O problems.
  - startPutting
```
ByteBuffer startPutting(short channelID)
                        throws 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:
    channelID - 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:
    
    IllegalStateException - If the state of this buffer is not INITIAL (PUTTING is allowed but meaningless if and only if the given channelID is equal to the existing channelID of this buffer).
  - write
```
boolean write(SocketChannel socketChannel)
              throws IllegalStateException,
                     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:
    
    IllegalStateException - If the state of this buffer is not PUTTING or WRITING.
    
    IOException - If the SocketChannel has been closed or discovers other I/O problems.
  - flip
```
void flip()
          throws IllegalStateException
```
    Turns the state of this buffer from PUTTING into GETTING.
    
    Throws:
    
    IllegalStateException - If the state of this buffer is not PUTTING.
  - getByteBuffer
```
ByteBuffer getByteBuffer()
                         throws IllegalStateException
```
    Returns the ByteBuffer that can be used for putting or getting data.
    
    Throws:
    
    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
```
String formatContent(boolean showHeader)
```
  - getErrorHandler
```
IErrorHandler getErrorHandler()
```
    Since:
    
    2.0
  - setErrorHandler
```
void setErrorHandler(IErrorHandler errorHandler)
```
    Since:
    
    2.0

Interface IBuffer

Field Summary

Method Summary

Field Detail

NO_CHANNEL

MIN_CHANNEL

MAX_CHANNEL

HEADER_SIZE

Method Detail

getBufferProvider

getChannelID

getCapacity

getState

startGetting

startPutting

write

flip

getByteBuffer

isEOS

setEOS

release

clear

formatContent

getErrorHandler

setErrorHandler