Skip to content

Commit

Permalink
javadoc: further comments
Browse files Browse the repository at this point in the history 
Signed-off-by: Jeronimo Irazabal <jeronimo.irazabal@gmail.com>

javadoc: further comments

Signed-off-by: Jeronimo Irazabal <jeronimo.irazabal@gmail.com>
  • Loading branch information
@jeroiraz
jeroiraz committed Dec 1, 2022
1 parent 45ed9f5 commit 22c139f
Showing 1 changed file with 104 additions and 10 deletions.
114 changes: 104 additions & 10 deletions src/main/java/io/codenotary/immudb4j/ImmuClient.java
View file
Expand Up @@ -565,6 +565,10 @@ public synchronized Entry getAtTx(byte[] key, long tx) throws KeyNotFoundExcepti
}

/**
* This method can be used to avoid additional latency while the server
* waits for the indexer to finish indexing but still guarantees that
* specific portion of the database history has already been indexed.
*
* @param key the key to look for
* @param tx the lowest transaction from which the associated entry should be
* retrieved
Expand All @@ -576,6 +580,10 @@ public Entry getSinceTx(String key, long tx) throws KeyNotFoundException {
}

/**
* This method can be used to avoid additional latency while the server
* waits for the indexer to finish indexing but still guarantees that
* specific portion of the database history has already been indexed.
*
* @param key the key to look for
* @param tx the lowest transaction from which the associated entry should be
* retrieved
Expand All @@ -601,19 +609,20 @@ public synchronized Entry getSinceTx(byte[] key, long tx) throws KeyNotFoundExce

/**
* @param key the key to look for
* @param tx the lowest transaction from which the associated entry should be
* retrieved
* @param rev the specific revision
* @return the specific revision for given key.
*
* Key revision is an integer value that starts at 1 when
* the key is created and then increased by 1 on every update made to
* that key.
*
* The way rev is interpreted depends on the value:
* - if rev = 0, returns current value
* - if rev > 0, returns nth revision value, e.g. 1 is the first value,
* - if rev == 0, returns current value
* - if rev &gt; 0, returns nth revision value, e.g. 1 is the first
* value,
* 2 is the second and so on
* - if rev < 0, returns nth revision value from the end, e.g. -1 is the
* - if rev &lt; 0, returns nth revision value from the end, e.g. -1 is
* the
* previous value, -2 is the one before and so on
*/
public Entry getAtRevision(String key, long rev) throws KeyNotFoundException {
Expand All @@ -622,19 +631,20 @@ public Entry getAtRevision(String key, long rev) throws KeyNotFoundException {

/**
* @param key the key to look for
* @param tx the lowest transaction from which the associated entry should be
* retrieved
* @param rev the specific revision
* @return the specific revision for given key.
*
* Key revision is an integer value that starts at 1 when
* the key is created and then increased by 1 on every update made to
* that key.
*
* The way rev is interpreted depends on the value:
* - if rev = 0, returns current value
* - if rev > 0, returns nth revision value, e.g. 1 is the first value,
* - if rev == 0, returns current value
* - if rev &gt; 0, returns nth revision value, e.g. 1 is the first
* value,
* 2 is the second and so on
* - if rev < 0, returns nth revision value from the end, e.g. -1 is the
* - if rev &lt; 0, returns nth revision value from the end, e.g. -1 is
* the
* previous value, -2 is the one before and so on
*/
public synchronized Entry getAtRevision(byte[] key, long rev) throws KeyNotFoundException {
Expand All @@ -654,6 +664,10 @@ public synchronized Entry getAtRevision(byte[] key, long rev) throws KeyNotFound
}
}

/**
* @param keys the lists of keys to look for
* @return retrieves multiple entries in a single call
*/
public synchronized List<Entry> getAll(List<String> keys) {
final List<ByteString> keysBS = new ArrayList<>(keys.size());

Expand All @@ -673,18 +687,46 @@ public synchronized List<Entry> getAll(List<String> keys) {
return result;
}

/**
* @param key the keys to look for
* @return the latest entry associated to the provided key. Equivalent to
* {@link #get(String) get} but with additional
* server-provided proof validation.
*/
public Entry verifiedGet(String key) throws KeyNotFoundException, VerificationException {
return verifiedGetAtTx(key, 0);
}

/**
* @param key the keys to look for
* @return the latest entry associated to the provided key. Equivalent to
* {@link #get(byte[])) get} but with additional
* server-provided proof validation.
*/
public Entry verifiedGet(byte[] key) throws KeyNotFoundException, VerificationException {
return verifiedGetAtTx(key, 0);
}

/**
* @param key the key to look for
* @param tx the transaction at which the associated entry is expected to be
* @return the entry associated to the provided key and transaction. Equivalent
* to
* {@link #getAtTx(String, long)) getAtTx} but with additional
* server-provided proof validation.
*/
public Entry verifiedGetAtTx(String key, long tx) throws KeyNotFoundException, VerificationException {
return verifiedGetAtTx(Utils.toByteArray(key), tx);
}

/**
* @param key the key to look for
* @param tx the transaction at which the associated entry is expected to be
* @return the entry associated to the provided key and transaction. Equivalent
* to
* {@link #getAtTx(byte[], long)) getAtTx} but with additional
* server-provided proof validation.
*/
public synchronized Entry verifiedGetAtTx(byte[] key, long tx) throws KeyNotFoundException, VerificationException {
final ImmuState state = state();

Expand All @@ -696,10 +738,38 @@ public synchronized Entry verifiedGetAtTx(byte[] key, long tx) throws KeyNotFoun
return verifiedGet(keyReq, state);
}

/**
* This method can be used to avoid additional latency while the server
* waits for the indexer to finish indexing but still guarantees that
* specific portion of the database history has already been indexed.
*
* @param key the key to look for
* @param tx the lowest transaction from which the associated entry should be
* retrieved
* @return the latest indexed entry associated the to provided key. Ensuring the
* indexing has already be completed up to the specified transaction.
* Equivalent to
* {@link #getSinceTx(String, long)) getSinceTx} but with additional
* server-provided proof validation.
*/
public Entry verifiedGetSinceTx(String key, long tx) throws KeyNotFoundException, VerificationException {
return verifiedGetSinceTx(Utils.toByteArray(key), tx);
}

/**
* This method can be used to avoid additional latency while the server
* waits for the indexer to finish indexing but still guarantees that
* specific portion of the database history has already been indexed.
*
* @param key the key to look for
* @param tx the lowest transaction from which the associated entry should be
* retrieved
* @return the latest indexed entry associated the to provided key. Ensuring the
* indexing has already be completed up to the specified transaction.
* Equivalent to
* {@link #getSinceTx(byte[], long)) getSinceTx} but with additional
* server-provided proof validation.
*/
public synchronized Entry verifiedGetSinceTx(byte[] key, long tx)
throws KeyNotFoundException, VerificationException {

Expand All @@ -713,10 +783,24 @@ public synchronized Entry verifiedGetSinceTx(byte[] key, long tx)
return verifiedGet(keyReq, state);
}

/**
* @param key the key to look for
* @param rev the specific revision
* @return the specific revision for given key. Equivalent to
* {@link #getAtRevision(String, long)) getAtRevision} but with additional
* server-provided proof validation.
*/
public Entry verifiedGetAtRevision(String key, long rev) throws KeyNotFoundException, VerificationException {
return verifiedGetAtRevision(Utils.toByteArray(key), rev);
}

/**
* @param key the key to look for
* @param rev the specific revision
* @return the specific revision for given key. Equivalent to
* {@link #getAtRevision(byte[], long)) getAtRevision} but with additional
* server-provided proof validation.
*/
public synchronized Entry verifiedGetAtRevision(byte[] key, long rev)
throws KeyNotFoundException, VerificationException {

Expand Down Expand Up @@ -830,10 +914,20 @@ private Entry verifiedGet(ImmudbProto.KeyRequest keyReq, ImmuState state)
// ========== DELETE ==========
//

/**
* Performs a logical deletion for key
*
* @param key the key to delete
*/
public TxHeader delete(String key) throws KeyNotFoundException {
return delete(Utils.toByteArray(key));
}

/**
* Performs a logical deletion for key
*
* @param key the key to delete
*/
public synchronized TxHeader delete(byte[] key) throws KeyNotFoundException {
try {
final ImmudbProto.DeleteKeysRequest req = ImmudbProto.DeleteKeysRequest.newBuilder()
Expand Down

0 comments on commit 22c139f

Please sign in to comment.