Package ai.timefold.solver.core.impl.bavet.common.index

Interface Indexer<T>

Type Parameters:
T - The element type. Often a tuple. For example for from(A).join(B), the tuple is UniTuple<A> xor UniTuple<B>. For example for Bi<A, B>.join(C), the tuple is BiTuple<A, B> xor UniTuple<C>.
All Known Subinterfaces:
IndexerBackend<T>
All Known Implementing Classes:
LinkedListIndexerBackend, RandomAccessIndexerBackend
@NullMarked public sealed interface Indexer<T> permits IndexerBackend<T> (not exhaustive)
An indexer for entity or fact X, maps a property or a combination of properties of X, denoted by compositeKey, to all instances of X that match those properties, depending on the indexer type (equal, lower than, contain, ...). For example for {Lesson(id=1, room=A), Lesson(id=2, room=B), Lesson(id=3, room=A)}, calling visit(room=A) would visit lesson 1 and 3.

The fact X is wrapped in a Tuple, because the TupleState is needed by clients of forEach(Object, Consumer).

Some indexer types (such as contain, containedIn, ...) have two different key types (modify key vs query key), depending on the operation type (modify operation vs query operation). For example, for a contain indexer the modify key is a collection, but the query key is not.

  • Method Details

    • put

      ListEntry<T> put(Object modifyCompositeKey, T tuple)
      Modify operation.
      Parameters:
      modifyCompositeKey - modify composite key
      tuple - never null
      Returns:
      the entry to allow remove it from the index directly

    • remove

      void remove(Object modifyCompositeKey, ListEntry<T> entry)
      Modify operation. Must not be called during forEach(Object, Consumer) and invalidates any iterator(Object) obtained before.
      Parameters:
      modifyCompositeKey - modify composite key
      entry - never null

    • size

      int size(Object queryCompositeKey)
      Query operation.
      Parameters:
      queryCompositeKey - query composite key
      Returns:
      at least 0

    • forEach

      default void forEach(Object queryCompositeKey, Consumer<T> tupleConsumer)
      Query operation.
      Parameters:
      queryCompositeKey - query composite key
      tupleConsumer - never null

    • iterator

      Iterator<T> iterator(Object queryCompositeKey)
      Gets an iterator for the given composite key. The returned iterator does not support Iterator.remove().
      Parameters:
      queryCompositeKey - composite key uniquely identifying the backend or a set of backends
      Returns:
      possibly empty iterator for the given composite key

    • isRemovable

      boolean isRemovable()
      Some indexers can be empty (size 0 and an empty forEach for all keys) but not yet removable.
      Returns:
      true if empty and all put() calls had a remove() call

    • randomIterator

      Iterator<T> randomIterator(Object queryCompositeKey, Random workingRandom)
      Iterator which picks elements randomly. Selection probability is uniform over all elements for the given composite key. By calling Iterator.remove(), the element is removed never to be returned again by this iterator. However, it is not removed from the index itself; the only way to remove from the index is to call remove(Object, ListEntry), which will make any existing iterators invalid.
      Parameters:
      queryCompositeKey - composite key uniquely identifying the backend or a set of backends
      workingRandom - used to pick random elements
      Returns:
      iterator for the given composite key, possibly empty

    • randomIterator

      Iterator<T> randomIterator(Object queryCompositeKey, Random workingRandom, Predicate<T> filter)
      As defined by randomIterator(Object, Random), but only returning elements matching the given filter.