Package io.permazen.index

Permazen index classes. These classes define the Java interface to database indexes.

Indexes provide fast lookup of objects based on field value(s). The Index* interfaces in this package have generic type parameters that correspond to the field value type(s), plus a final generic type parameter corresponding to the "target type". For example, an index on field int getAccountNumber() of type User will be represented by a Index<Integer, User>, and may be viewed either as a NavigableSet<Tuple2<Integer, User>> or a NavigableMap<Integer, NavigableSet<User>>.

Indexes are accessible through the JTransaction API:

Simple and Composite Indexes

A simple index on a single field value is created by setting indexed="true" on the @JField annotation.

Composite indexes on multiple fields are also supported. These are useful when the target type needs to be sorted on multiple fields; for simple searching on multiple fields, it suffices to have independent, single-field indexes, which can be intersected via NavigableSets.intersection(), etc.

A composite index on two fields String getUsername() and float getBalance() of type User will be represented by a Index2<String, Float, User>; a composite index on three fields of type X, Y, and Z by a Index3<X, Y, Z, User>, etc.

A composite index may be viewed as a set of tuples of indexed and target values, or as various mappings from one or more indexed field values to subsequent values. A composite index may also be viewed as a simpler index on any prefix of the indexed fields; for example, see Index2.asIndex().

Complex Sub-Fields

Only simple fields may be indexed, but the indexed field can be either a normal object field or a sub-field of a complex Set, List, or Map field. However, complex sub-fields may not appear in composite indexes.

For those complex sub-fields that can contain duplicate values (namely, List element and Map value), the associated distinguishing value (respectively, List index and Map key) is appended to the index and becomes the new target type. Therefore the resulting index types associated with indexes on complex sub-fields are as follows:

Complex Field Indexed Sub-Field Distinguising Value Distinguising Type Index Type
Set<E> Set element n/a n/a Index<E, Foobar>
List<E> List element List index Integer Index2<E, Foobar, Integer>
Map<K, V> Map key n/a n/a Index<K, Foobar>
Map<K, V> Map value Map key K Index2<V, Foobar, K>