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:

• JTransaction.queryIndex() - Access the index associated with a simple field
• JTransaction.queryListElementIndex() - Access the composite index associated with a list field that includes corresponding list indices
• JTransaction.queryMapValueIndex() - Access the composite index associated with a map value field that includes corresponding map keys
• JTransaction.queryCompositeIndex() - Access a composite index defined on two fields
• JTransaction.queryCompositeIndex() - Access a composite index defined on three fields
• JTransaction.queryCompositeIndex() - Access a composite index defined on four fields
• JTransaction.queryVersion() - Get database objects grouped according to their schema versions

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>

Interface Summary

Interface	Description
Index<V,T>	An index on a single field.
Index2<V1,V2,T>	An index on two fields.
Index3<V1,V2,V3,T>	An index on three fields.
Index4<V1,V2,V3,V4,T>	An index on a four fields.