com.hammurapi.store

## Interface Store<T,PK,S extends Store<T,PK,S>>

- Type Parameters:
    `T` - Object type.
    `PK` - Primary key type.
    `S` - Self-type - sub-type of store. Generic parameter for predicates, extractors, update tasks and views.
  All Superinterfaces:
    Iterable<T>, ReadWriteLock
  All Known Subinterfaces:
    LocalStore<T,PK>, Transaction<T,PK,S>, TransactionalStore<T,PK,S>
  All Known Implementing Classes:
    AbstractStore, DeputyStore, LiveView, LocalStoreBase, LocalStoreImpl, LocalStoreImpl.LocalDeputyStore, LocalStoreImpl.LocalLiveView, LocalStoreImpl.LocalUnmodifiableStore, UnmodifiableStore

      public interface Store<T,PK,S extends Store<T,PK,S>>
      extends ReadWriteLock, Iterable<T>

  Abstraction of object store.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static interface` | `Store.Handle<T,PK,S extends Store<T,PK,S>>` Object handle.
    `static interface` | `Store.QueryTask<T,PK,S extends Store<?,PK,S>>` Task to perform processing on objects (without updating).
    `static interface` | `Store.StoreIterator<T>` Some stores may return StoreIterator, which needs to be closed if iterator operation is terminated before hasNext() returns false.
    `static interface` | `Store.UpdateTask<T,PK,S extends Store<T,PK,S>>` Task to update objects.
    `static class` | `Store.ViewType`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `<V,ST extends T> Index<T,ST,PK,V,S>` | `addIndex(Predicate<T,S> predicate, Extractor<ST,V,S> extractor, Index.Type type, boolean ordered, Comparator<V> comparator)` Adds index to the store to speed-up extraction operations.
    `void` | `clear()` Removes all entries from the store.
    `S` | `createUnmodifiableFacade()` Creates unmodifiable facade for this store.
    `S` | `createView(Predicate<T,S> selector, Store.ViewType viewType)` Creates a view - a store which sees only objects matching the given selector.
    `Iterable<T>` | `get(Predicate<T,S> selector)` Retrieves objects matching the predicate.
    `<V> Iterable<V>` | `get(Predicate<T,S> selector, Extractor<T,V,S> extractor, boolean ordered, Comparator<V> comparator)` Retrieves values from objects matching the predicate.
    `Iterable<T>` | `getAll()` Retrieves all objects from the store.
    `T` | `getByPrimaryKey(PK primaryKey)` Retrieves object with given primary key.
    `<V> Iterable<V>` | `getMultiple(Predicate<T,S> selector, Extractor<T,Iterable<V>,S> extractor, Predicate<V,S> valueSelector, boolean ordered, Comparator<V> comparator)` Retrieves values from objects matching the predicate.
    `Extractor<T,PK,S>` | `getPrimaryKeyExtractor()` If primary key is set, then the store shall use equals on the value returned from the primaryKeyExtractor instead of equals on the object to compare objects for removal and update (put).
    `Store.Handle<T,PK,S>` | `put(T obj, Predicate<T,S>... validators)` Puts object to the store.
    `<V> int` | `query(Predicate<T,S> selector, Extractor<T,V,S> extractor, Store.QueryTask<V,PK,S> processor)` Processes values extracted from objects matching the predicate.
    `int` | `query(Predicate<T,S> selector, Store.QueryTask<T,PK,S> processor)` Processes objects matching the predicate.
    `int` | `queryAll(Store.QueryTask<T,PK,S> processor)` Processes all objects in the store.
    `<V> int` | `queryMultiple(Predicate<T,S> selector, Extractor<T,Iterable<V>,S> extractor, Predicate<V,S> valueSelector, Store.QueryTask<V,PK,S> processor)` Processes multiple values extracted from objects matching the predicate.
    `int` | `remove(Predicate<T,S> selector)` Removes objects matching the predicate.
    `boolean` | `remove(T obj)` Removes specified object from the store.
    `boolean` | `removeByPrimaryKey(PK primaryKey)` Removes object by primary key.
    `int` | `update(Predicate<T,S> selector, Store.UpdateTask<T,PK,S> updater)` Updates objects matching the predicate.

    - ### Methods inherited from interface java.util.concurrent.locks.ReadWriteLock

      `readLock, writeLock`

    - ### Methods inherited from interface java.lang.Iterable

      `iterator`

- - ### Method Detail

    - #### put

          Store.Handle<T,PK,S> put(T obj,
                                 Predicate<T,S>... validators)

      Puts object to the store. If object is already present in the store, it gets updated in the store.
      Parameters:
        `obj` - Object to put to the store.
        `validators` - Predicate(s) which are checked when object is retrieved from the store. If there is more than one predicate, predicates are connected with AND. If validator(s) evaluate to false, the object handle is considered invalid, i.e. object is considered removed from the store. Once validator(s) evaluate to false, they shall always evaluate to false. One of use of validators can be to expire object in the store, i.e. after some time validator returns false and object is cleared from the database. If validators evaluate to false at put time, object is not put to the store and put() returns null. Validators evaluation result is not cached.
      Returns:
        Object handle or null if validator(s) evaluate to false.

    - #### getAll

          Iterable<T> getAll()

      Retrieves all objects from the store.
      Returns:

    - #### queryAll

          int queryAll(Store.QueryTask<T,PK,S> processor)

      Processes all objects in the store.
      Parameters:
        `processor` -
      Returns:
        number of object queried.

    - #### getByPrimaryKey

          T getByPrimaryKey(PK primaryKey)

      Retrieves object with given primary key.
      Parameters:
        `primaryKey` -
      Returns:
      Throws:
        `IllegalStateException` - if object store is configured without primary key.

    - #### get

          Iterable<T> get(Predicate<T,S> selector)

      Retrieves objects matching the predicate.
      Parameters:
        `selector` -
      Returns:

    - #### query

          int query(Predicate<T,S> selector,
                  Store.QueryTask<T,PK,S> processor)

      Processes objects matching the predicate.
      Parameters:
        `selector` -
      Returns:
        Number of objects queried.

    - #### query

          <V> int query(Predicate<T,S> selector,
                      Extractor<T,V,S> extractor,
                      Store.QueryTask<V,PK,S> processor)

      Processes values extracted from objects matching the predicate.
      Parameters:
        `selector` -
        `extractor` - Extractor.
        `processor` - Processor of query results.
      Returns:
        Number of objects queried.

    - #### queryMultiple

          <V> int queryMultiple(Predicate<T,S> selector,
                              Extractor<T,Iterable<V>,S> extractor,
                              Predicate<V,S> valueSelector,
                              Store.QueryTask<V,PK,S> processor)

      Processes multiple values extracted from objects matching the predicate.
      Parameters:
        `selector` - Objects shall match this predicate. If null, all objects match.
        `extractor` - Extractor
        `valueSelector` - Values from matched objects shall match this predicate. If null, all values match. Value selectors are executed in separate tasks from extractor. Separation of value selection logic from value extraction logic makes sense if value selection logic is relatively heavy and parallelization of its execution will reduce overall query execution time.
        `processor` - Processor of query results.
      Returns:
        Number of objects queried.

    - #### get

          <V> Iterable<V> get(Predicate<T,S> selector,
                            Extractor<T,V,S> extractor,
                            boolean ordered,
                            Comparator<V> comparator)

      Retrieves values from objects matching the predicate.
      Type Parameters:
        `V` -
      Parameters:
        `selector` - Object selector.
        `extractor` - Value extractor. If null, then object itself is returned.
        `ordered` - If true, then returned result is ordered by comparator or by natural order if comparator is null.
        `comparator` - Comparator to use for ordering.
      Returns:

    - #### getMultiple

          <V> Iterable<V> getMultiple(Predicate<T,S> selector,
                                    Extractor<T,Iterable<V>,S> extractor,
                                    Predicate<V,S> valueSelector,
                                    boolean ordered,
                                    Comparator<V> comparator)

      Retrieves values from objects matching the predicate. Multiple values are retrieved from each object.
      Type Parameters:
        `V` -
      Parameters:
        `selector` - Objects shall match this predicate. If null, all objects match.
        `extractor` - Value extractor.
        `valueSelector` - Values from matched objects shall match this predicate. If null, all values match. Value selectors are executed in separate tasks from extractor. Separation of value selection logic from value extraction logic makes sense if value selection logic is relatively heavy and parallelization of its execution will reduce overall query execution time.
        `ordered` - If true, then returned result is ordered by comparator or by natural order if comparator is null.
        `comparator` - Comparator to use for ordering.
      Returns:

    - #### clear

          void clear()

      Removes all entries from the store.

    - #### remove

          boolean remove(T obj)

      Removes specified object from the store.
      Parameters:
        `obj` - Object to remove.
      Returns:
        true if object was removed.

    - #### removeByPrimaryKey

          boolean removeByPrimaryKey(PK primaryKey)

      Removes object by primary key.
      Parameters:
        `primaryKey` -
      Returns:

    - #### remove

          int remove(Predicate<T,S> selector)

      Removes objects matching the predicate.
      Parameters:
        `predicate` -
      Returns:
        number of returned objects or -1 if number is unknown.

    - #### update

          int update(Predicate<T,S> selector,
                   Store.UpdateTask<T,PK,S> updater)

      Updates objects matching the predicate.
      Parameters:
        `selector` -
        `updater` -
      Returns:

    - #### addIndex

          <V,ST extends T> Index<T,ST,PK,V,S> addIndex(Predicate<T,S> predicate,
                                                     Extractor<ST,V,S> extractor,
                                                     Index.Type type,
                                                     boolean ordered,
                                                     Comparator<V> comparator)

      Adds index to the store to speed-up extraction operations.
      Type Parameters:
        `V` - Value type extracted by extractor for ordering.
        `ST` - Type of index elements, which can be a sub-type of store element type. index creation parameters.
      Parameters:
        `predicate` - Only store items matching the predicate are indexed.
        `extractor` - Extractor of the index key.
        `Index` - type.
        `ordered` - If true index is ordered.
        `comparator` - Comparator to use for ordering. If null, then natural order is used.
      Returns:
        A "mix" of Index sub-interfaces corresponding to the

    - #### getPrimaryKeyExtractor

          Extractor<T,PK,S> getPrimaryKeyExtractor()

      If primary key is set, then the store shall use equals on the value returned from the primaryKeyExtractor instead of equals on the object to compare objects for removal and update (put).
      Parameters:
        `primaryKeyExtractor` - Primary key extractor.
      Throws:
        `IllegalStateException` - If primary key is already set.

    - #### createView

          S createView(Predicate<T,S> selector,
                     Store.ViewType viewType)

      Creates a view - a store which sees only objects matching the given selector.
      Parameters:
        `selector` - View selector.
        `materialized` - If true, view elements are calculated at modify time instead of query time.
      Returns:
        Store which sees only objects matching give selector. The returned store is backed by the master store.

    - #### createUnmodifiableFacade

          S createUnmodifiableFacade()

      Creates unmodifiable facade for this store.
      Returns: