Package kvd.client

Class KvdClient

java.lang.Object
kvd.client.KvdClient
All Implemented Interfaces:
AutoCloseable, KvdOperations
public class KvdClient extends Object implements KvdOperations, AutoCloseable
KvdClient is the public API that clients should use to interact with the server.

Example usage:

  try(KvdClient client = new KvdClient("kvd.example.com:3030")) {
    try(DataOutputStream out = new DataOutputStream(client.put("test"))) {
      out.writeLong(42);
    }
  }
All KvdOperations methods implemented in this class execute a single operation transaction on the server that is automatically committed when the operation completes. They partake in resource locking the same way as KvdTransaction operations. The main difference between KvdTransaction operations is that operations in KvdClient are auto committed. For manual commit/rollback start a new Transaction with beginTransaction()

Note: KvdClient(java.lang.String) establishes a single socket connection to the server that it keeps alive until close() is called.

Note: KvdClient is thread-safe.

  • Constructor Details

    • KvdClient

      public KvdClient(String serverAddress)
      Create a new KvdClient instance connecting to the server. Use KvdClientBuilder to create a KvdClient with non standard options.
      Parameters:
      serverAddress - in the form host:port. Port can be omitted and 3030 is used in this case.

  • Method Details

    • putAsync

      public Future<OutputStream> putAsync(byte[] key)
      Description copied from interface: KvdOperations
      Put a new value or replace an existing.
      Specified by:
      putAsync in interface KvdOperations
      Parameters:
      key - key with which the specified value is to be associated
      Returns:
      Future that evaluates either to an OutputStream to be used to stream the value in. or fails (e.g. on optimistic lock or deadlock). Close the OutputStream to signal that the value is complete.

    • getAsync

      public Future<InputStream> getAsync(byte[] key)
      Description copied from interface: KvdOperations
      Returns the value to which the specified key is mapped
      Specified by:
      getAsync in interface KvdOperations
      Parameters:
      key - the key whose associated value is to be returned
      Returns:
      Future that evaluates either to an InputStream for keys that exist or null for keys that don't exist on the server.

    • containsAsync

      public Future<Boolean> containsAsync(byte[] key)
      Description copied from interface: KvdOperations
      The returned Future evaluates to true if the key exists on the server, false otherwise
      Specified by:
      containsAsync in interface KvdOperations
      Parameters:
      key - The key whose presence is to be tested
      Returns:
      Future evaluates to true if the key exists on the server, false otherwise

    • removeAsync

      public Future<Boolean> removeAsync(byte[] key)
      Description copied from interface: KvdOperations
      Removes the mapping for the specified key from the server.
      Specified by:
      removeAsync in interface KvdOperations
      Parameters:
      key - key whose mapping is to be removed
      Returns:
      Future which evaluates to true if the key/value was removed from the server, false otherwise.

    • close

      public void close()
      Waits for pending requests to finish and closes the connection to the server. Once closed this instance can't be reused and must be discarded.
      Specified by:
      close in interface AutoCloseable

    • isClosed

      public boolean isClosed()
      Check if the KvdClient can still be used.
      Returns:
      true if the instance is closed, false otherwise.

    • beginTransactionAsync

      public Future<KvdTransaction> beginTransactionAsync(long timeoutMs)
      Begin a new transaction with the specified timeout. Also see {beginTransaction(long)
      Parameters:
      timeoutMs - The transaction timeout in milliseconds or 0 for no timeout. If the timeout is exceeded the transaction is aborted (rollback).
      Returns:
      Future that evaluates to a KvdTransaction when the server has created the transaction

    • beginTransaction

      public KvdTransaction beginTransaction(long timeoutMs)
      Begin a new transaction with the specified timeout and waits until the transaction has been created on the server. Normally this method should be used in a try-with-resource block to make sure the transaction is closed. Note that you have to commit the transaction manually to make changes permanent before the try-with-resource block closes the transaction. Also consider using withTransaction(KvdWork) which automatically commits transactions and also allows outer/inner units of work to share the same transaction to improve code reusability
      Parameters:
      timeoutMs - The transaction timeout in milliseconds or 0 for no timeout. If the timeout is exceeded the transaction is aborted (rollback).
      Returns:
      KvdTransaction

    • beginTransaction

      public KvdTransaction beginTransaction()
      See beginTransaction(long) except this method uses the default transaction timeout
      Returns:
      KvdTransaction

    • withTransaction

      public <T> T withTransaction(KvdWork<T> work)
      Execute a new or join an existing KvdTransaction that has been started either with withTransaction(KvdWork) or withTransactionVoid(KvdVoidWork). A new transaction is started with the default timeout. The transaction is automatically committed when the most outer KvdWork finishes or aborted (rollback) when the KvdWork throws an exceptions.
      Type Parameters:
      T - Result type of the KvdWork
      Parameters:
      work - the unit of work to be executed within the transaction
      Returns:
      The result of the unit of work

    • withTransactionVoid

      public void withTransactionVoid(KvdVoidWork work)
      Same as withTransaction(KvdWork) except this does not return a result
      Parameters:
      work - the unit of work to be executed within the transaction

    • getTransactionDefaultTimeoutMs

      public long getTransactionDefaultTimeoutMs()
      Retrieve the default transaction timeout in milliseconds, 0 means no timeout. This value can only be set when the KvdClient is constructed through the KvdClientBuilder
      Returns:
      The default transaction timeout in milliseconds

    • removeAllAsync

      public Future<Boolean> removeAllAsync()
      Removes all keys and values from the database.
      Returns:
      Future which evaluates to true if when all key/values have been removed from the server, false otherwise.

    • removeAll

      public Boolean removeAll()
      Remove all keys and values from the database.