org.apache.ignite.streamer.index

## Interface StreamerIndex<E,K,V>

All Superinterfaces:
  Iterable<StreamerIndexEntry<E,K,V>>

    public interface StreamerIndex<E,K,V>
    extends Iterable<StreamerIndexEntry<E,K,V>>

User view on streamer index. Streamer indexes are used for fast look ups into streamer windows.

Streamer index can be accessed from `StreamerWindow` via any of the following methods:

- `StreamerWindow.index()`
- `StreamerWindow.index(String)`
- `StreamerWindow.indexes()`

Indexes are created and provided for streamer windows by `StreamerIndexProvider` which is specified in streamer configuration.

# Example of how to use indexes

Stock price events are streamed into the system, the stock price event is an object containing stock symbol and price. We need to get minimum price for GOOG instrument.

Here is `StreamerIndexUpdater` that maintains index values up to date:

     class StockPriceIndexUpdater implements GridStreamerIndexUpdater<StockPriceEvent, String, Double> {
         @Nullable @Override public String indexKey(StockPriceEvent evt) {
             return evt.getSymbol(); // Symbol is an index key.
         }

         @Nullable @Override public Double initialValue(StockPriceEvent evt, String key) {
             return evt.getPrice(); // Set first event's price as an initial value.
         }

         @Nullable @Override public Double onAdded(GridStreamerIndexEntry<StockPriceEvent, String, Double> entry,
             StockPriceEvent evt) throws IgniteCheckedException {
             return Math.min(entry.value(), evt.getPrice()); // Update the minimum on new event.
         }

         @Nullable @Override
         public Double onRemoved(GridStreamerIndexEntry<StockPriceEvent, String, Double> entry, StockPriceEvent evt) {
             return entry.value(); // Leave minimum unchanged when event is evicted.
         }
     }

Here is the code that queries minimum price for GOOG instrument using index:

     double minGooglePrice = streamer.context().reduce(
         // This closure will execute on remote nodes.
         new GridClosure<GridStreamerContext, Double>() {
             @Nullable @Override public Double apply(GridStreamerContext ctx) {
                 GridStreamerIndex<StockPriceEvent, String, Double> minIdx = ctx.<StockPriceEvent>window().index("min-price");

                 return minIdx.entry("GOOG").value();
             }
         },
         new GridReducer<Double, Double>() {
             private double minPrice = Integer.MAX_VALUE;

             @Override public boolean collect(Double price) {
                 minPrice = Math.min(minPrice, price); // Take minimum price from all nodes.

                 return true;
             }

             @Override public Double reduce() {
                 return minPrice;
             }
         }
     );

### Method Summary

Methods
`Collection<StreamerIndexEntry<E,K,V>>` `entries(int cnt)` Gets read-only collection of entries in the index.
`StreamerIndexEntry<E,K,V>` `entry(K key)` Gets index entry for given key.
`Set<StreamerIndexEntry<E,K,V>>` `entrySet(boolean asc, V fromVal, boolean fromIncl, V toVal, boolean toIncl)` Gets read-only set of index entries within given value range.
`Set<StreamerIndexEntry<E,K,V>>` `entrySet(V val)` Gets read-only set of index entries with given value.
`Collection<E>` `events(boolean asc, V fromVal, boolean fromIncl, V toVal, boolean toIncl)` Gets read-only collection of index events.
`Collection<E>` `events(int cnt)` Gets read-only collection of index events.
`Collection<E>` `events(V val)` Gets read-only collection of index events.
`StreamerIndexEntry<E,K,V>` `firstEntry()` Gets first entry in the index.
`Set<K>` `keySet(boolean asc, V fromVal, boolean fromIncl, V toVal, boolean toIncl)` Gets read-only set of index keys within given value range.
`Set<K>` `keySet(int cnt)` Gets read-only set of index keys.
`Set<K>` `keySet(V val)` Gets read-only set of index keys with given value.
`StreamerIndexEntry<E,K,V>` `lastEntry()` Gets last entry in the index.
`String` `name()` Index name.
`StreamerIndexPolicy` `policy()` Gets index policy.
`int` `size()`
`boolean` `sorted()` Returns `true` if index supports sorting and therefore can perform range operations.
`boolean` `unique()` Gets index unique flag.
`Collection<V>` `values(boolean asc, V fromVal, boolean fromIncl, V toVal, boolean toIncl)` Gets read-only collection of index values within given value range.
`Collection<V>` `values(int cnt)` Gets read-only collection of index values.

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

`iterator`

### Method Detail

#### name

    @Nullable
    String name()

Index name.

Returns:
  Index name.

#### unique

    boolean unique()

Gets index unique flag. If index is unique then exception will be thrown if key is already present in the index.

Returns:
  Index unique flag.

#### sorted

    boolean sorted()

Returns `true` if index supports sorting and therefore can perform range operations.

Note that sorting happens by value and not by key.

Returns:
  Index sorted flag.

#### policy

    StreamerIndexPolicy policy()

Gets index policy.

Returns:
  Index policy.

#### size

    int size()

Returns:
  Number entries in the index.

#### entry

    @Nullable
    StreamerIndexEntry<E,K,V> entry(K key)

Gets index entry for given key.

Parameters:
  `key` - Key for which to retrieve entry.
Returns:
  Entry for given key, or `null` if one could not be found.

#### entries

    Collection<StreamerIndexEntry<E,K,V>> entries(int cnt)

Gets read-only collection of entries in the index.

Returned collection is ordered for sorted indexes.

Parameters:
  `cnt` - If 0 then all entries are returned, if positive, then returned collection contains up to `cnt` elements (in ascending order for sorted indexes), if negative, then returned collection contains up to `|cnt|` elements (in descending order for sorted indexes and not supported for unsorted indexes).
Returns:
  Collection of entries in the index.

#### keySet

    Set<K> keySet(int cnt)

Gets read-only set of index keys.

Returned collection is ordered for sorted indexes.

Parameters:
  `cnt` - If 0 then all keys are returned, if positive, then returned collection contains up to `cnt` elements (in ascending order for sorted indexes), if negative, then returned collection contains up to `|cnt|` elements (in descending order for sorted indexes and not supported for unsorted indexes).
Returns:
  Read-only set of index keys within given position range.

#### values

    Collection<V> values(int cnt)

Gets read-only collection of index values.

Returned collection is ordered for sorted indexes.

Parameters:
  `cnt` - If 0 then all values are returned, if positive, then returned collection contains up to `cnt` elements (in ascending order for sorted indexes), if negative, then returned collection contains up to `|cnt|` elements (in descending order for sorted indexes and not supported for unsorted indexes).
Returns:
  Read-only collections of index values.

#### events

    Collection<E> events(int cnt)

Gets read-only collection of index events.

For sorted indexes events are guaranteed to be grouped by corresponding values, however the order of the events corresponding to the same value is not defined.

Parameters:
  `cnt` - If 0 then all values are returned, if positive, then returned collection contains up to `cnt` elements (in ascending order of values for sorted indexes), if negative, then returned collection contains up to `|cnt|` elements (in descending order of values for sorted indexes and not supported for unsorted indexes).
Returns:
  Read-only collections of index events.
Throws:
  `IllegalStateException` - If index is not configured to track events.
See Also:
  `StreamerIndexPolicy`

#### entrySet

    Set<StreamerIndexEntry<E,K,V>> entrySet(V val)

Gets read-only set of index entries with given value.

This operation is only available for sorted indexes.

Parameters:
  `val` - Value.
Returns:
  Read-only set of index entries with given value.

#### entrySet

    Set<StreamerIndexEntry<E,K,V>> entrySet(boolean asc,
                                          @Nullable
                                          V fromVal,
                                          boolean fromIncl,
                                          @Nullable
                                          V toVal,
                                          boolean toIncl)

Gets read-only set of index entries within given value range.

This operation is only available for sorted indexes.

Parameters:
  `asc` - `True` for ascending set.
  `fromVal` - From value, if `null`, then start from beginning.
  `toVal` - To value, if `null` then include all entries until the end.
  `fromIncl` - Whether or not left value is inclusive (ignored if `minVal` is `null`).
  `toIncl` - Whether or not right value is inclusive (ignored if `maxVal` is `null`).
Returns:
  Read-only set of index entries within given value range.

#### keySet

    Set<K> keySet(V val)

Gets read-only set of index keys with given value. Iteration order over this set has the same order as within index.

This operation is only available for sorted indexes.

Parameters:
  `val` - Value.
Returns:
  Read-only set of index entries with given value.

#### keySet

    Set<K> keySet(boolean asc,
                @Nullable
                V fromVal,
                boolean fromIncl,
                @Nullable
                V toVal,
                boolean toIncl)

Gets read-only set of index keys within given value range. Iteration order over this set has the same order as within index.

This operation is only available for sorted indexes.

Parameters:
  `asc` - `True` for ascending set.
  `fromVal` - From value, if `null`, then start from beginning.
  `toVal` - To value, if `null` then include all entries until the end.
  `fromIncl` - Whether or not left value is inclusive (ignored if `minVal` is `null`).
  `toIncl` - Whether or not right value is inclusive (ignored if `maxVal` is `null`).
Returns:
  Read-only set of index entries within given value range.

#### values

    Collection<V> values(boolean asc,
                       @Nullable
                       V fromVal,
                       boolean fromIncl,
                       @Nullable
                       V toVal,
                       boolean toIncl)

Gets read-only collection of index values within given value range. Iteration order over this collection has the same order as within index.

This operation is only available for sorted indexes.

Parameters:
  `asc` - `True` for ascending set.
  `fromVal` - From value, if `null`, then start from beginning.
  `toVal` - To value, if `null` then include all entries until the end.
  `fromIncl` - Whether or not left value is inclusive (ignored if `minVal` is `null`).
  `toIncl` - Whether or not right value is inclusive (ignored if `maxVal` is `null`).
Returns:
  Read-only set of index entries within given value range.

#### events

    Collection<E> events(@Nullable
                       V val)

Gets read-only collection of index events.

This operation is only available for sorted indexes.

Parameters:
  `val` - From value, if `null`, then start from beginning.
Returns:
  Read-only set of index entries with given value.

#### events

    Collection<E> events(boolean asc,
                       @Nullable
                       V fromVal,
                       boolean fromIncl,
                       @Nullable
                       V toVal,
                       boolean toIncl)

Gets read-only collection of index events.

Events are guaranteed to be sorted by corresponding values, however the order of the events corresponding to the same value is not defined.

This operation is only available for sorted indexes.

Parameters:
  `asc` - `True` for ascending set.
  `fromVal` - From value, if `null`, then start from beginning.
  `toVal` - To value, if `null` then include all entries until the end.
  `fromIncl` - Whether or not left value is inclusive (ignored if `minVal` is `null`).
  `toIncl` - Whether or not right value is inclusive (ignored if `maxVal` is `null`).
Returns:
  Read-only set of index entries within given value range.

#### firstEntry

    @Nullable
    StreamerIndexEntry<E,K,V> firstEntry()

Gets first entry in the index.

This operation is only available for sorted indexes.

Returns:
  First entry in the index, or `null` if index is empty.

#### lastEntry

    @Nullable
    StreamerIndexEntry<E,K,V> lastEntry()

Gets last entry in the index.

This operation is only available for sorted indexes.

Returns:
  Last entry in the index, or `null` if index is empty.

2015 Copyright © Apache Software Foundation

Follow @ApacheIgnite

Ignite Fabric | : ver. 1.0.0-RC1
Release Date | : February 17 2015