Package com.googlecode.cqengine

Interface IndexedCollection<O>

All Superinterfaces:

Collection<O>, Iterable<O>, QueryEngine<O>, Set<O>

All Known Implementing Classes:

ConcurrentIndexedCollection, ObjectLockingIndexedCollection, TransactionalIndexedCollection

public interface IndexedCollection<O>
extends Set<O>, QueryEngine<O>

A Java collection which can maintain indexes on the objects it contains, allowing objects matching complex queries to be retrieved with very low latency.

The retrieve(com.googlecode.cqengine.query.Query) methods accept a Query and return a ResultSet of objects matching that query.

The addIndex(com.googlecode.cqengine.index.Index) methods allowing indexes to be added to the collection to improve query performance.

Several implementations of this interface exist each with different performance or transaction isolation characteristics. See documentation on the implementations for further details.

Author:

Niall Gallagher

Method Summary

Modifier and Type	Method	Description
void	addIndex(Index<O> index)
void	addIndex(Index<O> index, QueryOptions queryOptions)	Adds the given index to the collection.
MetadataEngine<O>	getMetadataEngine()	Returns the MetadataEngine, which can retrieve metadata and statistics from indexes on the distribution of attribute values in the collection.
Persistence<O,?>	getPersistence()	Returns the Persistence used by the the collection.
void	removeIndex(Index<O> index)
void	removeIndex(Index<O> index, QueryOptions queryOptions)	Removes the given index from the collection.
ResultSet<O>	retrieve(Query<O> query)	Shortcut for calling retrieve(Query, QueryOptions) without supplying any query options.
ResultSet<O>	retrieve(Query<O> query, QueryOptions queryOptions)	Retrieves a ResultSet which provides objects matching the given query, additionally accepting QueryOptions which can specify ordering of results, deduplication strategy etc.
boolean	update(Iterable<O> objectsToRemove, Iterable<O> objectsToAdd)	Removes or adds objects to/from the collection and indexes in bulk.
boolean	update(Iterable<O> objectsToRemove, Iterable<O> objectsToAdd, QueryOptions queryOptions)	Removes or adds objects to/from the collection and indexes in bulk.

Methods inherited from interface java.util.Collection

parallelStream, removeIf, stream, toArray

Methods inherited from interface java.lang.Iterable

forEach

Methods inherited from interface com.googlecode.cqengine.engine.QueryEngine

getIndexes

Methods inherited from interface java.util.Set

add, addAll, clear, contains, containsAll, equals, hashCode, isEmpty, iterator, remove, removeAll, retainAll, size, spliterator, toArray, toArray

Method Detail

retrieve

ResultSet<O> retrieve(Query<O> query)

Shortcut for calling retrieve(Query, QueryOptions) without supplying any query options.

retrieve

ResultSet<O> retrieve(Query<O> query,
                      QueryOptions queryOptions)

Retrieves a ResultSet which provides objects matching the given query, additionally accepting QueryOptions which can specify ordering of results, deduplication strategy etc.

Specified by:

retrieve in interface QueryEngine<O>

Parameters:

query - A query representing some assertions which sought objects must match

queryOptions - Optional parameters for the query

Returns:

A ResultSet which provides objects matching the given query

update

boolean update(Iterable<O> objectsToRemove,
               Iterable<O> objectsToAdd)

Removes or adds objects to/from the collection and indexes in bulk.

Note that although this method accepts either Iterables or Collections for its objectsToRemove and objectsToAdd parameters, there are pros and cons of each:

• If an Iterable is supplied, updates to indexes will be applied in a streaming fashion. This allows the application and CQEngine to avoid buffering many updates in memory as a batch, but requires more round trips to update indexes, which might hurt performance for indexes where making many round trips is expensive. This is typically fine for on-heap indexes, but less so for off-heap or on-disk indexes.
• If a Collection is supplied, updates to indexes will be applied as a single batch. This might improve performance for indexes where making many round trips is expensive. Ordinarily this implies that the application needs to assemble a batch into a collection before calling this method. However for applications where the source of updates is computed lazily or originates from a stream, but yet where it is desirable to apply the updates as a batch anyway, the application can wrap the stream as a lazy collection (extend AbstractCollection) so that CQEngine will behave as above.
  • Note also that some off-heap and on-disk indexes support a fast "bulk import" feature which can be used in conjunction with this. For details on how to perform a bulk import, see SQLiteIndexFlags.BULK_IMPORT.

Parameters:

objectsToRemove - The objects to remove from the collection

objectsToAdd - The objects to add to the collection

Returns:

True if the collection was modified as a result, false if it was not

update

boolean update(Iterable<O> objectsToRemove,
               Iterable<O> objectsToAdd,
               QueryOptions queryOptions)

Removes or adds objects to/from the collection and indexes in bulk.

Note that although this method accepts either Iterables or Collections for its objectsToRemove and objectsToAdd parameters, there are pros and cons of each:

• If an Iterable is supplied, updates to indexes will be applied in a streaming fashion. This allows the application and CQEngine to avoid buffering many updates in memory as a batch, but requires more round trips to update indexes, which might hurt performance for indexes where making many round trips is expensive. This is typically fine for on-heap indexes, but less so for off-heap or on-disk indexes.
• If a Collection is supplied, updates to indexes will be applied as a single batch. This might improve performance for indexes where making many round trips is expensive. Ordinarily this implies that the application needs to assemble a batch into a collection before calling this method. However for applications where the source of updates is computed lazily or originates from a stream, but yet where it is desirable to apply the updates as a batch anyway, the application can wrap the stream as a lazy collection (extend AbstractCollection) so that CQEngine will behave as above.
  • Note also that some off-heap and on-disk indexes support a fast "bulk import" feature which can be used in conjunction with this. For details on how to perform a bulk import, see SQLiteIndexFlags.BULK_IMPORT.

Parameters:

objectsToRemove - The objects to remove from the collection

objectsToAdd - The objects to add to the collection

queryOptions - Optional parameters for the update

Returns:

True if the collection was modified as a result, false if it was not

addIndex

void addIndex(Index<O> index)

See Also:

addIndex(Index, QueryOptions)

addIndex

void addIndex(Index<O> index,
              QueryOptions queryOptions)

Adds the given index to the collection.

Subsequently queries passed to the QueryEngine.retrieve(com.googlecode.cqengine.query.Query, QueryOptions) method will use these indexes if suitable for the particular queries, to speed up retrievals.

Specified by:

addIndex in interface QueryEngine<O>

Parameters:

index - The index to add

queryOptions - Optional parameters for the index

removeIndex

void removeIndex(Index<O> index)

See Also:

removeIndex(Index, QueryOptions)

removeIndex

void removeIndex(Index<O> index,
                 QueryOptions queryOptions)

Removes the given index from the collection.

Specified by:

removeIndex in interface QueryEngine<O>

Parameters:

index - The index to remove

queryOptions - Optional parameters for the index

getPersistence

Persistence<O,?> getPersistence()

Returns the Persistence used by the the collection.

Returns:

The Persistence used by the the collection

getMetadataEngine

MetadataEngine<O> getMetadataEngine()

Returns the MetadataEngine, which can retrieve metadata and statistics from indexes on the distribution of attribute values in the collection.