Interface Index

All Superinterfaces:

AutoCloseable, Closeable, View

public interface Index
extends View, Closeable

Mapping of keys to values, ordered by key, in lexicographical order. Although Java bytes are signed, they are treated as unsigned for ordering purposes. The natural order of an index cannot be changed.

See Also:

• Database

Method Summary

Modifier and Type	Method	Description
IndexStats	analyze(byte[] lowKey, byte[] highKey)	Estimates the size of this index with a single random probe.
<R> Table<R>	asTable(Class<R> type)	Returns a Table instance which stores rows in this index.
void	close()	Closes this index reference.
void	drop()	Fully closes and removes an empty index.
long	evict(Transaction txn, byte[] lowKey, byte[] highKey, Filter evictionFilter, boolean autoload)	Select a few entries, and delete them from the index.
long	id()
boolean	isClosed()
byte[]	name()
String	nameString()
boolean	verify(VerificationObserver observer, int numThreads)	Verifies the integrity of the index.

Methods inherited from interface View

comparator, count, count, delete, exchange, exists, insert, isEmpty, isModifyAtomic, isUnmodifiable, load, lockCheck, lockExclusive, lockShared, lockUpgradable, newAccessor, newCursor, newTransaction, ordering, remove, replace, store, touch, tryLockExclusive, tryLockShared, tryLockUpgradable, update, update, viewDifference, viewFiltered, viewGe, viewGt, viewIntersection, viewKeys, viewLe, viewLt, viewPrefix, viewReverse, viewTransformed, viewUnion, viewUnmodifiable

Modifier and Type	Method	Description
default Comparator<byte[]>	comparator()	Returns a key comparator for the ordering of this view, or null if unordered.
default long	count(byte[] lowKey, boolean lowInclusive, byte[] highKey, boolean highInclusive)	Non-transactionally counts the number of entries within the given range.
default long	count(byte[] lowKey, byte[] highKey)	Non-transactionally counts the number of entries within the given range.
default boolean	delete(Transaction txn, byte[] key)	Unconditionally removes the entry associated with the given key.
default byte[]	exchange(Transaction txn, byte[] key, byte[] value)	Unconditionally associates a value with the given key, returning the previous value.
default boolean	exists(Transaction txn, byte[] key)	Checks if an entry for the given key exists.
default boolean	insert(Transaction txn, byte[] key, byte[] value)	Associates a value with the given key, unless a corresponding value already exists.
default boolean	isEmpty()	Non-transactionally determines if the view has nothing in it.
default boolean	isModifyAtomic()	Returns true if the value-modifying methods of this view are atomic, even when not using transactions.
boolean	isUnmodifiable()	Returns true if any attempt to modify this view causes an UnmodifiableViewException to be thrown.
default byte[]	load(Transaction txn, byte[] key)	Returns a copy of the value for the given key, or null if no matching entry exists.
LockResult	lockCheck(Transaction txn, byte[] key)	Checks the lock ownership for the given key.
LockResult	lockExclusive(Transaction txn, byte[] key)	Explicitly acquire an exclusive lock for the given key, denying any additional locks.
LockResult	lockShared(Transaction txn, byte[] key)	Explicitly acquire a shared lock for the given key, denying exclusive locks.
LockResult	lockUpgradable(Transaction txn, byte[] key)	Explicitly acquire an upgradable lock for the given key, denying exclusive and additional upgradable locks.
default Cursor	newAccessor(Transaction txn, byte[] key)	Returns a cursor intended for accessing values in chunks, permitting them to be larger than what can fit in main memory.
Cursor	newCursor(Transaction txn)	Returns a new cursor over this view.
default Transaction	newTransaction(DurabilityMode durabilityMode)	Returns a new transaction which is compatible with this view.
Ordering	ordering()	Returns the key ordering for this view.
default boolean	remove(Transaction txn, byte[] key, byte[] value)	Removes the entry associated with the given key, but only if the given value matches.
default boolean	replace(Transaction txn, byte[] key, byte[] value)	Associates a value with the given key, but only if a corresponding value already exists.
default void	store(Transaction txn, byte[] key, byte[] value)	Unconditionally associates a value with the given key.
default LockResult	touch(Transaction txn, byte[] key)	Touch the given key as if calling load, but instead only acquiring any necessary locks.
default LockResult	tryLockExclusive(Transaction txn, byte[] key, long nanosTimeout)	Explicitly acquire an exclusive lock for the given key, denying any additional locks.
default LockResult	tryLockShared(Transaction txn, byte[] key, long nanosTimeout)	Explicitly acquire a shared lock for the given key, denying exclusive locks.
default LockResult	tryLockUpgradable(Transaction txn, byte[] key, long nanosTimeout)	Explicitly acquire an upgradable lock for the given key, denying exclusive and additional upgradable locks.
default boolean	update(Transaction txn, byte[] key, byte[] value)	Associates a value with the given key, but only if the given value differs from the existing value.
default boolean	update(Transaction txn, byte[] key, byte[] oldValue, byte[] newValue)	Associates a value with the given key, but only if the given old value matches the existing value.
default View	viewDifference(Combiner combiner, View second)	Returns a view which represents the set difference of this view and a second one.
default View	viewFiltered(Filter filter)	Returns a sub-view, backed by this one, whose entries have been filtered out.
default View	viewGe(byte[] key)	Returns a sub-view, backed by this one, whose keys are greater than or equal to the given key.
default View	viewGt(byte[] key)	Returns a sub-view, backed by this one, whose keys are greater than the given key.
default View	viewIntersection(Combiner combiner, View second)	Returns a view which represents the set intersection of this view and a second one.
default View	viewKeys()	Returns a view, backed by this one, which only provides the keys.
default View	viewLe(byte[] key)	Returns a sub-view, backed by this one, whose keys are less than or equal to the given key.
default View	viewLt(byte[] key)	Returns a sub-view, backed by this one, whose keys are less than the given key.
default View	viewPrefix(byte[] prefix, int trim)	Returns a sub-view, backed by this one, whose keys start with the given prefix.
default View	viewReverse()	Returns a view, backed by this one, whose natural order is reversed.
default View	viewTransformed(Transformer transformer)	Returns a sub-view, backed by this one, whose entries have been filtered out and transformed.
default View	viewUnion(Combiner combiner, View second)	Returns a view which represents the set union of this view and a second one.
default View	viewUnmodifiable()	Returns a view, backed by this one, whose entries cannot be modified.

Method Details

id

long id()

Returns:

randomly assigned, unique non-zero identifier for this index

name

byte[] name()

Returns:

unique user-specified index name

nameString

String nameString()

Returns:

name decoded as UTF-8

asTable

<R> Table<R> asTable(Class<R> type)
              throws IOException

Returns a Table instance which stores rows in this index. Bypassing the Table and storing directly into this index should be avoided, since it interferes with row encoding. Mixing encoding strategies can cause data corruption.

Returns:

shared Table instance

Throws:

IOException

See Also:

• Database.openTable(Class)

evict

long evict(Transaction txn,
 byte[] lowKey,
 byte[] highKey,
 Filter evictionFilter,
 boolean autoload)
    throws IOException

Select a few entries, and delete them from the index. Implementation should attempt to evict entries which haven't been recently used, but it might select them at random.

Parameters:

txn - optional

lowKey - inclusive lowest key in the evictable range; pass null for open range

highKey - exclusive highest key in the evictable range; pass null for open range

evictionFilter - callback which determines which entries are allowed to be evicted; pass null to evict all selected entries

autoload - pass true to also load values and pass them to the filter

Returns:

sum of the key and value lengths which were evicted, or 0 if none were evicted

Throws:

IOException

analyze

IndexStats analyze(byte[] lowKey,
 byte[] highKey)
            throws IOException

Estimates the size of this index with a single random probe. To improve the estimate, average several analysis results together.

Parameters:

lowKey - inclusive lowest key in the analysis range; pass null for open range

highKey - exclusive highest key in the analysis range; pass null for open range

Throws:

IOException

verify

boolean verify(VerificationObserver observer,
 int numThreads)
        throws IOException

Verifies the integrity of the index. Using multiple threads speeds up verification, even though some nodes might be visited multiple times.

Parameters:

observer - optional observer; pass null for default

numThreads - pass 0 for default, or if negative, the actual number will be (-numThreads * availableProcessors).

Returns:

true if verification passed

Throws:

IOException

close

void close()
    throws IOException

Closes this index reference. The underlying index is still valid and can be re-opened, unless it's a temporary index.

In general, indexes should not be closed if they are referenced by active transactions. Although closing the index is safe, the transaction might re-open it.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Throws:

IOException

See Also:

• ClosedIndexException

isClosed

boolean isClosed()

drop

void drop()
   throws IOException

Fully closes and removes an empty index. An exception is thrown if the index isn't empty or if an in-progress transaction is modifying it.

Throws:

IllegalStateException - if index isn't empty or if any pending transactional changes exist

ClosedIndexException - if this index reference is closed

IOException

See Also:

• Database.deleteIndex