org.jsimpledb.index.package-info Maven / Gradle / Ivy
Show all versions of jsimpledb-util Show documentation
/*
* Copyright (C) 2015 Archie L. Cobbs. All rights reserved.
*/
/**
* JSimpleDB index classes. These classes define the Java interface to database indexes.
*
*
* Indexes provide fast lookup of objects based on field value(s). The {@code 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 {@code int }{@code getAccountNumber()} of type
* {@code User} will be represented by a {@link org.jsimpledb.index.Index}{@code }, and may be viewed
* either as a {@link java.util.NavigableSet}{@code <}{@link org.jsimpledb.tuple.Tuple2}{@code >}
* or a {@link java.util.NavigableMap}{@code >}.
*
*
* Simple and Composite Indexes
*
*
* A simple index on a single field value is created by setting {@code indexed="true"} on the
* {@link org.jsimpledb.annotation.JField @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 {@link org.jsimpledb.util.NavigableSets#intersection NavigableSets.intersection()}, etc.
*
*
* A composite index on two fields {@code String getUsername()} and {@code float getBalance()} of type {@code User}
* will be represented by a {@link org.jsimpledb.index.Index2}{@code }; a composite index on
* three fields of type {@code X}, {@code Y}, and {@code Z} by a {@link org.jsimpledb.index.Index3}{@code }, 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.
*
*
* 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 {@link java.util.Set Set}, {@link java.util.List List}, or {@link java.util.Map Map} field. However,
* complex sub-fields may not appear in composite indexes.
*
*
* For those complex sub-fields that can contain duplicate values (namely, {@link java.util.List} element and
* {@link java.util.Map} value), the associated distinguishing value (respectively, {@link java.util.List} index
* and {@link java.util.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 follows:
*
*
*
*
* Complex Field
* Indexed Sub-Field
* Distinguising Value
* Distinguising Type
* Index Type
*
*
* {@link java.util.Set}{@code }
* Set element
* n/a
* n/a
* {@link org.jsimpledb.index.Index}{@code }
*
*
* {@link java.util.List}{@code }
* List element
* List index
* {@link java.lang.Integer}
* {@link org.jsimpledb.index.Index2}{@code }
*
*
* {@link java.util.Map}{@code }
* Map key
* n/a
* n/a
* {@link org.jsimpledb.index.Index}{@code }
*
*
* {@link java.util.Map}{@code }
* Map value
* Map key
* {@code K}
* {@link org.jsimpledb.index.Index2}{@code }
*
*
*
*/
package org.jsimpledb.index;