Package kvd.client

Class 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 Detail

      • 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 Detail

      • 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

      • 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.