Package tkrzw

Class DBM

Object
DBM
public class DBM extends Object
Polymorphic database manager.
Note:
All operations except for open and close are thread-safe; Multiple threads can access the same database concurrently. You can specify a data structure when you call the "open" method. Every opened database must be closed explicitly by the "close" method to avoid data corruption. Moreover, every unused database object should be destructed by the "destruct" method to free resources.

  • Field Details

    • ANY_BYTES

      public static final byte[] ANY_BYTES
      The special bytes value for no-operation or any data.
      Note:
      The actual value is set by the native code.

    • ANY_STRING

      public static final String ANY_STRING
      The special string value for no-operation or any data.

  • Constructor Details

    • DBM

      public DBM()
      Constructor.

  • Method Details

    • destruct

      public void destruct()
      Destructs the object and releases resources.
      Note:
      The database is closed implicitly if it has not been closed.

    • open

      public Status open(String path, boolean writable, Map<String,String> params)
      Opens a database file.
      Parameters:
      path - A path of the file.
      writable - If true, the file is writable. If false, it is read-only.
      params - Optional parameters. If it is null, it is ignored.
      Returns:
      The result status.
      Note:
      The extension of the path indicates the type of the database.
      • .tkh : File hash database (HashDBM)
      • .tkt : File tree database (TreeDBM)
      • .tks : File skip database (SkipDBM)
      • .tkmt : On-memory hash database (TinyDBM)
      • .tkmb : On-memory tree database (BabyDBM)
      • .tkmc : On-memory cache database (CacheDBM)
      • .tksh : On-memory STL hash database (StdHashDBM)
      • .tkst : On-memory STL tree database (StdTreeDBM)

      The optional parameters can include options for the file opening operation.

      • truncate (bool): True to truncate the file.
      • no_create (bool): True to omit file creation.
      • no_wait (bool): True to fail if the file is locked by another process.
      • no_lock (bool): True to omit file locking.
      • sync_hard (bool): True to do physical synchronization when closing.

      The optional parameter "dbm" supercedes the decision of the database type by the extension. The value is the type name: "HashDBM", "TreeDBM", "SkipDBM", "TinyDBM", "BabyDBM", "CacheDBM", "StdHashDBM", "StdTreeDBM".

      The optional parameter "file" specifies the internal file implementation class. The default file class is "MemoryMapAtomicFile". The other supported classes are "StdFile", "MemoryMapAtomicFile", "PositionalParallelFile", and "PositionalAtomicFile".

      For HashDBM, these optional parameters are supported.

      • update_mode (string): How to update the database file: "UPDATE_IN_PLACE" for the in-palce or "UPDATE_APPENDING" for the appending mode.
      • record_crc_mode (string): How to add the CRC data to the record: "RECORD_CRC_NONE" to add no CRC to each record, "RECORD_CRC_8" to add CRC-8 to each record, "RECORD_CRC_16" to add CRC-16 to each record, or "RECORD_CRC_32" to add CRC-32 to each record.
      • record_comp_mode (string): How to compress the record data: "RECORD_COMP_NONE" to do no compression, "RECORD_COMP_ZLIB" to compress with ZLib, "RECORD_COMP_ZSTD" to compress with ZStd, "RECORD_COMP_LZ4" to compress with LZ4, "RECORD_COMP_LZMA" to compress with LZMA, "RECORD_COMP_RC4" to cipher with RC4, "RECORD_COMP_AES" to cipher with AES.
      • offset_width (int): The width to represent the offset of records.
      • align_pow (int): The power to align records.
      • num_buckets (int): The number of buckets for hashing.
      • restore_mode (string): How to restore the database file: "RESTORE_SYNC" to restore to the last synchronized state, "RESTORE_READ_ONLY" to make the database read-only, or "RESTORE_NOOP" to do nothing. By default, as many records as possible are restored.
      • fbp_capacity (int): The capacity of the free block pool.
      • min_read_size (int): The minimum reading size to read a record.
      • cache_buckets (bool): True to cache the hash buckets on memory.
      • cipher_key (string): The encryption key for cipher compressors.

      For TreeDBM, all optional parameters for HashDBM are available. In addition, these optional parameters are supported.

      • max_page_size (int): The maximum size of a page.
      • max_branches (int): The maximum number of branches each inner node can have.
      • max_cached_pages (int): The maximum number of cached pages.
      • page_update_mode (string): What to do when each page is updated: "PAGE_UPDATE_NONE" is to do no operation or "PAGE_UPDATE_WRITE" is to write immediately.
      • key_comparator (string): The comparator of record keys: "LexicalKeyComparator" for the lexical order, "LexicalCaseKeyComparator" for the lexical order ignoring case, "DecimalKeyComparator" for the order of the decimal integer numeric expressions, "HexadecimalKeyComparator" for the order of the hexadecimal integer numeric expressions, "RealNumberKeyComparator" for the order of the decimal real number expressions.

      For SkipDBM, these optional parameters are supported.

      • offset_width (int): The width to represent the offset of records.
      • step_unit (int): The step unit of the skip list.
      • max_level (int): The maximum level of the skip list.
      • restore_mode (string): How to restore the database file: "RESTORE_SYNC" to restore to the last synchronized state or "RESTORE_NOOP" to do nothing make the database read-only. By default, as many records as possible are restored.
      • sort_mem_size (int): The memory size used for sorting to build the database in the at-random mode.
      • insert_in_order (bool): If true, records are assumed to be inserted in ascending order of the key.
      • max_cached_records (int): The maximum number of cached records.

      For TinyDBM, these optional parameters are supported.

      • num_buckets (int): The number of buckets for hashing.

      For BabyDBM, these optional parameters are supported.

      • key_comparator (string): The comparator of record keys. The same ones as TreeDBM.

      For CacheDBM, these optional parameters are supported.

      • cap_rec_num (int): The maximum number of records.
      • cap_mem_size (int): The total memory size to use.

      All databases support taking update logs into files. It is enabled by setting the prefix of update log files.

      • ulog_prefix (str): The prefix of the update log files.
      • ulog_max_file_size (num): The maximum file size of each update log file. By default, it is 1GiB.
      • ulog_server_id (num): The server ID attached to each log. By default, it is 0.
      • ulog_dbm_index (num): The DBM index attached to each log. By default, it is 0.

      For the file "PositionalParallelFile" and "PositionalAtomicFile", these optional parameters are supported.

      • block_size (int): The block size to which all blocks should be aligned.
      • access_options (str): Values separated by colon. "direct" for direct I/O. "sync" for synchrnizing I/O, "padding" for file size alignment by padding, "pagecache" for the mini page cache in the process.

      If the optional parameter "num_shards" is set, the database is sharded into multiple shard files. Each file has a suffix like "-00003-of-00015". If the value is 0, the number of shards is set by patterns of the existing files, or 1 if they doesn't exist.

    • open

      public Status open(String path, boolean writable, String params)
      Opens a database file, with a string expression for optional parameters.
      Parameters:
      path - A path of the file.
      writable - If true, the file is writable. If false, it is read-only.
      params - The optional parameter expression in "key=value,key=value" format.
      Returns:
      The result status.

    • open

      public Status open(String path, boolean writable)
      Opens a database file, without optional parameters.
      Parameters:
      path - A path of the file.
      writable - If true, the file is writable. If false, it is read-only.
      Returns:
      The result status.

    • close

      public Status close()
      Closes the database file.
      Returns:
      The result status.

    • process

      public Status process(byte[] key, RecordProcessor proc, boolean writable)
      Processes a record with a processor.
      Parameters:
      key - The key of the record.
      proc - The processor object. Its "process" method is called. The first parameter is the key of the record. The second parameter is the value of the existing record, or null if it the record doesn't exist. The return value is a byte array to update the record value. If the return value is null, the record is not modified. If the return value is REMOVE, the record is removed.
      writable - True if the processor can edit the record.
      Returns:
      The result status.

    • process

      public Status process(String key, RecordProcessor proc, boolean writable)
      Processes a record with a processor.
      Parameters:
      key - The key of the record.
      proc - The processor object. Its "process" method is called. The first parameter is the key of the record. The second parameter is the value of the existing record, or null if it the record doesn't exist. The return value is a byte array to update the record value. If the return value is null, the record is not modified. If the return value is REMOVE, the record is removed.
      writable - True if the processor can edit the record.
      Returns:
      The result status.

    • contains

      public boolean contains(byte[] key)
      Checks if a record exists or not.
      Parameters:
      key - The key of the record.
      Returns:
      True if the record exists, or false if not.

    • contains

      public boolean contains(String key)
      Checks if a record exists or not, with string data.
      Parameters:
      key - The key of the record.
      Returns:
      True if the record exists, or false if not.

    • get

      public byte[] get(byte[] key, Status status)
      Gets the value of a record of a key.
      Parameters:
      key - The key of the record.
      status - The status object to store the result status. If it is null, it is ignored.
      Returns:
      The value data of the record or null on failure.

    • get

      public byte[] get(byte[] key)
      Gets the value of a record of a key, without status assignment.
      Parameters:
      key - The key of the record.
      Returns:
      The value data of the record or null on failure.

    • get

      public String get(String key, Status status)
      Gets the value of a record of a key, with string data.
      Parameters:
      key - The key of the record.
      status - The status object to store the result status. If it is null, it is ignored.
      Returns:
      The value data of the record or null on failure.

    • get

      public String get(String key)
      Gets the value of a record of a key, with string data, without status assignment.
      Parameters:
      key - The key of the record.
      Returns:
      The value data of the record or null on failure.

    • getMulti

      public 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 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 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 result status. If overwriting is abandoned, DUPLICATION_ERROR is returned.

    • set

      public 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 result status.

    • set

      public 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 result status. If overwriting is abandoned, DUPLICATION_ERROR is returned.

    • set

      public 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 result status.

    • setMulti

      public 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 result status. If there are records avoiding overwriting, DUPLICATION_ERROR is returned.

    • setMultiString

      public 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 result status. If there are records avoiding overwriting, DUPLICATION_ERROR is returned.

    • setAndGet

      public Status.And<byte[]> setAndGet(byte[] key, byte[] value, boolean overwrite)
      Sets a record and get the old 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 result status and the old value. If the record has not existed when inserting the new record, null is assigned as the value.

    • setAndGet

      public Status.And<String> setAndGet(String key, String value, boolean overwrite)
      Sets a record and get the old 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 result status and the old value. If the record has not existed when inserting the new record, null is assigned as the value.

    • remove

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

    • remove

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

    • removeMulti

      public Status removeMulti(byte[][] keys)
      Removes records of keys.
      Parameters:
      keys - The keys of records to remove.
      Returns:
      The result status. If there are missing records, NOT_FOUND_ERROR is returned.

    • removeMulti

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

    • removeAndGet

      public Status.And<byte[]> removeAndGet(byte[] key)
      Removes a record and get the value.
      Parameters:
      key - The key of the record.
      Returns:
      The result status and the record value. If the record does not exist, null is assigned

    • removeAndGet

      public Status.And<String> removeAndGet(String key)
      Removes a record and get the value.
      Parameters:
      key - The key of the record.
      Returns:
      The result status and the record value. If the record does not exist, null is assigned

    • append

      public 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 result status.
      Note:
      If there's no existing record, the value is set without the delimiter.

    • append

      public 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 result status.
      Note:
      If there's no existing record, the value is set without the delimiter.

    • appendMulti

      public 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 result status.
      Note:
      If there's no existing record, the value is set without the delimiter.

    • appendMulti

      public 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 result status.
      Note:
      If there's no existing record, the value is set without the delimiter.

    • compareExchange

      public 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 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 ANY_BYTES, no update is done.
      Returns:
      The result status. If the condition doesn't meet, INFEASIBLE_ERROR is returned.

    • compareExchange

      public 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 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 ANY_STRING, no update is done.
      Returns:
      The result status. If the condition doesn't meet, INFEASIBLE_ERROR is returned.

    • compareExchangeAndGet

      public Status.And<byte[]> compareExchangeAndGet(byte[] key, byte[] expected, byte[] desired)
      Does compare-and-exchange and/or gets the old value of the record.
      Parameters:
      key - The key of the record.
      expected - The expected value. If it is null, no existing record is expected. If it is 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 ANY_BYTES, no update is done.
      Returns:
      The result status and the.old value of the record If the condition doesn't meet, the state is INFEASIBLE_ERROR. If there's no existing record, the value is null.

    • compareExchangeAndGet

      public Status.And<String> compareExchangeAndGet(String key, String expected, String desired)
      Does compare-and-exchange and/or gets the old value of the record.
      Parameters:
      key - The key of the record.
      expected - The expected value. If it is null, no existing record is expected. If it is 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 ANY_STRING, no update is done.
      Returns:
      The result status and the.old value of the record If the condition doesn't meet, the state is INFEASIBLE_ERROR. If there's no existing record, the value is null.

    • increment

      public long increment(byte[] key, long inc, long init, Status status)
      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.
      status - The status object to store the result status. If it is null, it is ignored.
      Returns:
      The current value, or Long.MIN_VALUE on vailure
      Note:
      The record value is stored as an 8-byte big-endian integer. Negative is also supported.

    • increment

      public long increment(String key, long inc, long init, Status status)
      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.
      status - The status object to store the result status. If it is null, it is ignored.
      Returns:
      The current value, or Long.MIN_VALUE on vailure
      Note:
      The record value is stored as an 8-byte big-endian integer. Negative is also supported.

    • processMulti

      public Status processMulti(RecordProcessor.WithKey[] key_proc_pairs, boolean writable)
      Processes multiple records with processors.
      Parameters:
      key_proc_pairs - Pairs of the keys and their processor objects. Their "process" method is called. The first parameter is the key of the record. The second parameter is the value of the existing record, or null if it the record doesn't exist. The return value is a byte array to update the record value. If the return value is null, the record is not modified. If the return value is REMOVE, the record is removed.
      writable - True if the processors can edit the records.
      Returns:
      The result status.

    • compareExchangeMulti

      public 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 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 result status. If the condition doesn't meet, INFEASIBLE_ERROR is returned.

    • compareExchangeMultiString

      public 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 value is null, no existing record is expected. If the value is ANY_STRING, 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 result status. If the condition doesn't meet, INFEASIBLE_ERROR is returned.

    • rekey

      public 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 result status. If there's no matching record to the old key, NOT_FOUND_ERROR is returned. If the overwrite flag is false and there is an existing record of the new key, DUPLICATION ERROR is returned.
      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 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 result status.

    • popFirst

      public byte[][] popFirst(Status status)
      Gets the first record and removes it.
      Parameters:
      status - The status object to store the result status. If it is null, it is ignored.
      Returns:
      A pair of the key and the value of the first record, or null on failure.

    • popFirst

      public byte[][] popFirst()
      Gets the first record and removes it, without status assingment.
      Returns:
      A pair of the key and the value of the first record, or null on failure.

    • popFirstString

      public String[] popFirstString(Status status)
      Gets the first record as strings and removes it.
      Parameters:
      status - The status object to store the result status. If it is null, it is ignored.
      Returns:
      A pair of the key and the value of the first record, or null on failure.

    • popFirstString

      public String[] popFirstString()
      Gets the first record as strings and removes it, without status assingment.
      Returns:
      A pair of the key and the value of the first record, or null on failure.

    • pushLast

      public 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 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 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 result status.

    • processEach

      public Status processEach(RecordProcessor proc, boolean writable)
      Processes each and every record in the database with a processor.
      Parameters:
      proc - The processor object. Its "process" method is called. The first parameter is the key of the record. The second parameter is the value of the existing record, or null if it the record doesn't exist. The return value is a byte array to update the record value. If the return value is null, the record is not modified. If the return value is REMOVE, the record is removed.
      writable - True if the processor can edit the record.
      Returns:
      The result status.
      Note:
      The given function is called repeatedly for each record. It is also called once before the iteration and once after the iteration with both the key and the value being null.

    • count

      public long count()
      Gets the number of records.
      Returns:
      The number of records on success, or -1 on failure.

    • getFileSize

      public long getFileSize()
      Gets the current file size of the database.
      Returns:
      The current file size of the database, or -1 on failure.

    • getFilePath

      public String getFilePath()
      Gets the path of the database file.
      Returns:
      path The file path of the database, or null on failure.

    • getTimestamp

      public double getTimestamp()
      Gets the timestamp in seconds of the last modified time.
      Returns:
      The timestamp of the last modified time, or NaN on failure.

    • clear

      public Status clear()
      Removes all records.
      Returns:
      The result status.

    • rebuild

      public Status rebuild(Map<String,String> params)
      Rebuilds the entire database.
      Parameters:
      params - Optional parameters. If it is null, it is ignored.
      Returns:
      The result status.
      Note:
      The optional parameters are the same as the Open method. Omitted tuning parameters are kept the same or implicitly optimized. If it is null, it is ignored.

      In addition, HashDBM, TreeDBM, and SkipDBM supports the following parameters.

      • skip_broken_records (bool): If true, the operation continues even if there are broken records which can be skipped.
      • sync_hard (bool): If true, physical synchronization with the hardware is done before finishing the rebuilt file.

    • rebuild

      public Status rebuild()
      Rebuilds the entire database, without optional parameters.
      Returns:
      The result status.

    • shouldBeRebuilt

      public boolean shouldBeRebuilt()
      Checks whether the database should be rebuilt.
      Returns:
      True to be optimized or false with no necessity.

    • synchronize

      public 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 result status.
      Note:
      Only SkipDBM uses the optional parameters. The "merge" parameter specifies paths of databases to merge, separated by colon. The "reducer" parameter specifies the reducer to apply to records of the same key. "ReduceToFirst", "ReduceToSecond", "ReduceToLast", etc are supported.

    • synchronize

      public 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 result status.

    • copyFileData

      public 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 result status.

    • export

      public Status export(DBM destDBM)
      Exports all records to another database.
      Parameters:
      destDBM - The destination database.
      Returns:
      The result status.

    • exportToFlatRecords

      public Status exportToFlatRecords(File destFile)
      Exports all records of a database to a flat record file.
      Parameters:
      destFile - The file object to write records in.
      Returns:
      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 Status importFromFlatRecords(File srcFile)
      Imports records to a database from a flat record file.
      Parameters:
      srcFile - The file object to read records from.
      Returns:
      The result status.

    • exportKeysAsLines

      public Status exportKeysAsLines(File destFile)
      Exports the keys of all records as lines to a text file.
      Parameters:
      destFile - The file object to write keys in.
      Returns:
      The result status.
      Note:
      As the exported text file is smaller than the database file, scanning the text file by the search method is often faster than scanning the whole database.

    • inspect

      public Map<String,String> inspect()
      Inspects the database.
      Returns:
      A map of property names and their values.

    • isOpen

      public boolean isOpen()
      Checks whether the database is open.
      Returns:
      True if the database is open, or false if not.

    • isWritable

      public boolean isWritable()
      Checks whether the database is writable.
      Returns:
      True if the database is writable, or false if not.

    • isHealthy

      public boolean isHealthy()
      Checks whether the database condition is healthy.
      Returns:
      True if the database condition is healthy, or false if not.

    • isOrdered

      public boolean isOrdered()
      Checks whether ordered operations are supported.
      Returns:
      True if ordered operations are supported, or false if not.

    • search

      public 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. "containcase", "containword", and "containcaseword" extract keys considering case and word boundary. Ordered databases support "upper" and "lower" which extract keys whose positions are upper/lower than the pattern. "upperinc" and "lowerinc" are their inclusive versions.
      pattern - The pattern for matching.
      capacity - The maximum records to obtain. 0 means unlimited.
      Returns:
      An array of keys matching the condition.

    • search

      public 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. "containcase", "containword", and "containcaseword" extract keys considering case and word boundary. Ordered databases support "upper" and "lower" which extract keys whose positions are upper/lower than the pattern. "upperinc" and "lowerinc" are their inclusive versions.
      pattern - The pattern for matching.
      capacity - The maximum records to obtain. 0 means unlimited.
      Returns:
      An array of keys matching the condition.

    • makeIterator

      public Iterator makeIterator()
      Makes an iterator for each record.
      Returns:
      The iterator for each record.
      Note:
      Every iterator should be destructed explicitly by the "destruct" method.

    • toString

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

    • restoreDatabase

      public static Status restoreDatabase(String oldFilePath, String newFilePath, String className, long endOffset, byte[] cipherKey)
      Restores a broken database as a new healthy database.
      Parameters:
      oldFilePath - The path of the broken database.
      newFilePath - The path of the new database to be created.
      className - The name of the database class. If it is null or empty, the class is guessed from the file extension.
      endOffset - The exclusive end offset of records to read. Negative means unlimited. 0 means the size when the database is synched or closed properly. Using a positive value is not meaningful if the number of shards is more than one.
      cipherKey - The encryption key for cipher compressors. If it is null, an empty key is used.
      Returns:
      The result status.