MultiByteBuffer
Class name: com.datashyft.core.model.util.MultiByteBuffer
A wrapper for a series of java.nio.ByteBuffer objects that allows them to be treated as a single continuous buffer when reading them. This allows an application to access more than the 2GB of data supported by a single ByteBuffer.
The MultiByteBuffer class mimics the interface of the ByteBuffer class. It tracks the position within the data, the total amount of data, as well as allowing marking and rewinding of the position within the file. The class only implements the read accessors for data, however. It does not support modifying the underlying data.
A MultiByteBuffer can be created to wrap existing ByteBuffers by providing the ByteBuffers to the constructor of the class. The MultiByteBuffer will duplicate all of the passed in ByteBuffers to ensure that the position and limit variables are kept independent. Modifying any of the ByteBuffers that are passed into the object will change the data contained in the MultiByteBuffer.
In addition to wrapping existing data, a MultiByteBuffer can be created directly from a File object. The content of the file is memory mapped and the mapped ByteBuffers are used to create a new MultiByteBuffer instance.
public MultiByteBuffer(ByteBuffer buffer)
Creates a MultiByteBuffer instance that uses the content of the specified ByteBuffer as its backing data.
Parameters:
buffer - ByteBuffer containing the data that is backing this object.
public MultiByteBuffer(ByteBuffer[] buffers)
Creates a MultiByteBuffer instance that uses the content of the specified ByteBuffers as its backing data. The data is accessed in the order the ByteBuffers occur in the array.
Parameters:
buffers - An array of ByteBuffers containing the data that will back this object. The data is accessed in the order the ByteBuffers are stored in the array.
public MultiByteBuffer(List<ByteBuffer> buffers)
Creates a MultiByteBuffer instance that uses the content of the specified ByteBuffers as its backing data. The data is accessed in the order the ByteBuffers occur in the list.
Parameters:
buffers - A list of ByteBuffers containing the data that will back this object. The data is accessed in the order the ByteBuffers are stored in the list.
public long limit()
Returns this buffer's limit.
Returns:
The limit of this buffer.
public long position()
Returns this buffer's position.
Returns:
The position of this buffer.
public MultiByteBuffer position(long newPosition) throws IllegalArgumentException
Set's this buffer's position. If the mark is defined and larger than the new position, it is discarded.
Parameters:
newPosition - The new position value; must be non-negative and no larger than the current limit.
Returns:
This buffer
Throws:
IllegalArgumentException - If the preconditions on newPosition do not hold.
public MultiByteBuffer mark()
Sets this buffer's mark at the current position.
Returns:
This buffer
public MultiByteBuffer reset()
throws InvalidMarkException
Resets this buffer's position to the previously marked position.
Invoking this method neither changes nor discards the mark's value.
Returns:
This buffer
Throws:
InvalidMarkException - If the mark has not been set.
public MultiByteBuffer rewind()
Rewinds this buffer. The position is set to zero and the mark is discarded.
Returns:
This buffer
public long remaining()
Returns the number of bytes between the current position and the limit.
Returns:
The number of bytes remaining in this buffer.
public boolean hasRemaining()
Tells whether there are any bytes between the current position and the limit.
Returns:
true if, and only if, there is at least one byte remaining in this buffer
public byte get() throws BufferUnderflowException
Relative get method. Reads the byte at this buffer's current position, and then increments its position.
Returns:
The byte at the buffer's current position.
Throws:
BufferUnderflowException - If the buffer's current position is not smaller than its limit
public short getShort() throws BufferUnderflowException
Relative get method for reading a short value. Reads the next two bytes at this buffer's current position, composing them into a short value, and then increments the position by two.
Returns:
The short value at the buffer's current position.
Throws:
BufferUnderflowException - If there are fewer than two bytes remaining in the buffer.
public int getInt() throws BufferUnderflowException
Relative get method for reading an int value.
Reads the next four bytes at this buffer's current position, composing them into an int value, and then increments the position by four.
Returns:
The int value at the buffer's current position
Throws:
BufferUnderflowException - If there are fewer than four bytes remaining in this buffer
public long getLong() throws BufferUnderflowException
Relative get method for reading a long value.
Reads the next eight bytes at this buffer's current position, composing them into a long value, and then increments the position by eight.
Returns:
The long value at the buffer's current position
Throws:
BufferUnderflowException - If there are fewer than eight bytes remaining in this buffer
public float getFloat() throws BufferUnderflowException
Relative get method for reading a float value.
Reads the next four bytes at this buffer's current position, composing them into a float value, and then increments the position by four.
Returns:
The float value at the buffer's current position
Throws:
BufferUnderflowException - - If there are fewer than four bytes remaining in this buffer
public double getDouble() throws BufferUnderflowException
Relative get method for reading a double value. Reads the next eight bytes at this buffer's current position, composing them into a double value according to the current byte order, and then increments the position by eight.
Returns:
The double value at the buffer's current position
Throws:
BufferUnderflowException - If there are fewer than eight bytes remaining in this buffer
public char getChar() throws BufferUnderflowException
Relative get method for reading a char value.
Reads the next two bytes at this buffer's current position, composing them into a char value, and then increments the position by two.
Returns:
The char value at the buffer's current position
Throws:
BufferUnderflowException - If there are fewer than two bytes remaining in this buffer
public void get(byte[] dst) throws BufferUnderflowException
Relative bulk get method.
This method transfers bytes from this buffer into the given destination array. An invocation of this method of the form src.get(a) behaves in exactly the same way as the invocation
src.get(a, 0, a.length)
Parameters:
dst - The byte array into which the data is to be written.
Throws:
BufferUnderflowException - If there are fewer than length bytes remaining in this buffer
public void get(byte[] dst, int offset, int length) throws BufferUnderflowException
Relative bulk get method. This method transfers bytes from this buffer into the given destination array. If there are fewer bytes remaining in the buffer than are required to satisfy the request, that is, if length > remaining(), then no bytes are transferred and a BufferUnderflowException is thrown.
Otherwise, this method copies length bytes from this buffer into the given array, starting at the current position of this buffer and at the given offset in the array. The position of this buffer is then incremented by length.
In other words, an invocation of this method of the form src.get(dst, off, len) has exactly the same effect as the loop
for (int i = off; i < off + len; i++) dst[i] = src.get();
except that it first checks that there are sufficient bytes in this buffer and it is potentially much more efficient.
Parameters:
dst - The array into which bytes are to be written
offset - The offset within the array of the first byte to be written; must be non-negative and no larger than dst.length
length - The maximum number of bytes to be written to the given array; must be non-negative and no larger than dst.length - offset
Throws:
BufferUnderflowException - If there are fewer than length bytes remaining in this buffer
IndexOutOfBoundsException - If the preconditions on the offset and length parameters do not hold
public ByteBuffer get(int maxData) throws IllegalArgumentException
Returns a ByteBuffer starting at the current position and whose length is, at maximum, maxData. At minimum, this will return a 1 byte ByteBuffer, or an empty ByteBuffer if there is no data left, or if maxData is 0.
Parameters:
maxData - the maximum amount of data to return
Returns:
The ByteBuffer containing the data to be returned
Throws:
IllegalArgumentException - if maxData is negative
public MultiByteBuffer slice()
Creates a new byte buffer whose content is a shared subsequence of this buffer's content.
The content of the new buffer will start at this buffer's current position. Changes to this buffer's content will be visible in the new buffer, and vice versa; the two buffers' position, limit, and mark values will be independent.
The new buffer's position will be zero, its capacity and its limit will be the number of bytes remaining in this buffer, and its mark will be undefined. The new buffer will be read-only if, and only if, this buffer is read-only.
Returns:
The new buffer
public MultiByteBuffer duplicate()
Creates a new byte buffer that shares this buffer's content.
The content of the new buffer will be that of this buffer. Changes to this buffer's content will be visible in the new buffer, and vice versa; the two buffers' position, limit, and mark values will be independent.
The new buffer's capacity, limit, position, and mark values will be identical to those of this buffer. The new buffer will be read-only if, and only if, this buffer is read-only.
Returns:
The new byte buffer
public MultiByteBuffer asReadOnlyBuffer()
Creates a new, read-only byte buffer that shares this buffer's content. The content of the new buffer will be that of this buffer. Changes to this buffer's content will be visible in the new buffer; the new buffer itself, however, will be read-only and will not allow the shared content to be modified. The two buffers' position, limit, and mark values will be independent. The new buffer's limit, position, and mark values will be identical to those of this buffer. If this buffer is itself read-only then this method behaves in exactly the same way as the duplicate method.
Returns:
The new, read-only byte buffer
public static MultiByteBuffer concat(MultiByteBuffer... mbbs)
Creates a new MultiByteBuffer by concatenating the given MultiByteBuffers
Parameters:
mbbs - the buffers to concatenate
Returns:
a new MultiByteBuffer containing the concatenated buffers
public boolean equals(Object other)
Tells whether or not this buffer is equal to another object. Two MultiByteBuffers are equal if, and only if,
1. They have the same number of remaining elements, and
2. The two sequences of remaining elements, considered independently of their starting positions, are pointwise equal.
A MultiByteBuffer is not equal to any other type of object.
Parameters:
other - The object to which this buffer is to be compared
Returns:
true if, and only if, this buffer is equal to the given object
public int hashCode()
Returns the current hash code of this buffer. The hash code of a multi byte buffer depends upon its content, position, and limit.
Because buffer hash codes are content- and state-dependent, it is inadvisable to use buffers as keys in hash maps or similar data structures.
Returns:
The current hash code of this buffer
public static MultiByteBuffer fromFile(File file) throws IOException
Constructs a new MultiByteBuffer from the content of the specified file. The file content will be memory mapped and the resulting memory mapped ByteBuffers used to construct a MultiByteBuffer.
Parameters:
file - The file whose content is to be used to create this MultiByteBuffer
Returns:
A MultiByteBuffer instance that access the content of the specified file.
Throws:
IOException - If there is an exception accessing the file
IllegalArgumentException - If the File is null.