package org.apache.kafka.streams.query;


/**
 * Interactive query for retrieving a single record  from a versioned state store based on its key and timestamp.
 * <p>
 * See KIP-960 for more details.
 */
@Evolving
public final class KeyQuery<KVersionedKeyQuery<K, V> implements Query<V>Query<VersionedRecord<V>> {

    private final K key;
    private final boolean skipCache;
    private final Optional<Instant> asOfTimestamp;

    private KeyQueryVersionedKeyQuery(final K key, final Optional<Instant> asOfTimestamp, final boolean skipCache) {
        this.key = Objects.requireNonNull(key);
        this.asOfTimestamp = asOfTimestamp;
        this.skipCache = skipCache;
    }

    /**
     * Creates a query that will retrieve the latest record from a versioned state store identified by {@code key} if itthe key 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> KeyQuery<KVersionedKeyQuery<K, V> withKey(final K key);
    
    /**
     * Specifies the upperas inclusiveof boundtimestamp for the key query. The key query returns the record
     * with the greatest timestamp <= asOfTimestamp
     * @param asOfTimestamp The upperas inclusiveof boundtimestamp for timestamp
     */
    public KeyQuery<K, V> asOf(final Instant asOfTimestamp);
    
     /**
     * Specifies that the cache should be skipped during query evaluation. This means, that the query
     * will always get forwarded to the underlying store.if @param asOfTimestamp is null, it will be considered as Optional.empty()
     */
    public KeyQuery<KVersionedKeyQuery<K, V> skipCacheasOf(final Instant asOfTimestamp);

    /**
     * The key that was specified for this query.
     */
    public K getKeykey();

    /**
     * The timestamp of the query, if specified
     */
    public Optional<Instant> getAsOfTimestampasOfTimestamp();

    /**
     * The flag whether to skip the cache or not during query evaluation.
     */
    public boolean isSkipCache();
}

}