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 org.cojen.tupl.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

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(java.lang.Class<R>)

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