org.jsimpledb.kv.KVStore Maven / Gradle / Ivy


/*
 * Copyright (C) 2015 Archie L. Cobbs. All rights reserved.
 */

package org.jsimpledb.kv;

import java.util.Iterator;

/**
 * General API into a key/value store where the keys are sorted lexicographically as unsigned bytes.
 *
 * 
 * Implementations are not required to support accessing keys that start with {@code 0xff},
 * and if not may throw {@link IllegalArgumentException} if such keys are accessed.
 *
 * 
Thread Safety
 *
 * 
 * Instances must be thread safe, with the exception of the {@link Iterator} returned by {@link #getRange getRange()}.
 *
 * 
Lock-free Counters
 *
 * 
 * Implementations are encouraged to include support for encoding a 64 bit counter in a key/value pair such that the counter
 * can be efficiently {@linkplain #adjustCounter adjusted} by concurrent transactions without conflict.
 * In practice this means no locking is required to increment or decrement the counter by some amount, as long as
 * it's not necessary to actually directly read or write the counter value in the same transaction.
 * Whether counter adjustments are actually lock-free is implementation dependent, however, the counter methods
 * {@link #encodeCounter encodeCounter()}, {@link #decodeCounter decodeCounter()}, and {@link #adjustCounter adjustCounter()}
 * must function correctly as specified in all cases.
 *
 * 

 * How counters are encoded is specific to the implementation. Clients needing to read or write counter values directly
 * should use {@link #decodeCounter decodeCounter()} and {@link #encodeCounter encodeCounter()}, respectively.
 * Counters are removed using the normal methods (i.e., {@link #remove remove()} and {@link #removeRange removeRange()}).
 */
public interface KVStore {

    /**
     * Get the value associated with the given key, if any.
     *
     * 

     * Modifications to the returned {@code byte[]} array do not affect this instance.
     *
     * @param key key
     * @return value associated with key, or null if not found
     * @throws IllegalArgumentException if {@code key} starts with {@code 0xff} and such keys are not supported
     * @throws StaleTransactionException if an underlying transaction is no longer usable
     * @throws RetryTransactionException if an underlying transaction must be retried and is no longer usable
     * @throws NullPointerException if {@code key} is null
     */
    byte[] get(byte[] key);

    /**
     * Get the key/value pair having the smallest key greater than or equal to the given minimum, if any.
     *
     * 

     * If keys starting with {@code 0xff} are not supported by this instance, and {@code minKey} starts with {@code 0xff},
     * then this method returns null.
     *
     * 

     * Modifications to the returned {@code byte[]} arrays do not affect this instance.
     *
     * @param minKey minimum key (inclusive), or null for no minimum (get the smallest key)
     * @return smallest key/value pair with {@code key >= minKey}, or null if none exists
     * @throws StaleTransactionException if an underlying transaction is no longer usable
     * @throws RetryTransactionException if an underlying transaction must be retried and is no longer usable
     */
    KVPair getAtLeast(byte[] minKey);

    /**
     * Get the key/value pair having the largest key strictly less than the given maximum, if any.
     *
     * 

     * If keys starting with {@code 0xff} are not supported by this instance, and {@code maxKey} starts with {@code 0xff},
     * then this method behaves as if {@code maxKey} were null.
     *
     * 

     * Modifications to the returned {@code byte[]} arrays do not affect this instance.
     *
     * @param maxKey maximum key (exclusive), or null for no maximum (get the largest key)
     * @return largest key/value pair with {@code key < maxKey}, or null if none exists
     * @throws StaleTransactionException if an underlying transaction is no longer usable
     * @throws RetryTransactionException if an underlying transaction must be retried and is no longer usable
     */
    KVPair getAtMost(byte[] maxKey);

    /**
     * Iterate the key/value pairs in the specified range. The returned {@link Iterator}'s {@link Iterator#remove remove()}
     * must be supported and should have the same effect as invoking {@link #remove remove()} on the corresponding key.
     *
     * 

     * If keys starting with {@code 0xff} are not supported by this instance, and {@code minKey} starts with {@code 0xff},
     * then this method returns an empty iteration.
     *
     * 

     * If keys starting with {@code 0xff} are not supported by this instance, and {@code maxKey} starts with {@code 0xff},
     * then this method behaves as if {@code maxKey} were null.
     *
     * 

     * The returned {@link Iterator} must not throw {@link java.util.ConcurrentModificationException};
     * however, whether or not a "live" {@link Iterator} reflects any modifications made after its creation is
     * implementation dependent. Implementations that do make post-creation updates visible in the {@link Iterator},
     * even if the update occurs after some delay, must preserve the order in which the modifications actually occurred.
     *
     * 

     * The returned {@link Iterator} itself is not guaranteed to be thread safe.
     *
     * 

     * Some implementations may return {@link Iterator}s that are also {@link java.io.Closeable}; invokers of this
     * method are encouraged to detect and {@link java.io.Closeable#close close()} such instances, though this is not
     * required for correct behavior.
     *
     * 

     * Modifications to the returned {@link KVPair} key and value {@code byte[]} arrays do not affect this instance.
     *
     * @param minKey minimum key (inclusive), or null for no minimum (start at the smallest key)
     * @param maxKey maximum key (exclusive), or null for no maximum (end at the largest key)
     * @param reverse true to return key/value pairs in reverse order (i.e., keys descending)
     * @return iteration of key/value pairs in the range {@code minKey} (inclusive) to {@code maxKey} (exclusive)
     * @throws IllegalArgumentException if {@code minKey > maxKey}
     * @throws StaleTransactionException if an underlying transaction is no longer usable
     * @throws RetryTransactionException if an underlying transaction must be retried and is no longer usable
     */
    Iterator getRange(byte[] minKey, byte[] maxKey, boolean reverse);

    /**
     * Set the value associated with the given key.
     *
     * @param key key
     * @param value value
     * @throws IllegalArgumentException if {@code key} starts with {@code 0xff} and such keys are not supported
     * @throws StaleTransactionException if an underlying transaction is no longer usable
     * @throws RetryTransactionException if an underlying transaction must be retried and is no longer usable
     * @throws NullPointerException if {@code key} or {@code value} is null
     */
    void put(byte[] key, byte[] value);

    /**
     * Remove the key/value pair with the given key, if it exists.
     *
     * @param key key
     * @throws IllegalArgumentException if {@code key} starts with {@code 0xff} and such keys are not supported
     * @throws StaleTransactionException if an underlying transaction is no longer usable
     * @throws RetryTransactionException if an underlying transaction must be retried and is no longer usable
     * @throws NullPointerException if {@code key} is null
     */
    void remove(byte[] key);

    /**
     * Remove all key/value pairs whose keys are in a given range.
     *
     * 

     * The {@code minKey} must be less than or equal to {@code maxKey}; if they equal (and not null)
     * then nothing happens; if they are both null then all entries are deleted.
     *
     * 

     * If keys starting with {@code 0xff} are not supported by this instance, then:
     * 

     *  If {@code minKey} starts with {@code 0xff}, then no change occurs
     *  If {@code maxKey} starts with {@code 0xff}, then this method behaves as if {@code maxKey} were null
     * 
     *
     * @param minKey minimum key (inclusive), or null for no minimum
     * @param maxKey maximum key (exclusive), or null for no maximum
     * @throws IllegalArgumentException if {@code minKey > maxKey}
     * @throws StaleTransactionException if an underlying transaction is no longer usable
     * @throws RetryTransactionException if an underlying transaction must be retried and is no longer usable
     */
    void removeRange(byte[] minKey, byte[] maxKey);

    /**
     * Encode a counter value into a {@code byte[]} value suitable for use with {@link #decodeCounter decodeCounter()}
     * and/or {@link #adjustCounter adjustCounter()}.
     *
     * @param value desired counter value
     * @return encoded counter value
     * @throws StaleTransactionException if an underlying transaction is no longer usable
     * @throws RetryTransactionException if an underlying transaction must be retried and is no longer usable
     */
    byte[] encodeCounter(long value);

    /**
     * Decode a counter value previously encoded by {@link #encodeCounter encodeCounter()}.
     *
     * @param value encoded counter value
     * @return decoded counter value
     * @throws IllegalArgumentException if {@code value} is not a valid counter value
     * @throws StaleTransactionException if an underlying transaction is no longer usable
     * @throws RetryTransactionException if an underlying transaction must be retried and is no longer usable
     * @throws NullPointerException if {@code value} is null
     */
    long decodeCounter(byte[] value);

    /**
     * Adjust the counter at the given key by the given amount.
     *
     * 
     * Ideally this operation should behave in a lock-free manner, so that concurrent transactions can invoke it without
     * conflict. However, when lock-free behavior occurs (if at all) depends on the implementation.
     *
     * 
     * If there is no value associated with {@code key}, or {@code key}'s value is not a valid counter encoding as
     * would be acceptable to {@link #decodeCounter decodeCounter()}, then how this operation affects {@code key}'s
     * value is undefined.
     *
     * @param key key
     * @param amount amount to adjust counter value by
     * @throws StaleTransactionException if an underlying transaction is no longer usable
     * @throws RetryTransactionException if an underlying transaction must be retried and is no longer usable
     * @throws NullPointerException if {@code key} is null
     */
    void adjustCounter(byte[] key, long amount);
}