package org.apache.kafka.streams.query;


/**
 * Interactive query for retrieving a set of records with keys within a specified key range and time
 * range.
 */

@Evolving
public final class MultiVersionedRangeQuery<K, V> implements
    Query<KeyValueIterator<K, VersionedRecord<V>>> {

  private final Optional<K> lower;
  private final Optional<K> upper;
  private final Optional<Instant> fromTime;
  private final Optional<Instant> toTime;

  private finalMultiVersionedRangeQuery(
 boolean isKeyAscending;
  private final boolean isTimeAscending;
  private final boolean isOrderedByKey;

  private MultiVersionedRangeQuery(
      final Optional<K> lower,
      final Optional<K> upper,
      final Optional<Instant> fromTime,
      final Optional<Instant> toTime,) {
    this.lower = finallower;
 boolean isOrderedByKey,
  this.upper = upper;
  final boolean isKeyAscending,
   this.fromTime = fromTime;
    finalthis.toTime boolean isTimeAscending) {= toTime;
  }

  this.lower = lower; /** 
    this.upper = upper;
    this.fromTime = fromTime;
    this.toTime = toTime;* Interactive range query using a lower and upper bound to filter the keys returned. * For each 
   * this.isOrderedByKeykey =the isOrderedByKey;
records valid within the this.isKeyAscendingspecified =time isKeyAscending;
range are   thisreturned.isTimeAscending =* isTimeAscending;
In case }

the time range /**is 
   * Interactivenot rangespecified queryjust usingthe alatest lowerrecord andfor uppereach boundkey tois filterreturned. the
 keys returned. * For@param eachlower 
The key that * keyspecifies the recordslower validbound withinof the specifiedrange time
 range are returned.* *@param Inupper caseThe thekey timethat rangespecifies isthe 
upper bound of *the notrange specified
 just the latest* record@param for<K> eachThe key istype returned. 
   * @param lower<V> The keyvalue thattype specifies
 the lower bound*/ of
 the range 
public static <K, *V> @paramMultiVersionedRangeQuery<K, upperV> ThewithKeyRange(final keyK thatlower, specifiesfinal theK upper);


 bound of the range   /**
   * @paramInteractive <K> The key type 
   * @param <V> The value type range query using a lower bound to filter the keys returned. * For each key the
   */ 
records valid within publicthe staticspecified <K,time V>range MultiVersionedRangeQuery<K,are V> withKeyRange(final K lower, final K upper);


   /**
   * Interactive range query using a lower bound to filter the keys returned. * For each key the
   * records valid within the specified time range are returned. * In case the time range is not
   * specified just the latest record for each key is returned.
   * @param lower The key that specifies the lower bound of the range
   * @param <K>   The key type
   * @param <V>   The value type
   */
  public static <K, V> MultiVersionedRangeQuery<K, V> withLowerKeyBound(final K lower);

  /**
   * Interactive range query using a lower bound to filter the keys returned. * For each key the
   * records valid within the specified time range are returned. * In case the time range is not
   * specified just the latest record for each key is returned.
   * @param upper The key that specifies the lower bound of the range
   * @param <K>   The key type
   * @param <V>   The value type
   */
  public static <K, V> MultiVersionedRangeQuery<K, V> withUpperKeyBound(final K upper);

  /**
   * Interactive scan query that returns all records in the store. * For each key the records valid
   * within the specified time range are returned. * In case the time range is not specified just
   * the latest record for each key is returned.
   * @param <K> The key type
   * @param <V> The value type
   */
  public static <K, V> MultiVersionedRangeQuery<K, V> allKeys();

  /**
   * Specifies the starting time point for the key query. The range query returns all the records
   * that are valid in the time range starting from the timestamp {@code fromTime}.
   * @param fromTime The starting time point
   */
  public MultiVersionedRangeQuery<K, V> fromTime(Instant fromTime);

  /**
   * Specifies the ending time point for the key query. The range query returns all the records that
   * have timestamp <= {@code toTime}.
   * @param toTime The ending time point
   */
  public MultiVersionedRangeQuery<K, V> toTime(Instant toTime);

   /**
   * Specifies the overall order of returned records by key
   */
  public MultiVersionedRangeQuery<K, V> orderByKey();

   /**
   * Specifies the overall order of returned records by timestamp
   */
  public MultiVersionedRangeQuery<K, V> orderByTimestamp();

   /**
   * Specifies the order of keys as ascending.
   */
  public MultiVersionedRangeQuery<K, V> withAscendingKeys(); 

    /**
   * Specifies the order of keys as descending.
   */
  public MultiVersionedRangeQuery<K, V> withDescendingKeys();

  /**    
   * Specifies the order of the timestamps as ascending.
   */
  public MultiVersionedRangeQuery<K, V> withAscendingTimestamps();    

  /**    
   * Specifies the order of the timestamps as descending.
   */
  public MultiVersionedRangeQuery<K, V> withDescendingTimestamps();

  /**
   * The lower bound of the query, if specified.
   */
  public Optional<K> lowerKeyBound();

  /**
   * The upper bound of the query, if specified
   */
  public Optional<K> upperKeyBound();

  /**
   * The starting time point of the query, if specified
   */
  public Optional<Instant> fromTime();

  /**
   * The ending time point of the query, if specified
   */
  public Optional<Instant> toTime();

  /**
   * @return true if the query orders the returned records by key 
   */
  public boolean isOrderedByKey();

  /**
   * @return true if the query returns records in ascending order of keys
   */
  public boolean isKeyAscending();

  /**
   * @return true if the query returns records in ascending order of timestamps
   */
  public boolean isTimeAscending();

}