Package tkrzw

Class AsyncDBM

Object
AsyncDBM
public class AsyncDBM extends Object
Asynchronous database manager adapter.
Note:
This class is a wrapper of DBM for asynchronous operations. A task queue with a thread pool is used inside. Every method except for the constructor and the destructor is run by a thread in the thread pool and the result is set in the future oject of the return value. The caller can ignore the future object if it is not necessary. The destruct method waits for all tasks to be done. Therefore, the destructor should be called before the database is closed.

  • Constructor Details

    • AsyncDBM

      public AsyncDBM(DBM dbm, int numWorkerThreads)
      Constructor.
      Parameters:
      dbm - A database object which has been opened.
      numWorkerThreads - The number of threads in the internal thread pool.

  • Method Details

    • destruct

      public void destruct()
      Destructs the object and releases resources.
      Note:
      This method waits for all tasks to be done.

    • get

      public Future<Status.And<byte[]>> get(byte[] key)
      Gets the value of a record of a key.
      Parameters:
      key - The key of the record.
      Returns:
      The future for the status and the value data of the record. If there's no matching record, NOT_FOUND_ERROR is set.

    • get

      public Future<Status.And<String>> get(String key)
      Gets the value of a record of a key, with string data.
      Parameters:
      key - The key of the record.
      Returns:
      The future for the status and the value data of the record. If there's no matching record, NOT_FOUND_ERROR is set.

    • getMulti

      public Future<Status.And<Map<byte[],byte[]>>> getMulti(byte[][] keys)
      Gets the values of multiple records of keys.
      Parameters:
      keys - The keys of records to retrieve.
      Returns:
      A map of retrieved records. Keys which don't match existing records are ignored.

    • getMulti

      public Future<Status.And<Map<String,String>>> getMulti(String[] keys)
      Gets the values of multiple records of keys, with string data.
      Parameters:
      keys - The keys of records to retrieve.
      Returns:
      A map of retrieved records. Keys which don't match existing records are ignored.

    • set

      public Future<Status> set(byte[] key, byte[] value, boolean overwrite)
      Sets a record of a key and a value.
      Parameters:
      key - The key of the record.
      value - The value of the record.
      overwrite - Whether to overwrite the existing value if there's a record with the same key. If true, the existing value is overwritten by the new value. If false, the operation is given up and an error status is returned.
      Returns:
      The future for the result status. If overwriting is abandoned, DUPLICATION_ERROR is set.

    • set

      public Future<Status> set(byte[] key, byte[] value)
      Sets a record of a key and a value, with overwriting.
      Parameters:
      key - The key of the record.
      value - The value of the record.
      Returns:
      The future for the result status.

    • set

      public Future<Status> set(String key, String value, boolean overwrite)
      Sets a record of a key and a value, with string data.
      Parameters:
      key - The key of the record.
      value - The value of the record.
      overwrite - Whether to overwrite the existing value if there's a record with the same key. If true, the existing value is overwritten by the new value. If false, the operation is given up and an error status is returned.
      Returns:
      The future for the result status. If overwriting is abandoned, DUPLICATION_ERROR is set.

    • set

      public Future<Status> set(String key, String value)
      Sets a record of a key and a value, with string data, with overwriting.
      Parameters:
      key - The key of the record.
      value - The value of the record.
      Returns:
      The future for the result status.

    • setMulti

      public Future<Status> setMulti(Map<byte[],byte[]> records, boolean overwrite)
      Sets multiple records.
      Parameters:
      records - The records to store.
      overwrite - Whether to overwrite the existing value if there's a record with the same key. If true, the existing value is overwritten by the new value. If false, the operation is given up and an error status is returned.
      Returns:
      The future for the result status. If there are records avoiding overwriting, DUPLICATION_ERROR is set.

    • setMultiString

      public Future<Status> setMultiString(Map<String,String> records, boolean overwrite)
      Sets multiple records, with string data.
      Parameters:
      records - The records to store.
      overwrite - Whether to overwrite the existing value if there's a record with the same key. If true, the existing value is overwritten by the new value. If false, the operation is given up and an error status is returned.
      Returns:
      The future for the result status. If there are records avoiding overwriting, DUPLICATION_ERROR is set.

    • remove

      public Future<Status> remove(byte[] key)
      Removes a record of a key.
      Parameters:
      key - The key of the record.
      Returns:
      The future for the result status. If there's no matching record, NOT_FOUND_ERROR is set.

    • remove

      public Future<Status> remove(String key)
      Removes a record of a key, with string data.
      Parameters:
      key - The key of the record.
      Returns:
      The future for the result status. If there's no matching record, NOT_FOUND_ERROR is set.

    • removeMulti

      public Future<Status> removeMulti(byte[][] keys)
      Removes records of keys.
      Parameters:
      keys - The keys of records to remove.
      Returns:
      The future for the result status. If there are missing records, NOT_FOUND_ERROR is set.

    • removeMulti

      public Future<Status> removeMulti(String[] keys)
      Removes records of keys, with string data.
      Parameters:
      keys - The keys of records to remove.
      Returns:
      The future for the result status. If there are missing records, NOT_FOUND_ERROR is set.

    • append

      public Future<Status> append(byte[] key, byte[] value, byte[] delim)
      Appends data at the end of a record of a key.
      Parameters:
      key - The key of the record.
      value - The value to append.
      delim - The delimiter to put after the existing record.
      Returns:
      The future for the result status.
      Note:
      If there's no existing record, the value is set without the delimiter.

    • append

      public Future<Status> append(String key, String value, String delim)
      Appends data at the end of a record of a key, with string data.
      Parameters:
      key - The key of the record.
      value - The value to append.
      delim - The delimiter to put after the existing record.
      Returns:
      The future for the result status.
      Note:
      If there's no existing record, the value is set without the delimiter.

    • appendMulti

      public Future<Status> appendMulti(Map<byte[],byte[]> records, byte[] delim)
      Appends data to multiple records
      Parameters:
      records - The records to append.
      delim - The delimiter to put after the existing record.
      Returns:
      The future for the result status.
      Note:
      If there's no existing record, the value is set without the delimiter.

    • appendMulti

      public Future<Status> appendMulti(Map<String,String> records, String delim)
      Appends data to multiple records, with string data.
      Parameters:
      records - The records to append.
      delim - The delimiter to put after the existing record.
      Returns:
      The future for the result status.
      Note:
      If there's no existing record, the value is set without the delimiter.

    • compareExchange

      public Future<Status> compareExchange(byte[] key, byte[] expected, byte[] desired)
      Compares the value of a record and exchanges if the condition meets.
      Parameters:
      key - The key of the record.
      expected - The expected value. If it is null, no existing record is expected. If it is DBM.ANY_BYTES, an existing record with any value is expacted.
      desired - The desired value. If it is null, the record is to be removed. If it is DBM.ANY_BYTES, no update is done.
      Returns:
      The future for the result status. If the condition doesn't meet, INFEASIBLE_ERROR is set.

    • compareExchange

      public Future<Status> compareExchange(String key, String expected, String desired)
      Compares the value of a record and exchanges if the condition meets, with string data.
      Parameters:
      key - The key of the record.
      expected - The expected value. If it is null, no existing record is expected. If it is DBM.ANY_STRING, an existing record with any value is expacted.
      desired - The desired value. If it is null, the record is to be removed. If it is DBM.ANY_STRING, no update is done.
      Returns:
      The future for the result status. If the condition doesn't meet, INFEASIBLE_ERROR is set.

    • increment

      public Future<Status.And<Long>> increment(byte[] key, long inc, long init)
      Increments the numeric value of a record.
      Parameters:
      key - The key of the record.
      inc - The incremental value. If it is Long.MIN_VALUE, the current value is not changed and a new record is not created.
      init - The initial value.
      Returns:
      The future for the result status and the current value.
      Note:
      The record value is stored as an 8-byte big-endian integer. Negative is also supported.

    • increment

      public Future<Status.And<Long>> increment(String key, long inc, long init)
      Increments the numeric value of a record, with string data.
      Parameters:
      key - The key of the record.
      inc - The incremental value.
      init - The initial value.
      Returns:
      The future for the result status and the current value.
      Note:
      The record value is stored as an 8-byte big-endian integer. Negative is also supported.

    • compareExchangeMulti

      public Future<Status> compareExchangeMulti(Map<byte[],byte[]> expected, Map<byte[],byte[]> desired)
      Compares the values of records and exchanges if the condition meets.
      Parameters:
      expected - The record keys and their expected values. If the value is null, no existing record is expected. If the value is DBM.ANY_BYTES, an existing record with any value is expacted.
      desired - The record keys and their desired values. If the value is null, the record is to be removed.
      Returns:
      The future for the result status. If the condition doesn't meet, INFEASIBLE_ERROR is set.

    • compareExchangeMultiString

      public Future<Status> compareExchangeMultiString(Map<String,String> expected, Map<String,String> desired)
      Compares the values of records and exchanges if the condition meets, with string data.
      Parameters:
      expected - The record keys and their expected values. If the data is null, no existing record is expected. If the value is DBM.ANY_STRING, an existing record with any value is expacted.
      desired - The record keys and their desired values. If the data is null, the record is to be removed.
      Returns:
      The future for the result status. If the condition doesn't meet, INFEASIBLE_ERROR is set.

    • rekey

      public Future<Status> rekey(byte[] oldKey, byte[] newKey, boolean overwrite, boolean copying)
      Changes the key of a record.
      Parameters:
      oldKey - The old key of the record.
      newKey - The new key of the record.
      overwrite - Whether to overwrite the existing record of the new key.
      copying - Whether to retain the record of the old key.
      Returns:
      The future for the result status. If there's no matching record to the old key, NOT_FOUND_ERROR is set. If the overwrite flag is false and there is an existing record of the new key, DUPLICATION ERROR is set.
      Note:
      This method is done atomically. The other threads observe that the record has either the old key or the new key. No intermediate states are observed.

    • rekey

      public Future<Status> rekey(String oldKey, String newKey, boolean overwrite, boolean copying)
      Changes the key of a record, with string data.
      Parameters:
      oldKey - The old key of the record.
      newKey - The new key of the record.
      overwrite - Whether to overwrite the existing record of the new key.
      copying - Whether to retain the record of the old key.
      Returns:
      The future for the result status.

    • popFirst

      public Future<Status.And<byte[][]>> popFirst()
      Gets the first record and removes it.
      Returns:
      The future for the result status and a pair of the key and the value of the first record.

    • popFirstString

      public Future<Status.And<String[]>> popFirstString()
      Gets the first record as strings and removes it.
      Returns:
      The future for the result status and a pair of the key and the value of the first record.

    • pushLast

      public Future<Status> pushLast(byte[] value, double wtime)
      Adds a record with a key of the current timestamp.
      Parameters:
      value - The value of the record.
      wtime - The current wall time used to generate the key. If it is negative, the system clock is used.
      Returns:
      The future for the result status.
      Note:
      The key is generated as an 8-bite big-endian binary string of the timestamp. If there is an existing record matching the generated key, the key is regenerated and the attempt is repeated until it succeeds.

    • pushLast

      public Future<Status> pushLast(String value, double wtime)
      Adds a record with a key of the current timestamp.
      Parameters:
      value - The value of the record.
      wtime - The current wall time used to generate the key. If it is negative, the system clock is used.
      Returns:
      The future for the result status.
      Note:
      The key is generated as an 8-bite big-endian binary string of the timestamp. If there is an existing record matching the generated key, the key is regenerated and the attempt is repeated until it succeeds.

    • clear

      public Future<Status> clear()
      Removes all records.
      Returns:
      The future for the result status.

    • rebuild

      public Future<Status> rebuild(Map<String,String> params)
      Rebuilds the entire database.
      Parameters:
      params - Optional parameters. If it is null, it is ignored.
      Returns:
      The future for the result status.
      Note:
      The parameters work in the same way as with DBM::rebuild.

    • rebuild

      public Future<Status> rebuild()
      Rebuilds the entire database, without optional parameters.
      Returns:
      The future for the result status.

    • synchronize

      public Future<Status> synchronize(boolean hard, Map<String,String> params)
      Synchronizes the content of the database to the file system.
      Parameters:
      hard - True to do physical synchronization with the hardware or false to do only logical synchronization with the file system.
      params - Optional parameters. If it is null, it is ignored.
      Returns:
      The future for the result status.
      Note:
      The parameters work in the same way as with DBM::synchronize.

    • synchronize

      public Future<Status> synchronize(boolean hard)
      Synchronizes the content of the database to the file system.
      Parameters:
      hard - True to do physical synchronization with the hardware or false to do only logical synchronization with the file system.
      Returns:
      The future for the result status.

    • copyFileData

      public Future<Status> copyFileData(String destPath, boolean syncHard)
      Copies the content of the database file to another file.
      Parameters:
      destPath - A path to the destination file.
      syncHard - True to do physical synchronization with the hardware.
      Returns:
      The future for the result status.

    • export

      public Future<Status> export(DBM destDBM)
      Exports all records to another database.
      Parameters:
      destDBM - The destination database. The lefetime of the database object must last until the task finishes.
      Returns:
      The future for the result status.

    • exportToFlatRecords

      public Future<Status> exportToFlatRecords(File destFile)
      Exports all records of a database to a flat record file.
      Parameters:
      destFile - The file object to write records in. The lefetime of the file object must last until the task finishes.
      Returns:
      The future for the result status.
      Note:
      A flat record file contains a sequence of binary records without any high level structure so it is useful as a intermediate file for data migration.

    • importFromFlatRecords

      public Future<Status> importFromFlatRecords(File srcFile)
      Imports records to a database from a flat record file.
      Parameters:
      srcFile - The file object to read records from. The lefetime of the file object must last until the task finishes.
      Returns:
      The future for the result status.

    • search

      public Future<Status.And<byte[][]>> search(String mode, byte[] pattern, int capacity)
      Searches the database and get keys which match a pattern.
      Parameters:
      mode - The search mode. "contain" extracts keys containing the pattern. "begin" extracts keys beginning with the pattern. "end" extracts keys ending with the pattern. "regex" extracts keys partially matches the pattern of a regular expression. "edit" extracts keys whose edit distance to the pattern is the least. "editbin" extracts keys whose edit distance to the binary pattern is the least.
      pattern - The pattern for matching.
      capacity - The maximum records to obtain. 0 means unlimited.
      Returns:
      The future for the result status and an array of keys matching the condition.

    • search

      public Future<Status.And<String[]>> search(String mode, String pattern, int capacity)
      Searches the database and get keys which match a pattern, with string data.
      Parameters:
      mode - The search mode. "contain" extracts keys containing the pattern. "begin" extracts keys beginning with the pattern. "end" extracts keys ending with the pattern. "regex" extracts keys partially matches the pattern of a regular expression. "edit" extracts keys whose edit distance to the UTF-8 pattern is the least. "editbin" extracts keys whose edit distance to the binary pattern is the least.
      pattern - The pattern for matching.
      capacity - The maximum records to obtain. 0 means unlimited.
      Returns:
      The future for the result status and an array of keys matching the condition.

    • toString

      public String toString()
      Gets a string representation of the database.
      Overrides:
      toString in class Object