• Home
• io.permazen
• permazen-util
• 5.0.0
• source code
• package-info.java

×

Project download

Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance.
Project price only 1 $

You can buy this project and download/modify it how often you want.

io.permazen.index.package-info Maven / Gradle / Ivy

/*
 * Copyright (C) 2015 Archie L. Cobbs. All rights reserved.
 */

/**
 * Permazen 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 io.permazen.index.Index1}{@code }, and may be viewed
 * either as a {@link java.util.NavigableSet}{@code <}{@link io.permazen.tuple.Tuple2}{@code >}
 * or a {@link java.util.NavigableMap}{@code >}.
 *
 * 

 * Indexes are accessible through the {@link io.permazen.PermazenTransaction} API:
 * 

 *  
{@link io.permazen.PermazenTransaction#querySimpleIndex(Class, String, Class) PermazenTransaction.querySimpleIndex()}
 *      - Access the index associated with a simple field
 *  
{@link io.permazen.PermazenTransaction#queryListElementIndex PermazenTransaction.queryListElementIndex()}
 *      - Access the composite index associated with a list field that includes corresponding list indices
 *  
{@link io.permazen.PermazenTransaction#queryMapValueIndex PermazenTransaction.queryMapValueIndex()}
 *      - Access the composite index associated with a map value field that includes corresponding map keys
 *  
{@link io.permazen.PermazenTransaction#queryCompositeIndex(Class, String, Class, Class)
 *      PermazenTransaction.queryCompositeIndex()} - Access a composite index defined on two fields
 *  
{@link io.permazen.PermazenTransaction#queryCompositeIndex(Class, String, Class, Class, Class)
 *      PermazenTransaction.queryCompositeIndex()} - Access a composite index defined on three fields
 *  
{@link io.permazen.PermazenTransaction#queryCompositeIndex(Class, String, Class, Class, Class, Class)
 *      PermazenTransaction.queryCompositeIndex()} - Access a composite index defined on four fields
 *  
 *  
{@link io.permazen.PermazenTransaction#querySchemaIndex PermazenTransaction.querySchemaIndex()}
 *      - 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 {@code indexed="true"} on the
 * {@link io.permazen.annotation.PermazenField @PermazenField} 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 io.permazen.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 io.permazen.index.Index2}{@code }; a composite index on
 * three fields of type {@code X}, {@code Y}, and {@code Z} by a {@link io.permazen.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 always be viewed as a simpler index on any prefix of its indexed fields; for example, see
 * {@link io.permazen.index.Index2#asIndex1}.
 *
 * 

 * 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) becomes a new value that is appended to the index.
 * The resulting index types associated with indexes on complex sub-fields of some object type {@code Foobar} are as follows:
 *
 * 

 * 
 * 
 * 
 *  
 *  
 *  
 *  
 *  
 * 
 * 
 *  
 *  
 *  
 *  
 *  
 * 
 * 
 *  
 *  
 *  
 *  
 *  
 * 
 * 
 *  
 *  
 *  
 *  
 *  
 * 
 * 
 *  
 *  
 *  
 *  
 *  
 * 
 * 
Index Types
Complex Field
Indexed Sub-Field
Distinguising Value
Distinguising Type
Index Type
{@link java.util.Set}{@code }
Set element
n/a
n/a
{@link io.permazen.index.Index1}{@code }
{@link java.util.List}{@code }
List element
List index
{@link java.lang.Integer}
{@link io.permazen.index.Index2}{@code }
{@link java.util.Map}{@code }
Map key
n/a
n/a
{@link io.permazen.index.Index1}{@code }
{@link java.util.Map}{@code }
Map value
Map key
{@code K}
{@link io.permazen.index.Index2}{@code }
 * 
 *
 * 

 * To ignore the distinguishing values, convert the {@link io.permazen.index.Index2} back into an {@link io.permazen.index.Index1}
 * via {@link io.permazen.index.Index2#asIndex1}.
 */
package io.permazen.index;