net.sf.mmm.util.io.api
Interface ByteArray

All Superinterfaces:

ByteProvider

All Known Subinterfaces:

ByteArrayBuffer

All Known Implementing Classes:

AbstractByteArray, ByteArrayBufferImpl, ByteArrayImpl, DetectorStreamBufferImpl.CurrentByteArray, PooledByteArray

public interface ByteArray
extends ByteProvider

This is the interface for some object that holds a byte-array together with a range where the user of this interface may start and end reading in that array.
A ByteArray is similar to ByteBuffer. However it is a lot simpler, has an interface as API and can permit modifying indices.
ATTENTION:
Unfortunately there is no way in java to give a read-only view on a byte[] than can be iterated as efficient. Unlike many APIs of the JDK this interface trusts the user NOT to modify the underlying byte-array and therefore avoids arraycopy overhead.

Since:

1.1.0

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

See Also:

ByteArrayImpl

Method Summary

ByteArray	createSubArray(int minimum, int maximum) This method creates a new ByteArray with the same bytes but the given indices.
byte[]	getBytes() This method gets the underlying byte-array of this buffer.
int	getBytesAvailable() This method gets the number of bytes available in this array.
int	getCurrentIndex() This method gets the offset in the byte array.
int	getMaximumIndex() This method gets the maximum index in the buffer.
int	getMinimumIndex() This method gets the minimum index where to start reading in the byte array.

Method Detail

getBytes

byte[] getBytes()

This method gets the underlying byte-array of this buffer. You are only permitted to read the content from minimumIndex (typically currentIndex to maximumIndex. Only the creator of this object may modify this array.

Returns:

the buffer

See Also:

getCurrentIndex(), getMaximumIndex()

getMinimumIndex

int getMinimumIndex()

This method gets the minimum index where to start reading in the byte array. It will be in the range from 0 to maximumIndex + 1. This is typically the same as the current index. However a mutable variant of a ByteArray may allow to modify (increase) the current-index. The value returned by this method can NOT be modified.

Returns:

the minimum index.

getCurrentIndex

int getCurrentIndex()

This method gets the offset in the byte array. It will be in the range from 0 to maximumIndex + 1.

Returns:

the offset in the byte array.

getMaximumIndex

int getMaximumIndex()

This method gets the maximum index in the buffer. It will be in the range from -1 to getBytes().length - 1.
A negative value (-1) indicates that the buffer does NOT contain data (payload).

Returns:

the maximumIndex

getBytesAvailable

int getBytesAvailable()

This method gets the number of bytes available in this array. In other words this method returns getMaximumIndex() - getCurrentIndex() + 1.

Specified by:

getBytesAvailable in interface ByteProvider

Returns:

the bytes left in this array.

createSubArray

ByteArray createSubArray(int minimum,
                         int maximum)

This method creates a new ByteArray with the same bytes but the given indices.
ATTENTION:
If the implementation is immutable and the given minimum and maximum index are both equal to the current indices of this ByteArray this method may return the instance itself ( this) rather than creating a new one.

Parameters:

minimum - is the minimumIndex and the currentIndex for the new ByteArray. It has to be greater or equal to the minimumIndex of this ByteArray.

maximum - is the maximumIndex for the new ByteArray.

Returns:

a new ByteArray with the given indices.