com.bigdata.btree.raba
Interface IRaba

All Superinterfaces:

Iterable<byte[]>

All Known Subinterfaces:

ICodedRaba

All Known Implementing Classes:

AbstractCodedRaba, AbstractKeyBuffer, AbstractRaba, CanonicalHuffmanRabaCoder.CodedRabaImpl, EmptyRaba, EmptyRaba.EmptyKeysRaba, EmptyRaba.EmptyValuesRaba, MutableKeyBuffer, MutableKeysRaba, MutableValueBuffer, MutableValuesRaba, ReadOnlyKeysRaba, ReadOnlyValuesRaba

public interface IRaba
extends Iterable<byte[]>

Interface for random access to a logical byte[][]s. This is primarily used for B+Tree keys and values, but is also used when serializing keys and values for IIndexProcedures. The interface defines optional operations for mutation. If mutation is supported, then isReadOnly() will return false. An IRaba instance either stores B+Tree keys and supports search(byte[]) -or- stores B+Tree values and allows nulls but does not support search. for storing null s and search are mutually exclusive. Some IRaba implementations may be used for either purpose, but the IRaba instance is always either B+Tree keys or B+Tree values. In both cases, the IRaba stores variable length byte[]s. However, when an IRaba stores B+Tree keys, the byte[]s interpreted as unsigned byte[]s for the purpose of search(byte[]).

B+Tree keys

When used for B+Tree keys, the interface provides operations on an ordered set of variable length unsigned byte[] keys and nulls ARE NOT permitted.

B+Tree values

When used for B+Tree values, the interface provides operations on an unordered collection of variable length byte[]s, does NOT support search(byte[]) and nulls are allowed.

Version:

$Id: IRaba.java 2265 2009-10-26 12:51:06Z thompsonbry $

Author:

Bryan Thompson

TODO:

consider discarding all of the add(byte[]) methods. It is typically easier and more convenient to directly manage the existing MutableKeyBuffer and MutableValueBuffer. However, there are also MutableKeysRaba and MutableValueRaba implementations which are, I believe, only used by the ResultSet.

Method Summary

int	add(byte[] a) Append a byte[] value to the end of the logical byte[][] (optional operation).
int	add(byte[] value, int off, int len) Append a byte[] value to the end of the logical byte[][] (optional operation).
int	add(DataInput in, int len) Append a byte[] value to the end of the logical byte[][] (optional operation).
int	capacity() The capacity of the logical byte[][].
int	copy(int index, OutputStream os) Copy the value at the specified index onto the output stream.
byte[]	get(int index) Return the byte[] at the specified index.
boolean	isEmpty() True iff the logical byte[][] is empty.
boolean	isFull() True iff the logical byte[][] is full.
boolean	isKeys() When true the IRaba supports search and elements are interpreted as unsigned byte[]s (B+Tree keys).
boolean	isNull(int index) Return true iff the byte[] at that index is null.
boolean	isReadOnly() Return true if this implementation is read-only.
Iterator<byte[]>	iterator() Iterator visits the byte[] elements in the view order.
int	length(int index) The length of the byte[] at that index.
int	search(byte[] searchKey) Search for the given searchKey in the key buffer (optional operation).
void	set(int index, byte[] a) Set the byte[] value at the specified index (optional operation).
int	size() The #of entries in the logical byte[][].

Method Detail

isReadOnly

boolean isReadOnly()

Return true if this implementation is read-only.

isKeys

boolean isKeys()

When true the IRaba supports search and elements are interpreted as unsigned byte[]s (B+Tree keys). For this case the application MUST ensure that the elements are maintained in unsigned byte[] order and that duplicates byte[]s are not stored.

When false, the IRaba allows nulls and the elements are interpreted as signed byte[] (B+Tree values).

Returns:

true if the IRaba represents B+Tree keys and false if it represents B+Tree values.

capacity

int capacity()

The capacity of the logical byte[][].

TODO:

Coded rabas generally impose capacity == size while only mutable rabas have a sense of capacity GTE size. Some of the unit tests assume that all rabas are dimensions based on the branching factor, which is no longer true. By moving this method onto the mutable IRaba implementations we would uncover those assumptions and clean things up a bit more.

size

int size()

The #of entries in the logical byte[][].

isEmpty

boolean isEmpty()

True iff the logical byte[][] is empty.

isFull

boolean isFull()

True iff the logical byte[][] is full.

isNull

boolean isNull(int index)

Return true iff the byte[] at that index is null. If isKeys() would return true then this method MUST return false since nulls are not permitted for B+Tree keys.

Parameters:

index - The index in [0:size()-1].

Throws:

IndexOutOfBoundsException - unless index is in [0:size()-1].

length

int length(int index)

The length of the byte[] at that index.

Parameters:

index - The index in [0:size()-1].

Returns:

The length of the byte[] at that index.

Throws:

NullPointerException - if the key at that index is null.

IndexOutOfBoundsException - unless index is in [0:size()-1].

get

byte[] get(int index)

Return the byte[] at the specified index. For greater efficiency, implementations MAY return a reference to an internal the byte[].

Parameters:

index - The index in [0:size()-1].

Returns:

The byte[] value at that index and null if a null value was stored at that index.

Throws:

IndexOutOfBoundsException - unless index is in [0:size()-1].

copy

int copy(int index,
         OutputStream os)

Copy the value at the specified index onto the output stream. This is often used with an ByteArrayBuffer so that the same backing byte[] can be overwritten by each visited key.

Parameters:

index - The index in [0:size()-1].

out - The output stream onto which the key will be copied.

Returns:

The #of bytes copied.

Throws:

IndexOutOfBoundsException - unless index is in [0:size()-1].

NullPointerException - if the byte[] value at that index is null.

RuntimeException - if the OutputStream throws an IOException (generally the OutputStream is writing onto a byte[] so it is more convenient to masquerade this exception).

iterator

Iterator<byte[]> iterator()

Iterator visits the byte[] elements in the view order. If an element is null, then the iterator will report a null for that element.

Specified by:

iterator in interface Iterable<byte[]>

set

void set(int index,
         byte[] a)

Set the byte[] value at the specified index (optional operation).

Parameters:

index - The index in [0:size()-1].

a - The byte[] value.

Throws:

IndexOutOfBoundsException - unless index is in [0:size()-1].

IllegalArgumentException - if the value is null and null values are not supported by this implementation.

add

int add(byte[] a)

Append a byte[] value to the end of the logical byte[][] (optional operation).

Parameters:

a - A value.

Returns:

The #of values in the logical byte[][] (postcondition).

Throws:

IllegalArgumentException - if the value is null and null values are not supported by this implementation.

add

int add(byte[] value,
        int off,
        int len)

Append a byte[] value to the end of the logical byte[][] (optional operation).

Parameters:

value - A value

off - The offset of the first byte to be copied.

len - The #of bytes to be copied.

Returns:

The #of values in the logical byte[][] (postcondition).

Throws:

IllegalArgumentException - if the value is null.

add

int add(DataInput in,
        int len)
        throws IOException

Append a byte[] value to the end of the logical byte[][] (optional operation).

Parameters:

in - The input stream from which the byte[] will be read.

len - The #of bytes to be read.

Returns:

The #of values in the logical byte[][] (postcondition).

Throws:

IllegalArgumentException - if in is null.

IOException

TODO:

also define variant of set(int, byte[]) that copies bytes from an input stream?

search

int search(byte[] searchKey)

Search for the given searchKey in the key buffer (optional operation). Whether or not search is supported depends on whether the logical byte[][] is ordered. However, the efficiency of search, where supported, depends on the implementation. Some implementations support binary search of the coded byte[] values. Others may require a mixture of binary and linear search, etc.

 entryIndex = -entryIndex - 1
 

or just

 entryIndex = -entryIndex
 

if you are looking for the first key after the searchKey.

Parameters:

searchKey - The search key.

Returns:

index of the search key, if it is found; otherwise, (-(insertion point) - 1). The insertion point is defined as the point at which the key would be inserted. Note that this guarantees that the return value will be >= 0 if and only if the key is found.

Throws:

IllegalArgumentException - if the searchKey is null.

UnsupportedOperationException - if search is not supported.