com.sun.labs.minion.util.buffer
Class ArrayBuffer

java.lang.Object
  com.sun.labs.minion.util.buffer.StdBufferImpl
      com.sun.labs.minion.util.buffer.ArrayBuffer

All Implemented Interfaces:

Buffer, ReadableBuffer, WriteableBuffer, java.lang.Cloneable

public class ArrayBuffer
extends StdBufferImpl
implements java.lang.Cloneable

A buffer class for reading and writing that is backed by a growable array of bytes.

This implementation is suitable for use in postings types.

See Also:

Postings

Field Summary

protected int	increaseFactor The increase factor to use when resizing the buffer.
protected int	lim The limit of the units array, i.e., the last byte that can be read.
protected static java.lang.String	logTag A tag to use in logging.
protected int	off The offset of the units array where the buffer we're representing starts.
protected int	pos The position in the array where the next byte will be written or read.
protected byte[]	units The array backing our data.

Fields inherited from class com.sun.labs.minion.util.buffer.StdBufferImpl

masks, maxBEValues, maxValues, nBits

Constructor Summary

protected	ArrayBuffer() Creates an array backed buffer that we can use when duplicating or slicing.
	ArrayBuffer(byte[] units) Creates an buffer backed by the given array.
	ArrayBuffer(byte[] units, int off, int length) Creates an buffer backed by the given array.
	ArrayBuffer(int n) Creates an array backed buffer with the given initial capacity.

Method Summary

WriteableBuffer	append(ReadableBuffer b, int n) Appends a given number of bytes from a readable buffer onto this buffer.
int	byteDecode() Decodes an integer stored using the 7 bit encoding.
int	byteEncode(long n) Encodes an integer in a byte-aligned fashion, using the minimal number of bytes.
WriteableBuffer	capacity(int n) Sets the capacity of the buffer to the given amount.
protected void	checkBounds(int p) Checks whether the given position is outside our array bounds.
java.lang.Object	clone() Clones this buffer.
ReadableBuffer	duplicate() Duplicates this buffer, so that it can be used safely by other readers.
byte	get() Gets the next byte from this buffer.
byte	get(int i) Gets a byte from this buffer at the given position.
ReadableBuffer	getReadableBuffer() Gets a readable buffer from this writeable one.
int	limit() The limit of this buffer, i.e., the last readable position.
void	limit(int l) Sets the limit of this buffer, i.e., the last readable position.
static void	main(java.lang.String[] args) A test program that will encode and decode random integers.
WriteableBuffer	or(ReadableBuffer b) Computes the logical OR of this buffer and another.
int	position() Gets the position in the buffer.
void	position(int position) Sets the position in the buffer.
WriteableBuffer	put(byte b) Puts a single byte onto this buffer.
WriteableBuffer	put(byte[] b, int o, int n) Puts a number of bytes onto this buffer.
WriteableBuffer	put(int p, byte b) Puts a single byte onto this buffer at the given position.
int	remaining() Gets the amount of space remaining in the buffer.
ReadableBuffer	slice(int p, int s) Slices this buffer so that a sub-buffer can be used.
void	write(java.nio.ByteBuffer b) Write the buffer to a new IO buffer.
void	write(java.io.DataOutput o) Write the buffer to a data output.
void	write(java.io.OutputStream os) Writes the buffer to a stream.
void	write(java.nio.channels.WritableByteChannel chan) Write the buffer to a channel.
WriteableBuffer	xor(ReadableBuffer b) Computes the logical XOR of this buffer and another.

Methods inherited from class com.sun.labs.minion.util.buffer.StdBufferImpl

append, byteDecode, byteDecode, byteDecodeLong, byteDecodeLong, byteDecodeLong, byteEncode, byteEncode, bytesRequired, byteToBinaryString, clear, countBits, countBits, decodeFloat, encode, encode, getString, set, sizeUTF8, skipByteEncoded, test, toString, toString, toString

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

units

protected byte[] units

The array backing our data.

increaseFactor

protected int increaseFactor

The increase factor to use when resizing the buffer. Initially we will double the size of the buffer, but at each increase in size we will double the increase factor.

pos

protected int pos

The position in the array where the next byte will be written or read. This is an absolute position in the array. When reading, we may be given a position that is relative to the beginning of a sliced buffer: we'll account for that later.

off

protected int off

The offset of the units array where the buffer we're representing starts. This is used only when reading a buffer that has been sliced. When writing, it will always be 0.

lim

protected int lim

The limit of the units array, i.e., the last byte that can be read. This is relative to the offset of the beginning of the buffer! This is used only when reading a buffer that has been explicitly limited. When writing it will always be the length of the units array.

logTag

protected static java.lang.String logTag

A tag to use in logging.

Constructor Detail

ArrayBuffer

protected ArrayBuffer()

Creates an array backed buffer that we can use when duplicating or slicing.

ArrayBuffer

public ArrayBuffer(int n)

Creates an array backed buffer with the given initial capacity.

Parameters:

n - The initial capacity of the buffer.

ArrayBuffer

public ArrayBuffer(byte[] units)

Creates an buffer backed by the given array. This should be used only when creating an entry for reading!

Parameters:

units - The array with which to back the buffer. This array is used as provided, so changes to it will affect the buffer.

ArrayBuffer

public ArrayBuffer(byte[] units,
                   int off,
                   int length)

Creates an buffer backed by the given array. This should be used only when creating an entry for reading!

Parameters:

units - The array with which to back the buffer. This array is used as provided, so changes to it will affect the buffer.

off - The position in the given array where the buffer should start.

length - The number of bytes that should be in the buffer.

Method Detail

checkBounds

protected void checkBounds(int p)

Checks whether the given position is outside our array bounds. If it is, we expand so that it is not.

Parameters:

p - The position that we want to check.

position

public int position()

Gets the position in the buffer. This is with respect to any offset gotten from a sliced buffer.

Specified by:

position in interface Buffer

Returns:

The position in the buffer.

position

public void position(int position)

Sets the position in the buffer.

Specified by:

position in interface Buffer

Parameters:

position - The point to which the buffer's position should be set.

remaining

public int remaining()

Gets the amount of space remaining in the buffer. This is the limit of the buffer minus the current position.

Specified by:

remaining in interface Buffer

Returns:

The number of bytes remaining in the buffer.

capacity

public WriteableBuffer capacity(int n)

Sets the capacity of the buffer to the given amount.

Specified by:

capacity in interface WriteableBuffer

Parameters:

n - The number of bytes that the buffer must be able to store.

Returns:

The buffer, for chained invocations.

put

public WriteableBuffer put(byte b)

Puts a single byte onto this buffer.

Specified by:

put in interface WriteableBuffer

Parameters:

b - The byte to put on the buffer

Returns:

This buffer, to allow chained invocations.

put

public WriteableBuffer put(int p,
                           byte b)

Puts a single byte onto this buffer at the given position.

Specified by:

put in interface WriteableBuffer

Parameters:

p - The position where the byte should be put.

b - The byte to put on the buffer

Returns:

This buffer, to allow chained invocations.

byteEncode

public int byteEncode(long n)

Encodes an integer in a byte-aligned fashion, using the minimal number of bytes. The basic idea: use the 7 lower order bits of a byte to encode a number. If the 8th bit is 0, then there are no further bytes in this number. If the 8th bit is one, then the next byte continues the number. Note that this means that a number that would completly fill an integer will take 5 bytes to encode.

Specified by:

byteEncode in interface WriteableBuffer

Overrides:

byteEncode in class StdBufferImpl

Parameters:

n - The number to encode.

Returns:

the number of bytes used to encode the number.

put

public WriteableBuffer put(byte[] b,
                           int o,
                           int n)

Puts a number of bytes onto this buffer.

Parameters:

b - An array from which we'll take the bytes.

o - The offset in the array at which we'll start.

n - The number of bytes to take.

Returns:

This buffer, to allow chained invocations.

append

public WriteableBuffer append(ReadableBuffer b,
                              int n)

Appends a given number of bytes from a readable buffer onto this buffer.

Specified by:

append in interface WriteableBuffer

Overrides:

append in class StdBufferImpl

Parameters:

b - The buffer that we wish to append onto this buffer.

n - The number of bytes to append onto this buffer.

Returns:

The buffer, to allow chained invocations.

or

public WriteableBuffer or(ReadableBuffer b)

Computes the logical OR of this buffer and another.

Specified by:

or in interface WriteableBuffer

Parameters:

b - The buffer to or with this one.

Returns:

The buffer, to allow chained invocations.

xor

public WriteableBuffer xor(ReadableBuffer b)

Computes the logical XOR of this buffer and another.

Specified by:

xor in interface WriteableBuffer

Parameters:

b - The buffer to or with this one.

Returns:

The buffer, to allow chained invocations.

write

public void write(java.nio.ByteBuffer b)

Write the buffer to a new IO buffer. We use the buffer's bulk put method to do so efficiently.

Specified by:

write in interface WriteableBuffer

Parameters:

b - The java.nio buffer onto which we will write this buffer.

See Also:

ByteBuffer.put(byte[],int,int)

write

public void write(java.nio.channels.WritableByteChannel chan)
           throws java.io.IOException

Write the buffer to a channel. The buffer is converted to a ByteBuffer and then written to the channel.

Specified by:

write in interface WriteableBuffer

Parameters:

chan - The channel to which the buffer should be written.

Throws:

java.io.IOException - If there is any error writing to the channel.

write

public void write(java.io.DataOutput o)
           throws java.io.IOException

Write the buffer to a data output. The underlying array is written using the write method of DataOutput.

Specified by:

write in interface WriteableBuffer

Parameters:

o - The output to which the buffer will be written.

Throws:

java.io.IOException - If there is any error writing the buffer.

write

public void write(java.io.OutputStream os)
           throws java.io.IOException

Writes the buffer to a stream.

Specified by:

write in interface WriteableBuffer

Parameters:

os - The stream to which the buffer should be written.

Throws:

java.io.IOException - If there is any error writing the buffer.

getReadableBuffer

public ReadableBuffer getReadableBuffer()

Gets a readable buffer from this writeable one. The readable buffer will share the representation with the buffer that generated it.

Specified by:

getReadableBuffer in interface WriteableBuffer

Returns:

A version of this buffer as a readable buffer.

duplicate

public ReadableBuffer duplicate()

Duplicates this buffer, so that it can be used safely by other readers.

Specified by:

duplicate in interface ReadableBuffer

Returns:

A new readable buffer that shares the underlying representation with this buffer.

slice

public ReadableBuffer slice(int p,
                            int s)

Slices this buffer so that a sub-buffer can be used.

Specified by:

slice in interface ReadableBuffer

Parameters:

p - The position at which the buffer should be sliced.

s - The number of bytes that should be in the sliced buffer.

Returns:

A new readable buffer that shares the underlying representation with this buffer.

limit

public int limit()

The limit of this buffer, i.e., the last readable position.

Specified by:

limit in interface Buffer

Returns:

The position of the last byte that can be read from or written to this buffer.

limit

public void limit(int l)

Sets the limit of this buffer, i.e., the last readable position.

Specified by:

limit in interface Buffer

Parameters:

l - The limit that we wish to set.

get

public byte get()

Gets the next byte from this buffer.

Specified by:

get in interface ReadableBuffer

Returns:

The byte at the current position. The position will then be advanced.

get

public byte get(int i)

Gets a byte from this buffer at the given position. This position is relative to any any offset into the array that comes from being a slice of another buffer.

Specified by:

get in interface ReadableBuffer

Parameters:

i - The position from which we would like to get the byte.

Returns:

The byte at the given position.

byteDecode

public int byteDecode()

Decodes an integer stored using the 7 bit encoding. This is a specialization of the general method that uses get for efficiency reasons.

Specified by:

byteDecode in interface ReadableBuffer

Overrides:

byteDecode in class StdBufferImpl

Returns:

the decoded int.

See Also:

byteEncode(long)

clone

public java.lang.Object clone()

Clones this buffer.

Overrides:

clone in class java.lang.Object

Returns:

A copy of this buffer. This copy will not share the underlying representation.

main

public static void main(java.lang.String[] args)
                 throws java.lang.Exception

A test program that will encode and decode random integers.

Parameters:

args - The arguments.

Throws:

java.lang.Exception - If there is any problem.