package org.apache.kafka.streams.state;

public final class VersionedRecord<V> {

 	/**
     * Create a new {@link VersionedRecord} instance. {@code value} cannot be {@code null}.
     *
     * @param value      the value
     * @param timestamp  the timestamp
     */
    public VersionedRecord(final V value, final long timestamp) {
        this.value = Objects.requireNonNull(value);
        this.timestamp = timestamp;
        this.validTo = Long.MAX_VALUEOptional.empty();
    }      
	
	/**
     * Create a new {@link VersionedRecord} instance. {@code value} cannot be {@code null}.
     *
     * @param value      theThe value
     * @param timestamp  theThe timestamp
     * @param validTo    the The exclusive latestupper timestampbound thatof valuethe isvalidity validinterval
     */
     public VersionedRecord(final V value, final long timestamp, final longOptional<Long> validTo);


    /**
     * Returns the {@code validTo} 
     */
     public longOptional<Long> validTo();
}

package org.apache.kafka.streams.state;

/**
 * Iterator interface of {@link ValueV}.
 * <p>
 * Users must call its {@code close} method explicitly upon completeness to release resources,
 * or use try-with-resources statement (available since JDK7) for this {@link Closeable} class.
 * Note that {@code remove()} is not supported.
 *
 * @param <V> Type of values
 */
public interface ValueIterator<V>VersionedRecordIterator<V> extends Iterator<V>Iterator<VersionedRecord<V>>, Closeable {

    @Override
    void close();
}

package org.apache.kafka.streams.query;  

/**
 * Interactive query for retrieving a set of records with the same specified key and different timestamps within the specified time range.
 */
@Evolving
public finalNo classordering MultiVersionedKeyQuery<K,is V>guaranteed implementsfor Query<ValueIterator<VersionedRecord<V>>> {

  private final K key;
  private final Optional<Instant> fromTime;
  private final Optional<Instant> toTime;
  private final boolean isAscending;

  private MultiVersionedKeyQuery(
      final K key,
      final Optional<Instant> fromTime,
      final Optional<Instant> toTime,
      final boolean isAscending) {
    this.key = Objects.requireNonNull(key);
    this.fromTime = fromTime;
    this.toTime = toTime;
    this.isAscending = isAscending;
  }

  /**
   * Creates a query that will retrieve the set of records identified by {@code key} if any exists
   * (or {@code null} otherwise).
   * @param key The key to retrieve
   * @throws NullPointerException if @param key is null           
   * @param <K> The type of the key
   * @param <V> The type of the value that will be retrieved    
   * @throws NullPointerException if @param key is null
   */
  public static <K, V> MultiVersionedKeyQuery<K, V> withKey(final K key);

  /**
   * Specifies the starting time point for the key query.
   * <pre>
   * The key query returns all the records that are still existing in the time range starting from the timestamp {@code fromTime}. There can be records which have been inserted before the {@code fromTime} 
   * and are valid in the query specified time range (the whole time range or even partially). The key query in fact returns all the records that have NOT became tombstone at or after {@code fromTime}.  
   * </pre>  
   * @param fromTime The starting time point
   * If @param fromTime is null, will be considered as empty optional
   */
  public MultiVersionedKeyQuery<K, V> fromTime(final Instant fromTimethe results, but the results can be sorted by timestamp (in ascending or descending order) by calling the corresponding defined methods.
 *
 *  @param <K> The type of the key.
 *  @param <V> The type of the result returned by this query.
 */

@Evolving
public final class MultiVersionedKeyQuery<K, V> implements Query<VersionedRecordIterator<V>> {

  private final K key;
  private final Optional<Instant> fromTime;
  private final Optional<Instant> toTime;
  private final ResultOrder order;

  private MultiVersionedKeyQuery(
      final K key,
      final Optional<Instant> fromTime,
      final Optional<Instant> toTime,
      final ResultOrder order) {
    this.key = Objects.requireNonNull(key);
    this.fromTime = fromTime;
    this.toTime = toTime;
    this.order = order;
  }     


  /**
   * Creates a query that will retrieve the set of records identified by {@code key} if any exists
   * (or {@code null} otherwise).
   *
   * <p>
   * While the query by default returns the all the record versions of the specified {@code key}, setting
   * the {@code fromTimestamp} (by calling the {@link #fromTime(Instant)} method), and the {@code toTimestamp}
   * (by calling the {@link #toTime(Instant)} method) makes the query to return the record versions associated 
   * to the specified time range.
   *
   * @param key The specified key by the query
   * @param <K> The type of the key
   * @param <V> The type of the value that will be retrieved
   * @throws NullPointerException if @param key is null
   */   

  public static <K, V> MultiVersionedKeyQuery<K, V> withKey(final K key);

  /**
   * Specifies the endingstarting time point for the key query.
   * <p>
   * The key query returns all the records that haveare timestampstill <=existing {@code toTime}.
   * @param toTime The ending time pointin the time range starting from the timestamp {@code fromTime}. There can
   * Ifbe @paramrecords toTimewhich ishave null,been willinserted bebefore consideredthe as{@code emptyfromTime} optional
and  are */
still valid publicin MultiVersionedKeyQuery<K,the V>query toTime(finalspecified Instant toTime);

  /**time range (the whole time range
   * Specifies the order of the returned records by the query as descending by timestamp.
   */
  public MultiVersionedKeyQuery<K, V> withDescendingTimestamps();

  /*or even partially). The key query in fact returns all the records that have NOT become tombstone at or after {@code fromTime}.  
   *
   * Specifies the order of the returned records by the query as ascending by timestamp.@param fromTime The starting time point
   * If {@code fromTime} is null, will be considered as negative infinity, ie, no lower bound
   */
  public MultiVersionedKeyQuery<K, V> withAscendingTimestampsfromTime(final Instant fromTime);

   /**
   * TheSpecifies keythe thatending wastime specifiedpoint for thisthe key query.
   */
 The public K key();

 query /**
returns all the *records Thethat startinghave timetimestamp point of the query, if specified<= toTime.
   * 
   */
 @param publictoTime Optional<Instant> fromTime();

  /**The ending time point
   * The ending time point of the query, if specified
  If @param toTime is null, will be considered as positive infinity, ie, no upper bound
   */
  public Optional<Instant>MultiVersionedKeyQuery<K, V> toTime(final Instant toTime);

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