/**
* Returns a copy of the value for the given key, or null if no matching entry exists.
*
* <p>If the entry must be locked, ownership of the key instance is transferred. The key must not
* be modified after calling this method.
*
* @param txn optional transaction; pass null for {@link LockMode#READ_COMMITTED READ_COMMITTED}
* locking behavior
* @param key non-null key
* @return copy of value, or null if entry doesn't exist
* @throws NullPointerException if key is null
* @throws IllegalArgumentException if transaction belongs to another database instance
*/
public default byte[] load(Transaction txn, byte[] key) throws IOException {
Cursor c = newCursor(txn);
try {
c.find(key);
return c.value();
} finally {
c.reset();
}
}
/**
* Unconditionally associates a value with the given key.
*
* <p>If the entry must be locked, ownership of the key instance is transferred. The key must not
* be modified after calling this method.
*
* @param txn optional transaction; pass null for auto-commit mode
* @param key non-null key
* @param value value to store; pass null to delete
* @throws NullPointerException if key is null
* @throws IllegalArgumentException if transaction belongs to another database instance
* @throws ViewConstraintException if entry is not permitted
*/
public default void store(Transaction txn, byte[] key, byte[] value) throws IOException {
Cursor c = newCursor(txn);
try {
c.autoload(false);
c.find(key);
c.store(value);
} finally {
c.reset();
}
}
/**
* Unconditionally associates a value with the given key, returning the previous value.
*
* <p>If the entry must be locked, ownership of the key instance is transferred. The key must not
* be modified after calling this method.
*
* @param txn optional transaction; pass null for auto-commit mode
* @param key non-null key
* @param value value to store; pass null to delete
* @return copy of previous value, or null if none
* @throws NullPointerException if key is null
* @throws IllegalArgumentException if transaction belongs to another database instance
* @throws ViewConstraintException if entry is not permitted
*/
public default byte[] exchange(Transaction txn, byte[] key, byte[] value) throws IOException {
Cursor c = newCursor(txn);
try {
c.find(key);
byte[] old = c.value();
c.store(value);
return old;
} finally {
c.reset();
}
}
/**
* Associates a value with the given key, but only if a corresponding value already exists.
*
* <p>If the entry must be locked, ownership of the key instance is transferred. The key must not
* be modified after calling this method.
*
* @param txn optional transaction; pass null for auto-commit mode
* @param key non-null key
* @param value value to insert; pass null to delete
* @return false if no existing entry
* @throws NullPointerException if key is null
* @throws IllegalArgumentException if transaction belongs to another database instance
* @throws ViewConstraintException if entry is not permitted
*/
public default boolean replace(Transaction txn, byte[] key, byte[] value) throws IOException {
Cursor c = newCursor(txn);
try {
c.autoload(false);
c.find(key);
if (c.value() == null) {
return false;
}
c.store(value);
return true;
} finally {
c.reset();
}
}
/**
* Associates a value with the given key, but only if the given old value matches.
*
* <p>If the entry must be locked, ownership of the key instance is transferred. The key must not
* be modified after calling this method.
*
* @param txn optional transaction; pass null for auto-commit mode
* @param key non-null key
* @param oldValue expected existing value, which can be null
* @param newValue new value to update to; pass null to delete
* @return false if existing value doesn't match
* @throws NullPointerException if key is null
* @throws IllegalArgumentException if transaction belongs to another database instance
* @throws ViewConstraintException if entry is not permitted
*/
public default boolean update(Transaction txn, byte[] key, byte[] oldValue, byte[] newValue)
throws IOException {
Cursor c = newCursor(txn);
try {
c.autoload(oldValue != null);
c.find(key);
if (!Arrays.equals(c.value(), oldValue)) {
return false;
}
c.store(newValue);
return true;
} finally {
c.reset();
}
}
