Interface IBuffer
- All Known Subinterfaces:
InternalBuffer
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.
Buffers may be obtained from an IBufferProvider, but implementations are not required to have been provided
by one. The current owner must call release() when processing is complete; release relinquishes ownership
and lets the implementation return storage to a provider, invoke an external release action, or free resources.
Release does not promise that the same buffer will be pooled or reused. A released buffer must no longer be used
through this interface. A previously returned ByteBuffer is a separate reference and is not revoked by a
buffer state check, so callers must stop accessing it before releasing the buffer.
In addition to its payload data each Net4j frame 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. A transport that uses message
boundaries must preserve this complete frame as the unit passed between the transport and Net4j; WebSocket message
boundaries are transport-specific and do not replace the Net4j header. The payload data may be accessed
through a ByteBuffer.
This interface is not intended to be implemented by clients.
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();
- Author:
- Eike Stepper
- See Also:
- 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
FieldsModifier and TypeFieldDescriptionstatic final intstatic final intstatic final shortstatic final shortstatic final shortstatic final shortPossible argument value ofstartPutting(short)and possible return value ofgetChannelID()that indicates that this buffer is not intended to be passed to aSocketChannel.static final intstatic final int -
Method Summary
Modifier and TypeMethodDescriptionvoidclear()Resets a live buffer for another read or write operation.voidcompact()voidflip()formatContent(boolean showHeader) byteget()voidget(byte[] dst) Deprecated.Returns theByteBufferthat can be used for putting or getting data.shortReturns the capacity of this buffer.shortReturns the channel index value stored in the header of this buffer.org.eclipse.net4j.util.IErrorHandlerintgetInt()intgetLimit()intshortgetShort()getState()Returns the current lifecycle and access state of this buffer.booleanbooleanisCCAM()Returns the Close Channel After Me flag.booleanisEOS()Returns the End Of Stream flag to indicate whether this buffer is the last buffer in a stream (typically a signal) of buffers.voidput(byte b) voidput(byte[] src, int offset, int length) voidputShort(short value) voidrelease()Relinquishes ownership of this buffer and releases its associated resources.voidsetCCAM(boolean ccam) Sets the Close Channel After Me flag.voidsetEOS(boolean eos) Sets the End Of Stream flag to indicate whether this buffer is the last buffer in a stream (typically a signal) of buffers.voidsetErrorHandler(org.eclipse.net4j.util.IErrorHandler errorHandler) voidsetLimit(int limit) voidsetPosition(int position) startGetting(SocketChannel socketChannel) Tries to read aByteBufferfrom aSocketChannelthat can be used for getting data.startPutting(short channelID) Returns aByteBufferthat can be used for putting data.booleanwrite(SocketChannel socketChannel) Tries to write the data of this buffer to aSocketChannel.
-
Field Details
-
NO_CHANNEL
static final short NO_CHANNELPossible argument value ofstartPutting(short)and possible return value ofgetChannelID()that indicates that this buffer is not intended to be passed to aSocketChannel.- See Also:
-
MIN_CHANNEL
static final short MIN_CHANNEL- Since:
- 2.0
- See Also:
-
MAX_CHANNEL
static final short MAX_CHANNEL- Since:
- 2.0
- See Also:
-
CHANNEL_ID_BYTES
static final int CHANNEL_ID_BYTES- Since:
- 4.8
- See Also:
-
PAYLOAD_SIZE_BYTES
static final int PAYLOAD_SIZE_BYTES- Since:
- 4.8
- See Also:
-
HEADER_SIZE
static final short HEADER_SIZE- See Also:
-
CHANNEL_ID_POS
static final int CHANNEL_ID_POS- Since:
- 4.10
- See Also:
-
PAYLOAD_SIZE_POS
static final int PAYLOAD_SIZE_POS- Since:
- 4.10
- See Also:
-
-
Method Details
-
getBufferProvider
Deprecated.Buffers are not required to originate from anIBufferProvider. Userelease()to relinquish ownership without assuming that the buffer belongs to a provider.Returns theIBufferProviderthat provided this buffer, ornullif the buffer was not provided by a buffer provider. -
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.For buffers obtained from an
IBufferProvider, this is normally equal to the provider's buffer capacity. -
getState
BufferState getState()Returns the current lifecycle and access state of this buffer. Implementations may reject operations that are invalid for that state; this does not invalidate aByteBufferreference previously returned to a caller. -
startGetting
Tries to read aByteBufferfrom aSocketChannelthat 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
SocketChannelnullis returned and the state of this buffer isREADING_HEADER. If it was not possible to read a complete body from theSocketChannelnullis returned and the state of this buffer isREADING_BODY.If a
ByteBufferis returned it may only be used for getting data. It is left to the responsibility of the caller that only the following methods of thatByteBufferare used:-
ByteBuffer.get() -
ByteBuffer.get(byte[]) -
ByteBuffer.get(int) -
ByteBuffer.get(byte[], int, int) -
ByteBuffer.getChar() -
ByteBuffer.getChar(int) -
ByteBuffer.getDouble() -
ByteBuffer.getDouble(int) -
ByteBuffer.getFloat() -
ByteBuffer.getFloat(int) -
ByteBuffer.getInt() -
ByteBuffer.getInt(int) -
ByteBuffer.getLong() -
ByteBuffer.getLong(int) -
ByteBuffer.getShort() -
ByteBuffer.getShort(int) - all other methods that do not influence
Buffer.position(),Buffer.limit()andBuffer.capacity()
- Parameters:
socketChannel- ThesocketChannelto read theByteBufferfrom.- Returns:
- A
ByteBufferthat can be used for getting data if it was possible to completely read the data from the givenSocketChannel,nullotherwise. - Throws:
IllegalStateException- If the state of this buffer is notINITIAL,READING_HEADERorREADING_BODY.IOException- If theSocketChannelhas been closed or discovers other I/O problems.
-
-
startPutting
Returns aByteBufferthat can be used for putting data.Turns the
stateof this buffer intoPUTTING.The returned
ByteBuffermay only be used for putting data. It is left to the responsibility of the caller that only the following methods of thatByteBufferare used:-
ByteBuffer.put(byte) -
ByteBuffer.put(byte[]) -
ByteBuffer.put(ByteBuffer) -
ByteBuffer.put(int, byte) -
ByteBuffer.put(byte[], int, int) -
ByteBuffer.putChar(char) -
ByteBuffer.putChar(int, char) -
ByteBuffer.putDouble(double) -
ByteBuffer.putDouble(int, double) -
ByteBuffer.putFloat(float) -
ByteBuffer.putFloat(int, float) -
ByteBuffer.putInt(int) -
ByteBuffer.putInt(int, int) -
ByteBuffer.putLong(long) -
ByteBuffer.putLong(int, long) -
ByteBuffer.putShort(short) -
ByteBuffer.putShort(int, short) - all other methods that do not influence
Buffer.position(),Buffer.limit()andBuffer.capacity()
- Parameters:
channelID- The index of anIChannelthat this buffer is intended to be passed to later orNO_CHANNEL.- Returns:
- A
ByteBufferthat can be used for putting data. - Throws:
IllegalStateException- If the state of this buffer is notINITIAL(PUTTINGis allowed but meaningless if and only if the givenchannelIDis equal to the existingchannelIDof this buffer).
-
-
write
Tries to write the data of this buffer to aSocketChannel.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
SocketChannelfalseis returned and the state of this buffer remainsWRITING.- Parameters:
socketChannel- ThesocketChannelto write the data to.- Returns:
trueif it was possible to completely write the data to theSocketChannel,falseotherwise.- Throws:
IllegalStateException- If the state of this buffer is notPUTTINGorWRITING.IOException- If theSocketChannelhas been closed or discovers other I/O problems.
-
flip
- Throws:
IllegalStateException- If the state of this buffer is notPUTTING.
-
getByteBuffer
Returns theByteBufferthat can be used for putting or getting data.- Throws:
IllegalStateException- If the state of this buffer is notPUTTINGorGETTING.
-
isEOS
boolean isEOS()Returns the End Of Stream flag to indicate whether this buffer is the last buffer in a stream (typically a signal) 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 (typically a signal) of buffers. -
isCCAM
boolean isCCAM()Returns the Close Channel After Me flag.- Since:
- 4.4
-
setCCAM
void setCCAM(boolean ccam) Sets the Close Channel After Me flag.- Since:
- 4.4
-
release
void release()Relinquishes ownership of this buffer and releases its associated resources. Implementations may return the buffer to a provider, release an externally owned resource, or perform another appropriate cleanup action. -
clear
void clear()Resets a live buffer for another read or write operation. This is a reuse operation, not an ownership release: it does not return storage to a provider or invoke an external release action. Implementations may reject clearing a terminally disposed buffer. -
formatContent
-
getErrorHandler
org.eclipse.net4j.util.IErrorHandler getErrorHandler()- Since:
- 2.0
-
setErrorHandler
void setErrorHandler(org.eclipse.net4j.util.IErrorHandler errorHandler) - Since:
- 2.0
-
compact
void compact()- Since:
- 4.7
-
getPosition
int getPosition()- Since:
- 4.7
-
setPosition
void setPosition(int position) - Since:
- 4.7
-
getLimit
int getLimit()- Since:
- 4.7
-
setLimit
void setLimit(int limit) - Since:
- 4.7
-
hasRemaining
boolean hasRemaining()- Since:
- 4.7
-
get
byte get()- Since:
- 4.7
-
get
void get(byte[] dst) - Since:
- 4.7
-
getShort
short getShort()- Since:
- 4.7
-
getInt
int getInt()- Since:
- 4.7
-
getString
String getString()- Since:
- 4.7
-
put
void put(byte b) - Since:
- 4.7
-
put
void put(byte[] src, int offset, int length) - Since:
- 4.7
-
putShort
void putShort(short value) - Since:
- 4.7
-
IBufferProvider.