IKeyValueStore.cs

using System;
using System.Collections.Generic;
using System.Data;
using System.Text;

namespace Ramp.Data
{
    /// <summary>
    ///     Represents a key value store that stores values as strings.
    /// </summary>
    public interface IKeyValueStore
    {
        /// <summary>
        ///     Gets the name of the default bucket used if null is specified for a bucket argument.
        /// </summary>
        string DefaultBucketName { get; }

        /// <summary>
        ///     Gets the name of the bucket used for storing metadata.
        /// </summary>
        string MetadataBucketName { get; }

        /// <summary>
        ///     Gets the encoding used for strings.
        /// </summary>
        Encoding Encoding { get; }

        /// <summary>
        ///     Get a string from the store. Returns defaultValue if no key is found.
        /// </summary>
        /// <param name="bucket"> The bucket, or null to use the default bucket. </param>
        /// <param name="key"> The key. </param>
        /// <param name="defaultValue"> The default value. </param>
        /// <returns> The matching string, or defaultValue if not found. </returns>
        /// <exception cref="ArgumentNullException"> Bucket or key is null. </exception>
        string GetStringOrDefault(string bucket, string key, string defaultValue = null);

        /// <summary>
        ///     Tries getting a string from the store.
        /// </summary>
        /// <param name="bucket"> The bucket, or null to use the default bucket. </param>
        /// <param name="key"> The key. </param>
        /// <param name="value"> The resulting value. </param>
        /// <returns> True if the value was found. </returns>
        /// <exception cref="ArgumentNullException"> Bucket or key is null. </exception>
        bool TryGetString(string bucket, string key, out string value);

        /// <summary>
        ///     Get a byte array from the store. Returns defaultValue if no key is found.
        /// </summary>
        /// <param name="bucket"> The bucket, or null to use the default bucket. </param>
        /// <param name="key"> The key. </param>
        /// <param name="defaultValue"> The default value. </param>
        /// <returns> The matching byte array, or null if not found. </returns>
        /// <exception cref="ArgumentNullException"> Bucket or key is null. </exception>
        byte[] GetBytesOrDefault(string bucket, string key, byte[] defaultValue = null);

        /// <summary>
        ///     Tries getting a byte array from the store.
        /// </summary>
        /// <param name="bucket"> The bucket, or null to use the default bucket. </param>
        /// <param name="key"> The key. </param>
        /// <param name="value"> The resulting value. </param>
        /// <returns> True if the value was found. </returns>
        /// <exception cref="ArgumentNullException"> Bucket or key is null. </exception>
        bool TryGetBytes(string bucket, string key, out byte[] value);

        /// <summary>
        ///     Get a generic value from the store using a TypeConverter. Returns defaultValue if no key is found or
        ///     converting the value to T fails.
        /// </summary>
        /// <typeparam name="T"> A type convertible from a string. </typeparam>
        /// <param name="bucket"> The bucket, or null to use the default bucket. </param>
        /// <param name="key"> The key. </param>
        /// <param name="defaultValue"> The default value. </param>
        /// <returns> The value. </returns>
        /// <exception cref="ArgumentNullException"> Key is null. </exception>
        T GetValueOrDefault<T>(string bucket, string key, T defaultValue = default(T));

        /// <summary>
        ///     Tries getting a value from the store.
        /// </summary>
        /// <param name="bucket"> The bucket, or null to use the default bucket. </param>
        /// <param name="key"> The key. </param>
        /// <param name="value"> The resulting value. </param>
        /// <returns> True if the value was found and converted. </returns>
        /// <exception cref="ArgumentNullException"> Bucket or key is null. </exception>
        bool TryGetValue<T>(string bucket, string key, out T value);

        /// <summary>
        ///     Set a string value in the store. Will add a new entry or overwrite an existing entry in the store.
        ///     The string will be UTF8 encoded.
        /// </summary>
        /// <param name="bucket"> The bucket, or null to use the default bucket. </param>
        /// <param name="key"> The key. </param>
        /// <param name="value"> The value. </param>
        /// <exception cref="ArgumentNullException"> Key is null. </exception>
        void Set(string bucket, string key, string value);

        /// <summary>
        ///     Set a byte array value in the store. Will add a new entry or overwrite an existing entry in the store.
        /// </summary>
        /// <param name="bucket"> The bucket, or null to use the default bucket. </param>
        /// <param name="key"> The key. </param>
        /// <param name="value"> The value. </param>
        /// <exception cref="ArgumentNullException"> Key is null. </exception>
        void Set(string bucket, string key, byte[] value);

        /// <summary>
        ///     Set a generic value in the store. The type must be convertible to a string. Will add a new entry or
        ///     overwrite an existing entry in the store.
        /// </summary>
        /// <typeparam name="T"> A type convertible to a string. </typeparam>
        /// <param name="bucket"> The bucket, or null to use the default bucket. </param>
        /// <param name="key"> The key. </param>
        /// <param name="value"> The value. </param>
        /// <exception cref="ArgumentNullException"> Key is null. </exception>
        void Set<T>(string bucket, string key, T value);

        /// <summary>
        ///     Delete an entry from the store.
        /// </summary>
        /// <param name="bucket"> The bucket, or null to use the default bucket. </param>
        /// <param name="key"> The key. </param>
        /// <returns> True if a matching entry was found and deleted. </returns>
        /// <exception cref="ArgumentNullException"> Key is null. </exception>
        bool Delete(string bucket, string key);

        /// <summary>
        ///     Check if an entry exists in the store.
        /// </summary>
        /// <param name="bucket"> The bucket, or null to use the default bucket. </param>
        /// <param name="key"> The key. </param>
        /// <returns> True if the entry exists. </returns>
        /// <exception cref="ArgumentNullException"> Key is null. </exception>
        bool Exists(string bucket, string key);

        /// <summary>
        ///     Get all keys and values within a bucket as byte arrays.
        /// </summary>
        /// <param name="bucket"> The bucket, or null to use the default bucket. </param>
        /// <returns></returns>
        IEnumerable<KeyValuePair<string, byte[]>> GetItemBytes(string bucket);

        /// <summary>
        ///     Get all keys and values within a bucket as strings.
        /// </summary>
        /// <param name="bucket"> The bucket, or null to use the default bucket. </param>
        /// <returns></returns>
        IEnumerable<KeyValuePair<string, string>> GetItemStrings(string bucket);

        /// <summary>
        ///     Get all key names within a bucket.
        /// </summary>
        /// <param name="bucket"> The bucket, or null to use the default bucket. </param>
        /// <returns></returns>
        IEnumerable<string> GetKeys(string bucket);

        /// <summary>
        ///     Begin a transaction with the underlying database.
        /// </summary>
        /// <returns> A database transaction object. </returns>
        IDbTransaction BeginTransaction();

        /// <summary>
        ///     Begin a transaction with the underlying database.
        /// </summary>
        /// <param name="isolationLevel"> The transaction isolation level. </param>
        /// <returns> A database transaction object. </returns>
        IDbTransaction BeginTransaction(IsolationLevel isolationLevel);
    }
}