de.gsi.dataset.serializer

Interface IoBufferHeader<C extends IoBufferHeader<C>>

Type Parameters:

C - generic type for inheriting self (fluent-design)

All Known Subinterfaces:

IoBuffer

All Known Implementing Classes:

ByteBuffer, FastByteBuffer

public interface IoBufferHeader<C extends IoBufferHeader<C>>

Interface definition in line with the jdk Buffer abstract class. This definition is needed to allow to redirect and allow for different buffer implementations.

A buffer is a linear, finite sequence of elements of a specific primitive type. Aside from its content, the essential properties of a buffer are its capacity, limit, and position:

A buffer's capacity is the number of elements it contains. The capacity of a buffer is never negative and never changes.

A buffer's limit is the index of the first element that should not be read or written. A buffer's limit is never negative and is never greater than its capacity.

A buffer's position is the index of the next element to be read or written. A buffer's position is never negative and is never greater than its limit.

The following invariant holds for the mark, position, limit, and capacity values:

0 <= position <= limit <= capacity

Author:

rstein

Method Summary

Modifier and Type	Method and Description
int	capacity()
C	clear() Clears this buffer.
C	ensureAdditionalCapacity(long capacity)
C	ensureCapacity(long capacity)
C	forceCapacity(long length, long preserve) Forces buffer to contain the given number of entries, preserving just a part of the array.
boolean	hasRemaining()
boolean	isReadOnly()
long	limit()
C	limit(int newLimit) Sets this buffer's limit.
ReadWriteLock	lock() For efficiency/performance reasons the buffer implementation is not required to safe-guard each put/get method independently.
long	position()
C	position(long newPosition) Sets this buffer's position.
long	remaining()
C	reset() resets the buffer read/write position to zero
C	trim() Trims the internal buffer array so that the capacity is equal to the size.
C	trim(int requestedCapacity) Trims the internal buffer array if it is too large.

Method Detail

capacity

int capacity()

Returns:

the capacity of this buffer

clear

C clear()

Clears this buffer. The position is set to zero amd the limit is set to the capacity.

Invoke this method before using a sequence of channel-read or put operations to fill this buffer. For example:

 buf.clear(); // Prepare buffer for reading
 in.read(buf); // Read data
 

This method does not actually erase the data in the buffer, but it is named as if it did because it will most often be used in situations in which that might as well be the case.

Returns:

itself (fluent design)

ensureAdditionalCapacity

C ensureAdditionalCapacity(long capacity)

ensureCapacity

C ensureCapacity(long capacity)

forceCapacity

C forceCapacity(long length,
                long preserve)

Forces buffer to contain the given number of entries, preserving just a part of the array.

Parameters:

length - the new minimum length for this array.

preserve - the number of elements of the old buffer that shall be preserved in case a new allocation is necessary.

Returns:

itself (fluent design)

hasRemaining

boolean hasRemaining()

Returns:

true if, and only if, there is at least one element remaining in this buffer

isReadOnly

boolean isReadOnly()

Returns:

true if, and only if, this buffer is read-only

limit

long limit()

Returns:

the limit of this buffer

limit

C limit(int newLimit)

Sets this buffer's limit. If the position is larger than the new limit then it is set to the new limit. If the mark is defined and larger than the new limit then it is discarded.

Parameters:

newLimit - the new limit value; must be non-negative and no larger than this buffer's capacity

Returns:

itself (fluent design)

lock

ReadWriteLock lock()

For efficiency/performance reasons the buffer implementation is not required to safe-guard each put/get method independently. Thus the user-code should acquire the given lock around a set of put/get appropriately.

Returns:

the read-write lock

position

long position()

Returns:

the position of this buffer

position

C position(long newPosition)

Sets this buffer's position. If the mark is defined and larger than the new position then it is discarded.

Parameters:

newPosition - the new position value; must be non-negative and no larger than the current limit

Returns:

itself (fluent design)

remaining

long remaining()

Returns:

the number of elements remaining in this buffer

reset

C reset()

resets the buffer read/write position to zero

Returns:

itself (fluent design)

trim

C trim()

Trims the internal buffer array so that the capacity is equal to the size.

Returns:

itself (fluent design)

See Also:

ArrayList.trimToSize()

trim

C trim(int requestedCapacity)

Trims the internal buffer array if it is too large. If the current array length is smaller than or equal to n, this method does nothing. Otherwise, it trims the array length to the maximum between requestedCapacity and capacity().

This method is useful when reusing FastBuffers. Clearing a list leaves the array length untouched. If you are reusing a list many times, you can call this method with a typical size to avoid keeping around a very large array just because of a few large transient lists.

Parameters:

requestedCapacity - the threshold for the trimming.

Returns:

itself (fluent design)