Package tkrzw_rpc

Class RemoteDBM

Object
RemoteDBM
public class RemoteDBM extends Object
Remote database manager.
Note:
All operations are thread-safe; Multiple threads can access the same database concurrently. The setDBMIndex affects all threads so it should be called before the object is shared.

  • Field Details

    • ANY_BYTES

      public static byte[] ANY_BYTES
      The special bytes value for no-operation or any data.

    • ANY_STRING

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

  • Constructor Details

    • RemoteDBM

      public RemoteDBM()
      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.

    • connect

      public Status connect(String address, double timeout, String auth_config)
      Connects to the server.
      Parameters:
      address - The address or the host name of the server and its port number. For IPv4 address, it's like "127.0.0.1:1978". For IPv6, it's like "[::1]:1978".
      timeout - The timeout in seconds for connection and each operation. Negative means unlimited.
      auth_config - The authentication configuration. It it is empty or null, no authentication is done. If it begins with "ssl:", the SSL authentication is done. Key-value parameters in "key=value,key=value,..." format comes next. For SSL, "key", "cert", and "root" parameters specify the paths of the client private key file, the client certificate file, and the root CA certificate file respectively. SSL is usable only if the Java runtime system supports the TLS and ALPN protocol.
      Returns:
      The result status.

    • connect

      public Status connect(String address, double timeout)
      Conects to the server.
      Parameters:
      address - The address or the host name of the server and its port number. For IPv4 address, it's like "127.0.0.1:1978". For IPv6, it's like "[::1]:1978".
      timeout - The timeout in seconds for connection and each operation. Negative means unlimited.
      Returns:
      The result status.

    • connect

      public Status connect(String address)
      Conects to the server.
      Parameters:
      address - The address or the host name of the server and its port number. For IPv4 address, it's like "127.0.0.1:1978". For IPv6, it's like "[::1]:1978".
      Returns:
      The result status.

    • disconnect

      public Status disconnect()
      Disconnects the connection to the server.
      Returns:
      The result status.

    • setDBMIndex

      public Status setDBMIndex(int dbmIndex)
      Sets the index of the DBM to access.
      Parameters:
      dbmIndex - The index of the DBM to access.
      Returns:
      The result status.

    • echo

      public String echo(String message, Status status)
      Sends a message and gets back the echo message.
      Parameters:
      message - The message to send.
      status - A status object to which the result status is assigned. If it is null, it is not used.
      Returns:
      The echo message or null on failure.

    • echo

      public String echo(String message)
      Sends a message and gets back the echo message, without status assignment.
      Parameters:
      message - The message to send.
      Returns:
      The echo message or null on failure.

    • inspect

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

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

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

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

    • compareExchangeAdvanced

      public Status.And<byte[]> compareExchangeAdvanced(byte[] key, byte[] expected, byte[] desired, double retryWait, boolean notify)
      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.
      retryWait - The maximum wait time in seconds before retrying. If it is zero, no retry is done. If it is positive, retry is done after waiting for the notifications of the next update for the time at most.
      notify - If true, a notification signal is sent to wake up retrying threads.
      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.

    • compareExchangeAdvanced

      public Status.And<String> compareExchangeAdvanced(String key, String expected, String desired, double retryWait, boolean notify)
      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.
      retryWait - The maximum wait time in seconds before retrying. If it is zero, no retry is done. If it is positive, retry is done after waiting for the notifications of the next update for the time at most.
      notify - If true, a notification signal is sent to wake up retrying threads.
      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.

    • 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 data 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 data 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(double retryWait, Status status)
      Gets the first record and removes it.
      Parameters:
      retryWait - The maximum wait time in seconds before retrying. If it is zero, no retry is done. If it is positive, retry is done after waiting for the notifications of the next update for the time at most.
      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(double retryWait, Status status)
      Gets the first record as strings and removes it.
      Parameters:
      retryWait - The maximum wait time in seconds before retrying. If it is zero, no retry is done. If it is positive, retry is done after waiting for the notifications of the next update for the time at most.
      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, boolean notify)
      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.
      notify - If true, notification signal is sent.
      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, boolean notify)
      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.
      notify - If true, notification signal is sent.
      Returns:
      The result status.

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

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

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