Package com.googlecode.cqengine.index.unique

Class UniqueIndex<A,​O>

  • All Implemented Interfaces:
    ModificationListener<O>, AttributeIndex<A,​O>, Index<O>, OnHeapTypeIndex
    public class UniqueIndex<A,​O>
extends AbstractAttributeIndex<A,​O>
implements OnHeapTypeIndex
    An index backed by a ConcurrentHashMap, which can be more efficient than HashIndex when used with (and only with) attributes which uniquely identify objects (primary key-type attributes).

    This type of index does not store a set of objects matching each attribute value, but instead stores only a single object for each value. This results in faster query performance, and often lower memory usage, but has some trade-offs.

    This index will throw an exception if a duplicate object is detected for an existing attribute value. That condition means however that inconsistencies might already have arisen between this and other indexes as a result of the application's misuse of this index.

    Trade-offs: UniqueIndex versus HashIndex

    • UniqueIndex will always use less memory than a non-quantized HashIndex
    • UniqueIndex will not necessarily use less memory than a quantized HashIndex, i.e. configured with a Quantizer
    • In all cases, UniqueIndex will answer queries faster than a HashIndex
    • It is important that UniqueIndex only be used with attributes which uniquely identify objects
    • A UniqueIndex on a primary key-type attribute might not be compatible with the MVCC algorithm implemented by TransactionalIndexedCollection.

    Supports query types:

    Author:
    Kinz Liu, Niall Gallagher

    • Constructor Detail

      • UniqueIndex

        protected UniqueIndex​(Factory<ConcurrentMap<A,​O>> indexMapFactory,
                      Attribute<O,​A> attribute)
        Package-private constructor, used by static factory methods. Creates a new UniqueIndex initialized to index the supplied attribute.
        Parameters:
        indexMapFactory - A factory used to create the main map-based data structure used by the index
        attribute - The attribute on which the index will be built

    • Method Detail

      • supportsQuery

        public boolean supportsQuery​(Query<O> query,
                             QueryOptions queryOptions)
        Description copied from class: AbstractAttributeIndex
        Indicates if the index can perform retrievals for the type of query supplied.
        Specified by:
        supportsQuery in interface Index<A>
        Overrides:
        supportsQuery in class AbstractAttributeIndex<A,​O>
        Parameters:
        query - A query to check
        queryOptions - Optional parameters for the query
        Returns:
        True if the index can perform retrievals for the type of query supplied, false if it does not support this type of query

      • isMutable

        public boolean isMutable()
        Indicates if objects can be added to or removed from the index after the index has been built.

        This index is mutable.

        Specified by:
        isMutable in interface Index<A>
        Returns:
        true

      • isQuantized

        public boolean isQuantized()
        Description copied from interface: Index
        Indicates if the index is quantized, using a Quantizer.
        Specified by:
        isQuantized in interface Index<A>
        Returns:
        True if the index is quantized, false if not.

      • getEffectiveIndex

        public Index<O> getEffectiveIndex()
        Description copied from interface: Index
        Returns the effective index, which Persistence objects will use to determine the identity of the index making persistence requests. Most Index implementations will typically return a reference to themselves ('this'). However in advanced cases when one index delegates to another, the implementation of the wrapping index will create a subclass the delegate index, and override this method in the delegate index so that when the delegate index interacts with the persistence, it will identify itself as the outer or "effective" index.
        Specified by:
        getEffectiveIndex in interface Index<A>
        Returns:
        The effective index, in the case that this index is wrapped by another index.

      • retrieve

        public ResultSet<O> retrieve​(Query<O> query,
                             QueryOptions queryOptions)
        Description copied from interface: Index
        Returns a ResultSet which when iterated will return objects from the index matching the query supplied.

        Usually ResultSets are lazy which means that they don't actually do any work, or encapsulate or materialize matching objects, but rather they encapsulate logic to fetch matching objects from the index on-the-fly as the application iterates through the ResultSet.

        Specified by:
        retrieve in interface Index<A>
        Parameters:
        query - An object which specifies some restriction on an attribute of an object
        queryOptions - Optional parameters for the query
        Returns:
        A set of objects with attributes matching the restriction imposed by the query
        See Also:
        Index.supportsQuery(Query, QueryOptions)

      • addAll

        public boolean addAll​(ObjectSet<O> objectSet,
                      QueryOptions queryOptions)
        Notifies the listener that the specified objects are being added to the collection, and so it can take action and update its internal data structures.
        Specified by:
        addAll in interface ModificationListener<A>
        Parameters:
        objectSet - The objects being added
        queryOptions - Optional parameters for the update

      • removeAll

        public boolean removeAll​(ObjectSet<O> objectSet,
                         QueryOptions queryOptions)
        Notifies the listener that the specified objects are being removed from the collection, and so it can take action and update its internal data structures.
        Specified by:
        removeAll in interface ModificationListener<A>
        Parameters:
        objectSet - The objects being removed
        queryOptions - Optional parameters for the update

      • init

        public void init​(ObjectStore<O> objectStore,
                 QueryOptions queryOptions)
        Notifies the listener that the given ObjectStore has just been created.
        Specified by:
        init in interface ModificationListener<A>
        Parameters:
        objectStore - The ObjectStore which persists objects
        queryOptions - Optional parameters for the update

      • destroy

        public void destroy​(QueryOptions queryOptions)
        This is a no-op for this type of index.
        Specified by:
        destroy in interface ModificationListener<A>
        Parameters:
        queryOptions - Optional parameters for the update

      • clear

        public void clear​(QueryOptions queryOptions)
        Notifies the listener that all objects have been removed from the collection, and so it can take action and update its internal data structures.
        Specified by:
        clear in interface ModificationListener<A>
        Parameters:
        queryOptions - Optional parameters for the update

      • onAttribute

        public static <A,​O> UniqueIndex<A,​O> onAttribute​(Attribute<O,​A> attribute)
        Creates a new UniqueIndex on the specified attribute.

        Type Parameters:
        O - The type of the object containing the attribute
        Parameters:
        attribute - The attribute on which the index will be built
        Returns:
        A UniqueIndex on this attribute

      • onAttribute

        public static <A,​O> UniqueIndex<A,​O> onAttribute​(Factory<ConcurrentMap<A,​O>> indexMapFactory,
                                                             Attribute<O,​A> attribute)
        Creates a new UniqueIndex on the specified attribute.

        Type Parameters:
        O - The type of the object containing the attribute
        Parameters:
        indexMapFactory - A factory used to create the main map-based data structure used by the index
        attribute - The attribute on which the index will be built
        Returns:
        A UniqueIndex on this attribute