Interface IKeyValueStore

public interface IKeyValueStore
Abstraction for key-value store systems.

Provides a minimum set of operations for interacting with the key-value store

Since:
11.0
Author:
Mihai Bob, Petru Galanton

  • Method Details

    • set

      void set(String key, Serializable value)
      Saves a Serializable object in the key-value store.

      If a value already exists for the given key, the value will be overwritten.

      Parameters:
      key - - the key where the value will be saved, cannot be null
      value - - Serializable object to persist in the key-value store
      Throws:
      IllegalArgumentException - if parameter key is null
      KeyValueStoreException - when there is an error communicating with the key-value store
      See Also:

    • set

      void set(String key, Serializable value, long timeout, TimeUnit unit)
      Saves a Serializable object in the key-value store with a specified expiration time.

      The key-value store will remove the data at the specified key in the specified time. If a value already exists for the given the key, it will be overwritten.

      Parameters:
      key - - the key where the value will be saved under, cannot be null
      value - - Serializable object to persist in the key-value store
      timeout - - specified expiration time
      unit - - time unit for the timeout parameter
      Throws:
      IllegalArgumentException - if parameter key or unit is null
      KeyValueStoreException - when there is an error communicating with the key-value store
      See Also:

    • setRaw

      void setRaw(String key, byte[] value)
      Similar to set(String, Serializable), except the byte array value is written in the key-value store as-is, without serializing it first.

      This method should be used for byte arrays to avoid an extra serialization. Values written with this method should be read with getRaw(String).

      Parameters:
      key - - the key where the byte array will be saved, cannot be null
      value - - the byte array to persist in the key-value store
      Throws:
      IllegalArgumentException - if parameter key is null
      KeyValueStoreException - when there is an error communicating with the key-value store
      See Also:

    • setRaw

      void setRaw(String key, byte[] value, long timeout, TimeUnit unit)
      Similar to set(String, Serializable, long, TimeUnit), except the byte array value is written in the key-value store as-is, without serializing it first.

      This method should be used for byte arrays to avoid an extra serialization. Values written with this method should be read with getRaw(String).

      Parameters:
      key - - the key where the value will be saved under, cannot be null
      value - - the byte array to persist in the key-value store
      timeout - - specified expiration time
      unit - - time unit for the timeout parameter
      Throws:
      IllegalArgumentException - if parameter key or unit is null
      KeyValueStoreException - when there is an error communicating with the key-value store
      See Also:

    • get

      <T extends Serializable> T get(String key, Class<T> valueType)
      Returns the value for the specified key
      Type Parameters:
      T - the return type which extends Serializable
      Parameters:
      key - - the key from where to retrieve the data
      valueType - - the Java type of the value
      Returns:
      saved value or null if nothing was found
      Throws:
      IllegalArgumentException - if key is null, or if the value is not assignment compatible with valueType
      KeyValueStoreException - when there is an error communicating with the key-value store
      See Also:

    • getRaw

      byte[] getRaw(String key)
      This method reads the byte array stored at the given key and returns the raw byte array without deserializing it first.

      This method should be used to read raw byte arrays written with setRaw(String, byte[]) or setRaw(String, byte[], long, TimeUnit). Values written with set(String, Serializable) or set(String, Serializable, long, TimeUnit) may also be read, in which case the client code is responsible to deserialize it.

      Parameters:
      key - - the key from where to retrieve the data
      Returns:
      the saved byte array or null if nothing was found
      Throws:
      IllegalArgumentException - if key is null
      KeyValueStoreException - when there is an error communicating with the key-value store
      See Also:

    • delete

      void delete(String key)
      Removes the specified key

      If the given key does not exist in the key-value store, no exception is thrown.

      Parameters:
      key - - the key to delete, cannot be null
      Throws:
      IllegalArgumentException - if key is null
      KeyValueStoreException - when there is an error communicating with the key-value store

    • deleteAll

      void deleteAll(String... keys)
      Removes the specified keys.

      This method is conceptually equivalent to calling {delete(String) multiple times. However, some implementations may provide a more efficient implementation of deleting multiple keys in a single call.

      Parameters:
      keys - - keys to be removed, cannot be null, but may be empty
      Throws:
      IllegalArgumentException - if parameter key is null
      KeyValueStoreException - when there is an error communicating with the key-value store

    • hasKey

      boolean hasKey(String key)
      Checks if the given key exists in the key-value store.
      Parameters:
      key - - the key to check for existence, cannot be null
      Returns:
      true if the key exists, otherwise false
      Throws:
      IllegalArgumentException - if parameter key is null
      KeyValueStoreException - when there is an error communicating with the key-value store

    • expire

      boolean expire(String key, long timeout, TimeUnit unit)
      Sets the expiration time for the given key.

      If the key previously did not have an expiration time, it will have the specified expiration time after this method returns. If the key previously had an expiration time it will be reset to the new expiration time.

      Parameters:
      key - - the key which will have its expiration time changed
      timeout - - the expiration time
      unit - - the units for the expiration time
      Returns:
      true if the given key already exists, otherwise false
      Throws:
      IllegalArgumentException - if parameter key is null
      KeyValueStoreException - when there is an error communicating with the key-value store

    • keyIterator

      IKeyValueStore.IKeyIterator keyIterator(IKeyPattern pattern)
      Provides a means to enumerate all keys in the key-value store, optionally matching a pattern.

      The return value is an iterator, as some implementations may choose to not load all keys in the key-value store all at once. NOTE: The iterator must be closed after it is no longer needed.

      This interface does not mandate that implementations provide any guarantees related to modifications in the key-value store during iteration. For example:

      • keys added after iteration has started may or may not be returned by the iterator
      • keys returned by the iterator may be deleted before iteration has completed

      Since keys may be fetched up-front or incrementally, the hasNext() and next() methods may also throw KeyValueStoreException. The remove() method may optionally be supported, but this interface does not require implementations to support it.

      Since the iterator may internally hold a connection to the key-value store, the iterator must be closed once iteration has completed and the iterator is no longer needed.

      Parameters:
      pattern - the pattern the returned keys should match, or null if all keys should be returned
      Returns:
      an iterator over all matching keys in the key-value store
      Throws:
      KeyValueStoreException - when there is an error communicating with the key-value store

    • keys

      Set<String> keys(IKeyPattern pattern)
      Returns all keys in the key-value store, optionally with a pattern to scope to a namespace.

      Only use this method when you need to retrieve ALL keys (within a namespace). When you want a subset, use the keyIterator(IKeyPattern) method instead.

      Warning: this method can greatly affect performance when ran against large databases. Use it with caution.

      Parameters:
      pattern - the pattern the scope to a namespace, or null if all keys should be returned
      Returns:
      A set of keys in the key-value store, never null

    • getNamespaceSeparator

      String getNamespaceSeparator()
      Returns the string which is used to separate namespaces in the key-value store. If the key-value store does not support namespaces then this method returns an empty string.
      Returns:
      the namespace separator

    • getKeyPatternBuilder

      IKeyPatternBuilder getKeyPatternBuilder()
      Returns a builder for creating key patterns.
      Returns:
      a key pattern builder.

    • serialize

      byte[] serialize(Serializable value)
      Serializes the given value, so it may be saved in raw byte-array for using setRaw(String, byte[]).
      Parameters:
      value - the value to be serialized
      Returns:
      the serialized value
      Throws:
      KeyValueStoreException - if a serialization error occurs

    • deserialize

      <T> T deserialize(byte[] bytes, Class<T> valueType)
      Deserializes the given byte array as an instance of the given class.
      Type Parameters:
      T - the return type
      Parameters:
      bytes - the bytes to deserialize
      valueType - the expected type
      Returns:
      the deserialized value
      Throws:
      IllegalArgumentException - if the deserialized value is not assignment compatible with valueType
      KeyValueStoreException - if a deserialization error occurs