Example: + *
Abort a transaction and check the returned status.
+ *{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * try {
+ * Txn txn = new Txn();
+ * try {
+ * client.commit(txn);
+ * } catch (AerospikeException.Commit e) {
+ * AbortStatus status = client.abort(txn);
+ * if (status != AbortStatus.OK && status != AbortStatus.ALREADY_ABORTED) {
+ * System.err.println(status.str);
+ * }
+ * }
+ * } finally {
+ * client.close();
+ * }
+ * }
+ *
+ * @see CommitStatus
+ * @see CommitError
+ * @see com.aerospike.client.AerospikeClient#abort
*/
public enum AbortStatus {
OK("Abort succeeded"),
@@ -25,6 +48,7 @@ public enum AbortStatus {
ROLL_BACK_ABANDONED("Transaction client roll back abandoned. Server will eventually abort the transaction."),
CLOSE_ABANDONED("Transaction has been rolled back, but transaction client close was abandoned. Server will eventually close the transaction.");
+ /** Human-readable message for this status. */
public final String str;
AbortStatus(String str) {
diff --git a/client/src/com/aerospike/client/AerospikeClient.java b/client/src/com/aerospike/client/AerospikeClient.java
index 5b520c195..8675f8e01 100644
--- a/client/src/com/aerospike/client/AerospikeClient.java
+++ b/client/src/com/aerospike/client/AerospikeClient.java
@@ -139,16 +139,28 @@
import com.aerospike.client.util.Version;
/**
- * Instantiate an AerospikeClient object to access an Aerospike
- * database cluster and perform database operations.
+ * Main client to access an Aerospike cluster and perform database operations (get, put, query, batch, etc.).
* - * This client is thread-safe. One client instance should be used per cluster. - * Multiple threads should share this cluster instance. - *
- * Your application uses this class API to perform database operations such as - * writing and reading records, and selecting sets of records. Write operations - * include specialized functionality such as append/prepend and arithmetic - * addition. + * Thread-safe; use one instance per cluster and share it across threads. Implements {@link IAerospikeClient}. Use {@link ClientPolicy} and {@link Host} (or seed strings) to construct. + * + *
Example: + *
Create a client, put a record, and get it back.
+ *{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * try {
+ * Key key = new Key("test", "set1", "id1");
+ * client.put(null, key, new Bin("name", "Alice"));
+ * Record rec = client.get(null, key);
+ * } finally {
+ * client.close();
+ * }
+ * }
+ *
+ * @see IAerospikeClient
+ * @see ClientPolicy
+ * @see Host
+ * @see Key
+ * @see Record
*/
public class AerospikeClient implements IAerospikeClient, Closeable {
//-------------------------------------------------------
@@ -768,10 +780,25 @@ public String getVersion() {
* committed. Otherwise, the transaction is aborted.
* * Requires server version 8.0+ + *
+ *
Commit a transaction after put; check returned status.
+ *{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Key key = new Key("ns", "set", "txnkey");
+ * Txn txn = new Txn();
+ * WritePolicy wp = client.copyWritePolicyDefault();
+ * wp.txn = txn;
+ * client.put(wp, key, new Bin("bin1", "val1"));
+ * CommitStatus status = client.commit(txn);
+ * client.close();
+ * }
*
* @param txn transaction
* @return status of the commit on success
- * @throws AerospikeException.Commit if verify commit fails
+ * @throws AerospikeException.Commit when verify or commit fails
+ * @see #commit(EventLoop, CommitListener, Txn)
+ * @see #abort(Txn)
+ * @see Txn
*/
public final CommitStatus commit(Txn txn)
throws AerospikeException.Commit {
@@ -804,12 +831,28 @@ public final CommitStatus commit(Txn txn)
* The event loop thread will process the command and send the results to the listener.
* * Requires server version 8.0+ + *
+ *
Async commit: put with txn policy then commit via event loop and listener.
+ *{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * Txn txn = new Txn();
+ * WritePolicy wp = client.copyWritePolicyDefault();
+ * wp.txn = txn;
+ * client.put(loop, null, wp, key, new Bin("bin1", "val1"));
+ * client.commit(loop, new CommitListener() { ... }, txn);
+ * }
*
* @param eventLoop event loop that will process the command. If NULL, the event
* loop will be chosen by round-robin.
* @param listener where to send results
* @param txn transaction
- * @throws AerospikeException if event loop registration fails
+ * @throws AerospikeException when event loop registration fails
+ * @see #commit(Txn)
+ * @see CommitListener
*/
public final void commit(EventLoop eventLoop, CommitListener listener, Txn txn)
throws AerospikeException {
@@ -844,9 +887,24 @@ public final void commit(EventLoop eventLoop, CommitListener listener, Txn txn)
* Abort and rollback the given transaction.
* * Requires server version 8.0+ + *
+ *
Abort a transaction and check returned status.
+ *{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Txn txn = new Txn();
+ * WritePolicy wp = client.copyWritePolicyDefault();
+ * wp.txn = txn;
+ * client.put(wp, key, new Bin("bin1", "val1"));
+ * AbortStatus status = client.abort(txn);
+ * client.close();
+ * }
*
- * @param txn transaction
+ * @param txn transaction to abort
* @return status of the abort
+ * @throws AerospikeException when transaction was already committed
+ * @see #commit(Txn)
+ * @see #abort(EventLoop, AbortListener, Txn)
+ * @see Txn
*/
public final AbortStatus abort(Txn txn) {
TxnRoll tr = new TxnRoll(cluster, txn);
@@ -872,12 +930,28 @@ public final AbortStatus abort(Txn txn) {
* The event loop thread will process the command and send the results to the listener.
* * Requires server version 8.0+ + *
+ *
Async abort: put with txn then abort via event loop and AbortListener.
+ *{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * Txn txn = new Txn();
+ * WritePolicy wp = client.copyWritePolicyDefault();
+ * wp.txn = txn;
+ * client.put(loop, null, wp, key, new Bin("bin1", "val1"));
+ * client.abort(loop, new AbortListener() { ... }, txn);
+ * }
*
* @param eventLoop event loop that will process the command. If NULL, the event
* loop will be chosen by round-robin.
* @param listener where to send results
- * @param txn transaction
- * @throws AerospikeException if event loop registration fails
+ * @param txn transaction to abort
+ * @throws AerospikeException when event loop registration fails
+ * @see #abort(Txn)
+ * @see AbortListener
*/
public final void abort(EventLoop eventLoop, AbortListener listener, Txn txn)
throws AerospikeException {
@@ -908,14 +982,23 @@ public final void abort(EventLoop eventLoop, AbortListener listener, Txn txn)
//-------------------------------------------------------
/**
- * Write record bin(s).
- * The policy specifies the command timeouts, record expiration and how the command is
- * handled when the record already exists.
+ * Write record bins; policy controls timeout, expiration, and create/replace behavior.
+ * + *
Put bins for a key then get the record.
+ *{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Key key = new Key("ns", "set", "mykey");
+ * client.put(null, key, new Bin("bin1", "value1"), new Bin("bin2", 42));
+ * Record rec = client.get(null, key);
+ * client.close();
+ * }
*
- * @param policy write configuration parameters, pass in null for defaults
- * @param key unique record identifier
- * @param bins array of bin name/value pairs
- * @throws AerospikeException if write fails
+ * @param policy write configuration, or null for defaults
+ * @param key record key
+ * @param bins bin name/value pairs
+ * @throws AerospikeException when write fails
+ * @see #get(Policy, Key)
+ * @see #put(EventLoop, WriteListener, WritePolicy, Key, Bin...)
*/
public final void put(WritePolicy policy, Key key, Bin... bins)
throws AerospikeException {
@@ -934,20 +1017,26 @@ public final void put(WritePolicy policy, Key key, Bin... bins)
}
/**
- * Asynchronously write record bin(s).
- * This method registers the command with an event loop and returns.
- * The event loop thread will process the command and send the results to the listener.
+ * Asynchronously write record bins.
* - * The policy specifies the command timeout, record expiration and how the command is - * handled when the record already exists. + *
Async put via event loop and WriteListener.
+ *{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * client.put(loop, writeListener, null, key, new Bin("bin1", "v"));
+ * }
*
- * @param eventLoop event loop that will process the command. If NULL, the event
- * loop will be chosen by round-robin.
- * @param listener where to send results, pass in null for fire and forget
- * @param policy write configuration parameters, pass in null for defaults
- * @param key unique record identifier
- * @param bins array of bin name/value pairs
- * @throws AerospikeException if event loop registration fails
+ * @param eventLoop event loop; null to use round-robin
+ * @param listener callback, or null for fire-and-forget
+ * @param policy write configuration, or null for defaults
+ * @param key record key
+ * @param bins bin name/value pairs
+ * @throws AerospikeException when event loop registration fails
+ * @see #put(WritePolicy, Key, Bin...)
+ * @see WriteListener
*/
public final void put(EventLoop eventLoop, WriteListener listener, WritePolicy policy, Key key, Bin... bins)
throws AerospikeException {
@@ -970,15 +1059,21 @@ public final void put(EventLoop eventLoop, WriteListener listener, WritePolicy p
//-------------------------------------------------------
/**
- * Append bin string values to existing record bin values.
- * The policy specifies the command timeout, record expiration and how the command is
- * handled when the record already exists.
- * This call only works for string values.
+ * Append string values to existing bin values (strings only).
+ * + *
Append a string to an existing bin.
+ *{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * client.append(null, key, new Bin("name", "suffix"));
+ * client.close();
+ * }
*
- * @param policy write configuration parameters, pass in null for defaults
- * @param key unique record identifier
- * @param bins array of bin name/value pairs
- * @throws AerospikeException if append fails
+ * @param policy write configuration, or null for defaults
+ * @param key record key
+ * @param bins bin name/value pairs
+ * @throws AerospikeException when append fails
+ * @see #put(WritePolicy, Key, Bin...)
+ * @see #append(EventLoop, WriteListener, WritePolicy, Key, Bin...)
*/
public final void append(WritePolicy policy, Key key, Bin... bins)
throws AerospikeException {
@@ -997,21 +1092,25 @@ public final void append(WritePolicy policy, Key key, Bin... bins)
}
/**
- * Asynchronously append bin string values to existing record bin values.
- * This method registers the command with an event loop and returns.
- * The event loop thread will process the command and send the results to the listener.
+ * Asynchronously append string values to existing bin values.
* - * The policy specifies the command timeout, record expiration and how the command is - * handled when the record already exists. - * This call only works for string values. + *
Async append via event loop and WriteListener.
+ *{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * client.append(loop, listener, null, key, new Bin("name", "suffix"));
+ * }
*
- * @param eventLoop event loop that will process the command. If NULL, the event
- * loop will be chosen by round-robin.
- * @param listener where to send results, pass in null for fire and forget
- * @param policy write configuration parameters, pass in null for defaults
- * @param key unique record identifier
- * @param bins array of bin name/value pairs
- * @throws AerospikeException if event loop registration fails
+ * @param eventLoop event loop; null to use round-robin
+ * @param listener callback, or null for fire-and-forget
+ * @param policy write configuration, or null for defaults
+ * @param key record key
+ * @param bins bin name/value pairs
+ * @throws AerospikeException when event loop registration fails
+ * @see #append(WritePolicy, Key, Bin...)
*/
public final void append(EventLoop eventLoop, WriteListener listener, WritePolicy policy, Key key, Bin... bins)
throws AerospikeException {
@@ -1030,15 +1129,21 @@ public final void append(EventLoop eventLoop, WriteListener listener, WritePolic
}
/**
- * Prepend bin string values to existing record bin values.
- * The policy specifies the command timeout, record expiration and how the command is
- * handled when the record already exists.
- * This call works only for string values.
+ * Prepend string values to existing bin values (strings only).
+ * + *
Prepend a string to an existing bin.
+ *{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * client.prepend(null, key, new Bin("name", "prefix"));
+ * client.close();
+ * }
*
- * @param policy write configuration parameters, pass in null for defaults
- * @param key unique record identifier
- * @param bins array of bin name/value pairs
- * @throws AerospikeException if prepend fails
+ * @param policy write configuration, or null for defaults
+ * @param key record key
+ * @param bins bin name/value pairs
+ * @throws AerospikeException when prepend fails
+ * @see #append(WritePolicy, Key, Bin...)
+ * @see #prepend(EventLoop, WriteListener, WritePolicy, Key, Bin...)
*/
public final void prepend(WritePolicy policy, Key key, Bin... bins)
throws AerospikeException {
@@ -1057,21 +1162,26 @@ public final void prepend(WritePolicy policy, Key key, Bin... bins)
}
/**
- * Asynchronously prepend bin string values to existing record bin values.
- * This method registers the command with an event loop and returns.
- * The event loop thread will process the command and send the results to the listener.
+ * Asynchronously prepend string values to existing bin values.
* - * The policy specifies the command timeout, record expiration and how the command is - * handled when the record already exists. - * This call only works for string values. + *
Async prepend via event loop and WriteListener.
+ *{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * Key key = new Key("ns", "set", "prependkey");
+ * client.prepend(loop, listener, null, key, new Bin("prependbin", "Hello "));
+ * }
*
- * @param eventLoop event loop that will process the command. If NULL, the event
- * loop will be chosen by round-robin.
- * @param listener where to send results, pass in null for fire and forget
- * @param policy write configuration parameters, pass in null for defaults
- * @param key unique record identifier
- * @param bins array of bin name/value pairs
- * @throws AerospikeException if event loop registration fails
+ * @param eventLoop event loop; null to use round-robin
+ * @param listener callback, or null for fire-and-forget
+ * @param policy write configuration, or null for defaults
+ * @param key record key
+ * @param bins bin name/value pairs
+ * @throws AerospikeException when event loop registration fails
+ * @see #prepend(WritePolicy, Key, Bin...)
*/
public final void prepend(EventLoop eventLoop, WriteListener listener, WritePolicy policy, Key key, Bin... bins)
throws AerospikeException {
@@ -1094,15 +1204,21 @@ public final void prepend(EventLoop eventLoop, WriteListener listener, WritePoli
//-------------------------------------------------------
/**
- * Add integer/double bin values to record bin values. If the record or bin does not exist, the
- * record/bin will be created by default with the value to be added. The policy specifies the
- * command timeout, record expiration and how the command is handled when the record
- * already exists.
+ * Add integer/double bin values to existing bins; creates record/bin if absent.
+ * + *
Add an integer to a bin (creates bin if absent).
+ *{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * client.add(null, key, new Bin("counter", 1));
+ * client.close();
+ * }
*
- * @param policy write configuration parameters, pass in null for defaults
- * @param key unique record identifier
- * @param bins array of bin name/value pairs
- * @throws AerospikeException if add fails
+ * @param policy write configuration, or null for defaults
+ * @param key record key
+ * @param bins bin name/value pairs (integer or double)
+ * @throws AerospikeException when add fails
+ * @see #operate(WritePolicy, Key, Operation...)
+ * @see #add(EventLoop, WriteListener, WritePolicy, Key, Bin...)
*/
public final void add(WritePolicy policy, Key key, Bin... bins)
throws AerospikeException {
@@ -1121,21 +1237,26 @@ public final void add(WritePolicy policy, Key key, Bin... bins)
}
/**
- * Asynchronously add integer/double bin values to record bin values. If the record or bin does
- * not exist, the record/bin will be created by default with the value to be added. The policy
- * specifies the command timeout, record expiration and how the command is handled when
- * the record already exists.
+ * Asynchronously add integer/double bin values to existing values.
* - * This method registers the command with an event loop and returns. - * The event loop thread will process the command and send the results to the listener. + *
Async add via event loop and WriteListener.
+ *{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * Key key = new Key("ns", "set", "addkey");
+ * client.add(loop, listener, null, key, new Bin("addbin", 10));
+ * }
*
- * @param eventLoop event loop that will process the command. If NULL, the event
- * loop will be chosen by round-robin.
- * @param listener where to send results, pass in null for fire and forget
- * @param policy write configuration parameters, pass in null for defaults
- * @param key unique record identifier
- * @param bins array of bin name/value pairs
- * @throws AerospikeException if event loop registration fails
+ * @param eventLoop event loop; null to use round-robin
+ * @param listener callback, or null for fire-and-forget
+ * @param policy write configuration, or null for defaults
+ * @param key record key
+ * @param bins bin name/value pairs (integer or double)
+ * @throws AerospikeException when event loop registration fails
+ * @see #add(WritePolicy, Key, Bin...)
*/
public final void add(EventLoop eventLoop, WriteListener listener, WritePolicy policy, Key key, Bin... bins)
throws AerospikeException {
@@ -1158,13 +1279,21 @@ public final void add(EventLoop eventLoop, WriteListener listener, WritePolicy p
//-------------------------------------------------------
/**
- * Delete record for specified key.
- * The policy specifies the command timeout.
+ * Delete the record for the given key.
+ * + *
Delete a record and check if it existed.
+ *{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * boolean existed = client.delete(null, key);
+ * client.close();
+ * }
*
- * @param policy delete configuration parameters, pass in null for defaults
- * @param key unique record identifier
- * @return whether record existed on server before deletion
- * @throws AerospikeException if delete fails
+ * @param policy write configuration, or null for defaults
+ * @param key record key
+ * @return true if record existed before deletion
+ * @throws AerospikeException when delete fails
+ * @see #delete(BatchPolicy, BatchDeletePolicy, Key[])
+ * @see #delete(EventLoop, DeleteListener, WritePolicy, Key)
*/
public final boolean delete(WritePolicy policy, Key key)
throws AerospikeException {
@@ -1184,18 +1313,26 @@ public final boolean delete(WritePolicy policy, Key key)
}
/**
- * Asynchronously delete record for specified key.
- * This method registers the command with an event loop and returns.
- * The event loop thread will process the command and send the results to the listener.
+ * Asynchronously delete the record for the given key.
* - * The policy specifies the command timeout. + *
Async delete via event loop and DeleteListener.
+ *{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * Key key = new Key("ns", "set", "delkey");
+ * client.delete(loop, new DeleteListener() { ... }, null, key);
+ * }
*
- * @param eventLoop event loop that will process the command. If NULL, the event
- * loop will be chosen by round-robin.
- * @param listener where to send results, pass in null for fire and forget
- * @param policy write configuration parameters, pass in null for defaults
- * @param key unique record identifier
- * @throws AerospikeException if event loop registration fails
+ * @param eventLoop event loop; null to use round-robin
+ * @param listener callback, or null for fire-and-forget
+ * @param policy write configuration, or null for defaults
+ * @param key record key
+ * @throws AerospikeException when event loop registration fails
+ * @see #delete(WritePolicy, Key)
+ * @see DeleteListener
*/
public final void delete(EventLoop eventLoop, DeleteListener listener, WritePolicy policy, Key key)
throws AerospikeException {
@@ -1214,15 +1351,25 @@ public final void delete(EventLoop eventLoop, DeleteListener listener, WritePoli
}
/**
- * Delete records for specified keys. If a key is not found, the corresponding result
- * {@link BatchRecord#resultCode} will be {@link ResultCode#KEY_NOT_FOUND_ERROR}.
+ * Delete records for the given keys in a single batch; missing keys get {@link ResultCode#KEY_NOT_FOUND_ERROR}.
+ * + * Requires server 6.0+. *
- * Requires server version 6.0+ + *
Batch delete keys and get results per key.
+ *{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Key[] keys = new Key[] { new Key("ns", "set", "k1"), new Key("ns", "set", "k2") };
+ * BatchResults results = client.delete(null, null, keys);
+ * client.close();
+ * }
*
- * @param batchPolicy batch configuration parameters, pass in null for defaults
- * @param deletePolicy delete configuration parameters, pass in null for defaults
- * @param keys array of unique record identifiers
- * @throws AerospikeException.BatchRecordArray which contains results for keys that did complete
+ * @param batchPolicy batch configuration, or null for defaults
+ * @param deletePolicy delete configuration, or null for defaults
+ * @param keys keys to delete
+ * @return results per key
+ * @throws AerospikeException.BatchRecordArray when some keys fail (contains partial results)
+ * @see #delete(WritePolicy, Key)
+ * @see #operate(BatchPolicy, List)
*/
public final BatchResults delete(BatchPolicy batchPolicy, BatchDeletePolicy deletePolicy, Key[] keys)
throws AerospikeException {
@@ -1282,22 +1429,29 @@ public final BatchResults delete(BatchPolicy batchPolicy, BatchDeletePolicy dele
}
/**
- * Asynchronously delete records for specified keys.
- * This method registers the command with an event loop and returns.
- * The event loop thread will process the command and send the results to the listener.
+ * Asynchronously delete records for the given keys; results delivered to listener as a single array.
* - * If a key is not found, the corresponding result {@link BatchRecord#resultCode} will be - * {@link ResultCode#KEY_NOT_FOUND_ERROR}. - *
- * Requires server version 6.0+ + * Missing keys set {@link BatchRecord#resultCode} to {@link ResultCode#KEY_NOT_FOUND_ERROR}. Requires server 6.0+. + *
Example usage for this method.
+ *{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * Key[] keys = new Key[] { new Key("ns", "set", "k1"), new Key("ns", "set", "k2") };
+ * client.delete(loop, new BatchRecordArrayListener() { ... }, null, null, keys);
+ * }
*
- * @param eventLoop event loop that will process the command. If NULL, the event
- * loop will be chosen by round-robin.
- * @param listener where to send results
- * @param batchPolicy batch configuration parameters, pass in null for defaults
- * @param deletePolicy delete configuration parameters, pass in null for defaults
- * @param keys array of unique record identifiers
- * @throws AerospikeException if event loop registration fails
+ * @param eventLoop event loop; null to use round-robin
+ * @param listener callback for batch results
+ * @param batchPolicy batch configuration, or null for defaults
+ * @param deletePolicy delete configuration, or null for defaults
+ * @param keys keys to delete
+ * @throws AerospikeException when event loop registration fails
+ * @see #delete(BatchPolicy, BatchDeletePolicy, Key[])
+ * @see #delete(EventLoop, BatchRecordSequenceListener, BatchPolicy, BatchDeletePolicy, Key[])
+ * @see BatchRecordArrayListener
*/
public final void delete(
EventLoop eventLoop,
@@ -1357,23 +1511,29 @@ public final void delete(
}
/**
- * Asynchronously delete records for specified keys.
- * This method registers the command with an event loop and returns.
- * The event loop thread will process the command and send the results to the listener.
- * - * Each record result is returned in separate onRecord() calls. - * If a key is not found, the corresponding result {@link BatchRecord#resultCode} will be - * {@link ResultCode#KEY_NOT_FOUND_ERROR}. + * Asynchronously delete records for the given keys; each result delivered via onRecord. *
- * Requires server version 6.0+ + * Missing keys set {@link BatchRecord#resultCode} to {@link ResultCode#KEY_NOT_FOUND_ERROR}. Requires server 6.0+. + *
Example usage for this method.
+ *{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * Key[] keys = new Key[] { new Key("ns", "set", "k1"), new Key("ns", "set", "k2") };
+ * client.delete(loop, new BatchRecordSequenceListener() { ... }, null, null, keys);
+ * }
*
- * @param eventLoop event loop that will process the command. If NULL, the event
- * loop will be chosen by round-robin.
- * @param listener where to send results
- * @param batchPolicy batch configuration parameters, pass in null for defaults
- * @param deletePolicy delete configuration parameters, pass in null for defaults
- * @param keys array of unique record identifiers
- * @throws AerospikeException if event loop registration fails
+ * @param eventLoop event loop; null to use round-robin
+ * @param listener callback for per-record results
+ * @param batchPolicy batch configuration, or null for defaults
+ * @param deletePolicy delete configuration, or null for defaults
+ * @param keys keys to delete
+ * @throws AerospikeException when event loop registration fails
+ * @see #delete(BatchPolicy, BatchDeletePolicy, Key[])
+ * @see #delete(EventLoop, BatchRecordArrayListener, BatchPolicy, BatchDeletePolicy, Key[])
+ * @see BatchRecordSequenceListener
*/
public final void delete(
EventLoop eventLoop,
@@ -1428,22 +1588,23 @@ public final void delete(
}
/**
- * Remove records in specified namespace/set efficiently. This method is many orders of magnitude
- * faster than deleting records one at a time.
+ * Remove records in namespace/set efficiently; many orders of magnitude faster than deleting one at a time.
* - * See https://www.aerospike.com/docs/reference/info#truncate - *
- * This asynchronous server call may return before the truncation is complete. The user can still - * write new records after the server call returns because new records will have last update times - * greater than the truncate cutoff (set at the time of truncate call). + * Server call may return before truncation completes; new writes use last-update times after the cutoff. + *
Truncate a set in a namespace.
+ *{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * client.truncate(null, "ns", "set1", null);
+ * client.close();
+ * }
*
- * @param policy info command configuration parameters, pass in null for defaults
- * @param ns required namespace
- * @param set optional set name. Pass in null to delete all sets in namespace.
- * @param beforeLastUpdate optional delete records before record last update time.
- * If specified, value must be before the current time.
- * Pass in null to delete all records in namespace/set.
- * @throws AerospikeException if truncate fails
+ * @param policy info configuration, or null for defaults
+ * @param ns namespace
+ * @param set set name, or null for all sets in namespace
+ * @param beforeLastUpdate delete records before this time, or null for all
+ * @throws AerospikeException when truncate fails
+ * @see truncate
+ * @see #delete(WritePolicy, Key)
*/
public final void truncate(InfoPolicy policy, String ns, String set, Calendar beforeLastUpdate)
throws AerospikeException {
@@ -1485,13 +1646,19 @@ public final void truncate(InfoPolicy policy, String ns, String set, Calendar be
//-------------------------------------------------------
/**
- * Reset record's time to expiration using the policy's expiration.
- * If the record does not exist, it can't be created because the server deletes empty records.
- * Throw an exception if the record does not exist.
+ * Reset record time-to-expiration using the policy; fails when the record does not exist.
+ * Example usage for this method.
+ *{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * client.touch(null, key);
+ * client.close();
+ * }
*
- * @param policy write configuration parameters, pass in null for defaults
- * @param key unique record identifier
- * @throws AerospikeException if touch fails
+ * @param policy write configuration, or null for defaults
+ * @param key record key
+ * @throws AerospikeException when touch fails or record does not exist
+ * @see #touched(WritePolicy, Key)
+ * @see #touch(EventLoop, WriteListener, WritePolicy, Key)
*/
public final void touch(WritePolicy policy, Key key)
throws AerospikeException {
@@ -1510,20 +1677,15 @@ public final void touch(WritePolicy policy, Key key)
}
/**
- * Asynchronously reset record's time to expiration using the policy's expiration.
- * If the record does not exist, it can't be created because the server deletes empty records.
+ * Asynchronously reset record time-to-expiration using the policy.
* - * This method registers the command with an event loop and returns. - * The event loop thread will process the command and send the results to the listener. - *
- * Fail if the record does not exist. - * - * @param eventLoop event loop that will process the command. If NULL, the event - * loop will be chosen by round-robin. - * @param listener where to send results, pass in null for fire and forget - * @param policy write configuration parameters, pass in null for defaults - * @param key unique record identifier - * @throws AerospikeException if event loop registration fails + * @param eventLoop event loop; null to use round-robin + * @param listener callback, or null for fire-and-forget + * @param policy write configuration, or null for defaults + * @param key record key + * @throws AerospikeException when event loop registration fails + * @see #touch(WritePolicy, Key) + * @see WriteListener */ public final void touch(EventLoop eventLoop, WriteListener listener, WritePolicy policy, Key key) throws AerospikeException { @@ -1542,13 +1704,20 @@ public final void touch(EventLoop eventLoop, WriteListener listener, WritePolicy } /** - * Reset record's time to expiration using the policy's expiration. - * If the record does not exist, it can't be created because the server deletes empty records. - * Return true if the record exists and is touched. Return false if the record does not exist. + * Reset record time-to-expiration; returns true if record existed and was touched, false if not found. + *
Example usage for this method.
+ *{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * boolean ok = client.touched(null, key);
+ * client.close();
+ * }
*
- * @param policy write configuration parameters, pass in null for defaults
- * @param key unique record identifier
- * @throws AerospikeException if touch fails
+ * @param policy write configuration, or null for defaults
+ * @param key record key
+ * @return true if touched, false if record did not exist
+ * @throws AerospikeException when command fails
+ * @see #touch(WritePolicy, Key)
+ * @see #touched(EventLoop, ExistsListener, WritePolicy, Key)
*/
public final boolean touched(WritePolicy policy, Key key)
throws AerospikeException {
@@ -1568,21 +1737,25 @@ public final boolean touched(WritePolicy policy, Key key)
}
/**
- * Asynchronously reset record's time to expiration using the policy's expiration.
- * If the record does not exist, it can't be created because the server deletes empty records.
- * - * This method registers the command with an event loop and returns. - * The event loop thread will process the command and send the results to the listener. - *
- * If the record does not exist, send a value of false to - * {@link com.aerospike.client.listener.ExistsListener#onSuccess(Key, boolean)} + * Asynchronously reset record time-to-expiration; listener receives false when record does not exist. + *
Example usage for this method.
+ *{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * Key key = new Key("ns", "set", "touchkey");
+ * client.touched(loop, new ExistsListener() { ... }, null, key);
+ * }
*
- * @param eventLoop event loop that will process the command. If NULL, the event
- * loop will be chosen by round-robin.
- * @param listener where to send results, pass in null for fire and forget
- * @param policy write configuration parameters, pass in null for defaults
- * @param key unique record identifier
- * @throws AerospikeException if event loop registration fails
+ * @param eventLoop event loop; null to use round-robin
+ * @param listener callback
+ * @param policy write configuration, or null for defaults
+ * @param key record key
+ * @throws AerospikeException when event loop registration fails
+ * @see #touched(WritePolicy, Key)
+ * @see ExistsListener
*/
public final void touched(EventLoop eventLoop, ExistsListener listener, WritePolicy policy, Key key)
throws AerospikeException {
@@ -1605,13 +1778,21 @@ public final void touched(EventLoop eventLoop, ExistsListener listener, WritePol
//-------------------------------------------------------
/**
- * Determine if a record key exists.
- * The policy can be used to specify timeouts.
+ * Check whether a record key exists.
+ * Example usage for this method.
+ *{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * boolean found = client.exists(null, key);
+ * client.close();
+ * }
*
- * @param policy generic configuration parameters, pass in null for defaults
- * @param key unique record identifier
- * @return whether record exists or not
- * @throws AerospikeException if command fails
+ * @param policy read configuration, or null for defaults
+ * @param key record key
+ * @return true if record exists
+ * @throws AerospikeException when command fails
+ * @see #get(Policy, Key)
+ * @see #exists(BatchPolicy, Key[])
+ * @see #exists(EventLoop, ExistsListener, Policy, Key)
*/
public final boolean exists(Policy policy, Key key)
throws AerospikeException {
@@ -1631,18 +1812,25 @@ public final boolean exists(Policy policy, Key key)
}
/**
- * Asynchronously determine if a record key exists.
- * This method registers the command with an event loop and returns.
- * The event loop thread will process the command and send the results to the listener.
- * - * The policy can be used to specify timeouts. + * Asynchronously check whether a record key exists. + *
Example usage for this method.
+ *{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * Key key = new Key("ns", "set", "existskey");
+ * client.exists(loop, new ExistsListener() { ... }, null, key);
+ * }
*
- * @param eventLoop event loop that will process the command. If NULL, the event
- * loop will be chosen by round-robin.
- * @param listener where to send results
- * @param policy generic configuration parameters, pass in null for defaults
- * @param key unique record identifier
- * @throws AerospikeException if event loop registration fails
+ * @param eventLoop event loop; null to use round-robin
+ * @param listener callback
+ * @param policy read configuration, or null for defaults
+ * @param key record key
+ * @throws AerospikeException when event loop registration fails
+ * @see #exists(Policy, Key)
+ * @see ExistsListener
*/
public final void exists(EventLoop eventLoop, ExistsListener listener, Policy policy, Key key)
throws AerospikeException {
@@ -1665,13 +1853,21 @@ public final void exists(EventLoop eventLoop, ExistsListener listener, Policy po
}
/**
- * Check if multiple record keys exist in one batch call.
- * The returned boolean array is in positional order with the original key array order.
+ * Check if multiple record keys exist in one batch call; result array matches key order.
+ * Example usage for this method.
+ *{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Key[] keys = new Key[] { new Key("ns", "set", "k1"), new Key("ns", "set", "k2") };
+ * boolean[] found = client.exists(null, keys);
+ * client.close();
+ * }
*
- * @param policy batch configuration parameters, pass in null for defaults
- * @param keys array of unique record identifiers
- * @return array key/existence status pairs
- * @throws AerospikeException.BatchExists which contains results for keys that did complete
+ * @param policy batch configuration, or null for defaults
+ * @param keys keys to check
+ * @return existence per key, same order as keys
+ * @throws AerospikeException.BatchExists when some keys fail (contains partial results)
+ * @see #exists(Policy, Key)
+ * @see #exists(EventLoop, ExistsArrayListener, BatchPolicy, Key[])
*/
public final boolean[] exists(BatchPolicy policy, Key[] keys)
throws AerospikeException {
@@ -1717,18 +1913,29 @@ public final boolean[] exists(BatchPolicy policy, Key[] keys)
}
/**
- * Asynchronously check if multiple record keys exist in one batch call.
- * This method registers the command with an event loop and returns.
- * The event loop thread will process the command and send the results to the listener.
+ * Asynchronously check if multiple record keys exist in one batch call; results in one callback as array.
* - * The returned boolean array is in positional order with the original key array order. + * Result array order matches key order. + *
Example usage for this method.
+ *{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * Key[] keys = new Key[] { new Key("ns", "set", "k1"), new Key("ns", "set", "k2") };
+ * client.exists(loop, new ExistsArrayListener() { ... }, null, keys);
+ * }
*
* @param eventLoop event loop that will process the command. If NULL, the event
* loop will be chosen by round-robin.
* @param listener where to send results
* @param policy batch configuration parameters, pass in null for defaults
* @param keys unique record identifiers
- * @throws AerospikeException if event loop registration fails
+ * @throws AerospikeException when event loop registration fails
+ * @see #exists(BatchPolicy, Key[])
+ * @see #exists(EventLoop, ExistsSequenceListener, BatchPolicy, Key[])
+ * @see ExistsArrayListener
*/
public final void exists(EventLoop eventLoop, ExistsArrayListener listener, BatchPolicy policy, Key[] keys)
throws AerospikeException {
@@ -1773,18 +1980,28 @@ public final void exists(EventLoop eventLoop, ExistsArrayListener listener, Batc
}
/**
- * Asynchronously check if multiple record keys exist in one batch call.
- * This method registers the command with an event loop and returns.
- * The event loop thread will process the command and send the results to the listener.
+ * Asynchronously check if multiple record keys exist in one batch call; each result via onExists().
* - * Each key's result is returned in separate onExists() calls. + *
Example usage for this method.
+ *{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * Key[] keys = new Key[] { new Key("ns", "set", "k1"), new Key("ns", "set", "k2") };
+ * client.exists(loop, new ExistsSequenceListener() { ... }, null, keys);
+ * }
*
* @param eventLoop event loop that will process the command. If NULL, the event
* loop will be chosen by round-robin.
* @param listener where to send results
* @param policy batch configuration parameters, pass in null for defaults
* @param keys unique record identifiers
- * @throws AerospikeException if event loop registration fails
+ * @throws AerospikeException when event loop registration fails
+ * @see #exists(BatchPolicy, Key[])
+ * @see #exists(EventLoop, ExistsArrayListener, BatchPolicy, Key[])
+ * @see ExistsSequenceListener
*/
public final void exists(EventLoop eventLoop, ExistsSequenceListener listener, BatchPolicy policy, Key[] keys)
throws AerospikeException {
@@ -1833,12 +2050,21 @@ public final void exists(EventLoop eventLoop, ExistsSequenceListener listener, B
/**
* Read entire record for specified key.
- * The policy can be used to specify timeouts.
+ * Example usage for this method.
+ *{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Key key = new Key("ns", "set", "mykey");
+ * Record rec = client.get(null, key);
+ * if (rec != null) { String s = rec.getString("bin1"); }
+ * client.close();
+ * }
*
* @param policy generic configuration parameters, pass in null for defaults
* @param key unique record identifier
* @return if found, return record instance. If not found, return null.
- * @throws AerospikeException if read fails
+ * @throws AerospikeException when read fails
+ * @see #get(Policy, Key, String...)
+ * @see #get(EventLoop, RecordListener, Policy, Key)
*/
public final Record get(Policy policy, Key key)
throws AerospikeException {
@@ -1859,17 +2085,25 @@ public final Record get(Policy policy, Key key)
/**
* Asynchronously read entire record for specified key.
- * This method registers the command with an event loop and returns.
- * The event loop thread will process the command and send the results to the listener.
- * - * The policy can be used to specify timeouts. + *
Example usage for this method.
+ *{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * Key key = new Key("ns", "set", "mykey");
+ * client.get(loop, new RecordListener() { ... }, null, key);
+ * }
*
* @param eventLoop event loop that will process the command. If NULL, the event
* loop will be chosen by round-robin.
* @param listener where to send results
* @param policy generic configuration parameters, pass in null for defaults
* @param key unique record identifier
- * @throws AerospikeException if event loop registration fails
+ * @throws AerospikeException when event loop registration fails
+ * @see #get(Policy, Key)
+ * @see RecordListener
*/
public final void get(EventLoop eventLoop, RecordListener listener, Policy policy, Key key)
throws AerospikeException {
@@ -1892,14 +2126,22 @@ public final void get(EventLoop eventLoop, RecordListener listener, Policy polic
}
/**
- * Read record header and bins for specified key.
- * The policy can be used to specify timeouts.
+ * Read record header and bins for specified key and bin names.
+ * Example usage for this method.
+ *{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Key key = new Key("ns", "set", "mykey");
+ * Record rec = client.get(null, key, "bin1", "bin2");
+ * client.close();
+ * }
*
* @param policy generic configuration parameters, pass in null for defaults
* @param key unique record identifier
* @param binNames bins to retrieve
* @return if found, return record instance. If not found, return null.
- * @throws AerospikeException if read fails
+ * @throws AerospikeException when read fails
+ * @see #get(Policy, Key)
+ * @see #get(EventLoop, RecordListener, Policy, Key, String...)
*/
public final Record get(Policy policy, Key key, String... binNames)
throws AerospikeException {
@@ -1919,11 +2161,16 @@ public final Record get(Policy policy, Key key, String... binNames)
}
/**
- * Asynchronously read record header and bins for specified key.
- * This method registers the command with an event loop and returns.
- * The event loop thread will process the command and send the results to the listener.
- * - * The policy can be used to specify timeouts. + * Asynchronously read record header and bins for specified key and bin names. + *
Example usage for this method.
+ *{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * client.get(loop, new RecordListener() { ... }, null, key, "bin1", "bin2");
+ * }
*
* @param eventLoop event loop that will process the command. If NULL, the event
* loop will be chosen by round-robin.
@@ -1931,7 +2178,9 @@ public final Record get(Policy policy, Key key, String... binNames)
* @param policy generic configuration parameters, pass in null for defaults
* @param key unique record identifier
* @param binNames bins to retrieve
- * @throws AerospikeException if event loop registration fails
+ * @throws AerospikeException when event loop registration fails
+ * @see #get(Policy, Key, String...)
+ * @see RecordListener
*/
public final void get(EventLoop eventLoop, RecordListener listener, Policy policy, Key key, String... binNames)
throws AerospikeException {
@@ -1954,13 +2203,21 @@ public final void get(EventLoop eventLoop, RecordListener listener, Policy polic
}
/**
- * Read record generation and expiration only for specified key. Bins are not read.
- * The policy can be used to specify timeouts.
+ * Read record generation and expiration only; bins are not read.
+ * Example usage for this method.
+ *{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Key key = new Key("ns", "set", "mykey");
+ * Record rec = client.getHeader(null, key);
+ * client.close();
+ * }
*
* @param policy generic configuration parameters, pass in null for defaults
* @param key unique record identifier
* @return if found, return record instance. If not found, return null.
- * @throws AerospikeException if read fails
+ * @throws AerospikeException when read fails
+ * @see #get(Policy, Key)
+ * @see #getHeader(EventLoop, RecordListener, Policy, Key)
*/
public final Record getHeader(Policy policy, Key key)
throws AerospikeException {
@@ -1980,18 +2237,25 @@ public final Record getHeader(Policy policy, Key key)
}
/**
- * Asynchronously read record generation and expiration only for specified key. Bins are not read.
- * This method registers the command with an event loop and returns.
- * The event loop thread will process the command and send the results to the listener.
- * - * The policy can be used to specify timeouts. + * Asynchronously read record generation and expiration only; bins are not read. + *
Example usage for this method.
+ *{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * client.getHeader(loop, new RecordListener() { ... }, null, key);
+ * }
*
* @param eventLoop event loop that will process the command. If NULL, the event
* loop will be chosen by round-robin.
* @param listener where to send results
* @param policy generic configuration parameters, pass in null for defaults
* @param key unique record identifier
- * @throws AerospikeException if event loop registration fails
+ * @throws AerospikeException when event loop registration fails
+ * @see #getHeader(Policy, Key)
+ * @see RecordListener
*/
public final void getHeader(EventLoop eventLoop, RecordListener listener, Policy policy, Key key)
throws AerospikeException {
@@ -2018,16 +2282,26 @@ public final void getHeader(EventLoop eventLoop, RecordListener listener, Policy
//-------------------------------------------------------
/**
- * Read multiple records for specified batch keys in one batch call.
- * This method allows different namespaces/bins to be requested for each key in the batch.
- * The returned records are located in the same list.
- * If the BatchRead key field is not found, the corresponding record field will be null.
+ * Read multiple records for specified batch keys in one batch call; different bins per key allowed.
+ * Example usage for this method.
+ *{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * List batchReads = java.util.Arrays.asList(
+ * new BatchRead(new Key("ns", "set", "k1"), "bin1"),
+ * new BatchRead(new Key("ns", "set", "k2"))
+ * );
+ * client.get(null, batchReads);
+ * for (BatchRead br : batchReads) { Record r = br.record; }
+ * client.close();
+ * }
*
* @param policy batch configuration parameters, pass in null for defaults
* @param records list of unique record identifiers and the bins to retrieve.
* The returned records are located in the same list.
* @return true if all batch key requests succeeded
- * @throws AerospikeException if read fails
+ * @throws AerospikeException when read fails
+ * @see #get(BatchPolicy, Key[])
+ * @see #get(EventLoop, BatchListListener, BatchPolicy, List)
*/
public final boolean get(BatchPolicy policy, List- * This method allows different namespaces/bins to be requested for each key in the batch. - * The returned records are located in the same list. - * If the BatchRead key field is not found, the corresponding record field will be null. + * Asynchronously read multiple records for specified batch keys; results in the same list. + *
Example usage for this method.
+ *{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * List batchReads = java.util.Arrays.asList(new BatchRead(new Key("ns", "set", "k1")), new BatchRead(new Key("ns", "set", "k2")));
+ * client.get(loop, new BatchListListener() { ... }, null, batchReads);
+ * }
*
* @param eventLoop event loop that will process the command. If NULL, the event
* loop will be chosen by round-robin.
@@ -2078,7 +2356,9 @@ public final boolean get(BatchPolicy policy, List- * This method allows different namespaces/bins to be requested for each key in the batch. - * Each record result is returned in separate onRecord() calls. - * If the BatchRead key field is not found, the corresponding record field will be null. + * Asynchronously read multiple records for specified batch keys; each result via onRecord(). + *
Example usage for this method.
+ *{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * List batchReads = java.util.Arrays.asList(new BatchRead(new Key("ns", "set", "k1")), new BatchRead(new Key("ns", "set", "k2")));
+ * client.get(loop, new BatchSequenceListener() { ... }, null, batchReads);
+ * }
*
* @param eventLoop event loop that will process the command. If NULL, the event
* loop will be chosen by round-robin.
@@ -2133,7 +2417,9 @@ public final void get(EventLoop eventLoop, BatchListListener listener, BatchPoli
* @param policy batch configuration parameters, pass in null for defaults
* @param records list of unique record identifiers and the bins to retrieve.
* The returned records are located in the same list.
- * @throws AerospikeException if event loop registration fails
+ * @throws AerospikeException when event loop registration fails
+ * @see #get(BatchPolicy, List)
+ * @see BatchSequenceListener
*/
public final void get(EventLoop eventLoop, BatchSequenceListener listener, BatchPolicy policy, ListExample usage for this method.
+ *{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Key[] keys = new Key[] { new Key("ns", "set", "k1"), new Key("ns", "set", "k2") };
+ * Record[] records = client.get(null, keys);
+ * client.close();
+ * }
*
* @param policy batch configuration parameters, pass in null for defaults
* @param keys array of unique record identifiers
- * @return array of records
- * @throws AerospikeException.BatchRecords which contains results for keys that did complete
+ * @return array of records (null for missing keys)
+ * @throws AerospikeException.BatchRecords when some keys fail (contains partial results)
+ * @see #get(BatchPolicy, List)
+ * @see #get(EventLoop, RecordArrayListener, BatchPolicy, Key[])
*/
public final Record[] get(BatchPolicy policy, Key[] keys)
throws AerospikeException {
@@ -2230,19 +2523,26 @@ public final Record[] get(BatchPolicy policy, Key[] keys)
}
/**
- * Asynchronously read multiple records for specified keys in one batch call.
- * This method registers the command with an event loop and returns.
- * The event loop thread will process the command and send the results to the listener.
- * - * The returned records are in positional order with the original key array order. - * If a key is not found, the positional record will be null. + * Asynchronously read multiple records for specified keys; results in one callback as array. + *
Example usage for this method.
+ *{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * Key[] keys = new Key[] { new Key("ns", "set", "k1"), new Key("ns", "set", "k2") };
+ * client.get(loop, new RecordArrayListener() { ... }, null, keys);
+ * }
*
* @param eventLoop event loop that will process the command. If NULL, the event
* loop will be chosen by round-robin.
* @param listener where to send results
* @param policy batch configuration parameters, pass in null for defaults
* @param keys array of unique record identifiers
- * @throws AerospikeException if event loop registration fails
+ * @throws AerospikeException when event loop registration fails
+ * @see #get(BatchPolicy, Key[])
+ * @see RecordArrayListener
*/
public final void get(EventLoop eventLoop, RecordArrayListener listener, BatchPolicy policy, Key[] keys)
throws AerospikeException {
@@ -2287,19 +2587,26 @@ public final void get(EventLoop eventLoop, RecordArrayListener listener, BatchPo
}
/**
- * Asynchronously read multiple records for specified keys in one batch call.
- * This method registers the command with an event loop and returns.
- * The event loop thread will process the command and send the results to the listener.
- * - * Each record result is returned in separate onRecord() calls. - * If a key is not found, the record will be null. + * Asynchronously read multiple records for specified keys; each result via onRecord(). + *
Example usage for this method.
+ *{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * Key[] keys = new Key[] { new Key("ns", "set", "k1"), new Key("ns", "set", "k2") };
+ * client.get(loop, new RecordSequenceListener() { ... }, null, keys);
+ * }
*
* @param eventLoop event loop that will process the command. If NULL, the event
* loop will be chosen by round-robin.
* @param listener where to send results
* @param policy batch configuration parameters, pass in null for defaults
* @param keys array of unique record identifiers
- * @throws AerospikeException if event loop registration fails
+ * @throws AerospikeException when event loop registration fails
+ * @see #get(BatchPolicy, Key[])
+ * @see RecordSequenceListener
*/
public final void get(EventLoop eventLoop, RecordSequenceListener listener, BatchPolicy policy, Key[] keys)
throws AerospikeException {
@@ -2343,15 +2650,22 @@ public final void get(EventLoop eventLoop, RecordSequenceListener listener, Batc
}
/**
- * Read multiple record headers and bins for specified keys in one batch call.
- * The returned records are in positional order with the original key array order.
- * If a key is not found, the positional record will be null.
+ * Read multiple records for specified keys and bin names; result order matches key order.
+ * Example usage for this method.
+ *{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Key[] keys = new Key[] { new Key("ns", "set", "k1"), new Key("ns", "set", "k2") };
+ * Record[] records = client.get(null, keys, "bin1");
+ * client.close();
+ * }
*
* @param policy batch configuration parameters, pass in null for defaults
* @param keys array of unique record identifiers
* @param binNames array of bins to retrieve
- * @return array of records
- * @throws AerospikeException.BatchRecords which contains results for keys that did complete
+ * @return array of records (null for missing keys)
+ * @throws AerospikeException.BatchRecords when some keys fail (contains partial results)
+ * @see #get(BatchPolicy, Key[])
+ * @see #get(EventLoop, RecordArrayListener, BatchPolicy, Key[], String...)
*/
public final Record[] get(BatchPolicy policy, Key[] keys, String... binNames)
throws AerospikeException {
@@ -2400,12 +2714,17 @@ public final Record[] get(BatchPolicy policy, Key[] keys, String... binNames)
}
/**
- * Asynchronously read multiple record headers and bins for specified keys in one batch call.
- * This method registers the command with an event loop and returns.
- * The event loop thread will process the command and send the results to the listener.
- * - * The returned records are in positional order with the original key array order. - * If a key is not found, the positional record will be null. + * Asynchronously read multiple records for specified keys and bin names; results in one callback. + *
Example usage for this method.
+ *{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * Key[] keys = new Key[] { new Key("ns", "set", "k1"), new Key("ns", "set", "k2") };
+ * client.get(loop, new RecordArrayListener() { ... }, null, keys, "bin1");
+ * }
*
* @param eventLoop event loop that will process the command. If NULL, the event
* loop will be chosen by round-robin.
@@ -2413,7 +2732,9 @@ public final Record[] get(BatchPolicy policy, Key[] keys, String... binNames)
* @param policy batch configuration parameters, pass in null for defaults
* @param keys array of unique record identifiers
* @param binNames array of bins to retrieve
- * @throws AerospikeException if event loop registration fails
+ * @throws AerospikeException when event loop registration fails
+ * @see #get(BatchPolicy, Key[], String...)
+ * @see RecordArrayListener
*/
public final void get(EventLoop eventLoop, RecordArrayListener listener, BatchPolicy policy, Key[] keys, String... binNames)
throws AerospikeException {
@@ -2461,12 +2782,17 @@ public final void get(EventLoop eventLoop, RecordArrayListener listener, BatchPo
}
/**
- * Asynchronously read multiple record headers and bins for specified keys in one batch call.
- * This method registers the command with an event loop and returns.
- * The event loop thread will process the command and send the results to the listener.
- * - * Each record result is returned in separate onRecord() calls. - * If a key is not found, the record will be null. + * Asynchronously read multiple records for specified keys and bin names; each result via onRecord(). + *
Example usage for this method.
+ *{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * Key[] keys = new Key[] { new Key("ns", "set", "k1"), new Key("ns", "set", "k2") };
+ * client.get(loop, new RecordSequenceListener() { ... }, null, keys, "bin1");
+ * }
*
* @param eventLoop event loop that will process the command. If NULL, the event
* loop will be chosen by round-robin.
@@ -2474,7 +2800,9 @@ public final void get(EventLoop eventLoop, RecordArrayListener listener, BatchPo
* @param policy batch configuration parameters, pass in null for defaults
* @param keys array of unique record identifiers
* @param binNames array of bins to retrieve
- * @throws AerospikeException if event loop registration fails
+ * @throws AerospikeException when event loop registration fails
+ * @see #get(BatchPolicy, Key[], String...)
+ * @see RecordSequenceListener
*/
public final void get(EventLoop eventLoop, RecordSequenceListener listener, BatchPolicy policy, Key[] keys, String... binNames)
throws AerospikeException {
@@ -2520,15 +2848,22 @@ public final void get(EventLoop eventLoop, RecordSequenceListener listener, Batc
}
/**
- * Read multiple records for specified keys using read operations in one batch call.
- * The returned records are in positional order with the original key array order.
- * If a key is not found, the positional record will be null.
+ * Read multiple records for specified keys using read operations; result order matches key order.
+ * Example usage for this method.
+ *{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Key[] keys = new Key[] { new Key("ns", "set", "k1"), new Key("ns", "set", "k2") };
+ * Record[] records = client.get(null, keys, Operation.get("bin1"));
+ * client.close();
+ * }
*
* @param policy batch configuration parameters, pass in null for defaults
* @param keys array of unique record identifiers
* @param ops array of read operations on record
- * @return array of records
- * @throws AerospikeException.BatchRecords which contains results for keys that did complete
+ * @return array of records (null for missing keys)
+ * @throws AerospikeException.BatchRecords when some keys fail (contains partial results)
+ * @see #get(BatchPolicy, Key[])
+ * @see Operation
*/
public final Record[] get(BatchPolicy policy, Key[] keys, Operation... ops)
throws AerospikeException {
@@ -2574,12 +2909,17 @@ public final Record[] get(BatchPolicy policy, Key[] keys, Operation... ops)
}
/**
- * Asynchronously read multiple records for specified keys using read operations in one batch call.
- * This method registers the command with an event loop and returns.
- * The event loop thread will process the command and send the results to the listener.
- * - * The returned records are in positional order with the original key array order. - * If a key is not found, the positional record will be null. + * Asynchronously read multiple records for specified keys using read operations; results in one callback. + *
Example usage for this method.
+ *{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * Key[] keys = new Key[] { new Key("ns", "set", "k1"), new Key("ns", "set", "k2") };
+ * client.get(loop, new RecordArrayListener() { ... }, null, keys, Operation.get("bin1"));
+ * }
*
* @param eventLoop event loop that will process the command. If NULL, the event
* loop will be chosen by round-robin.
@@ -2587,7 +2927,9 @@ public final Record[] get(BatchPolicy policy, Key[] keys, Operation... ops)
* @param policy batch configuration parameters, pass in null for defaults
* @param keys array of unique record identifiers
* @param ops array of read operations on record
- * @throws AerospikeException if event loop registration fails
+ * @throws AerospikeException when event loop registration fails
+ * @see #get(BatchPolicy, Key[], Operation...)
+ * @see RecordArrayListener
*/
public final void get(EventLoop eventLoop, RecordArrayListener listener, BatchPolicy policy, Key[] keys, Operation... ops)
throws AerospikeException {
@@ -2632,12 +2974,17 @@ public final void get(EventLoop eventLoop, RecordArrayListener listener, BatchPo
}
/**
- * Asynchronously read multiple records for specified keys using read operations in one batch call.
- * This method registers the command with an event loop and returns.
- * The event loop thread will process the command and send the results to the listener.
- * - * Each record result is returned in separate onRecord() calls. - * If a key is not found, the record will be null. + * Asynchronously read multiple records for specified keys using read operations; each result via onRecord(). + *
Example usage for this method.
+ *{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * Key[] keys = new Key[] { new Key("ns", "set", "k1"), new Key("ns", "set", "k2") };
+ * client.get(loop, new RecordSequenceListener() { ... }, null, keys, Operation.get("bin1"));
+ * }
*
* @param eventLoop event loop that will process the command. If NULL, the event
* loop will be chosen by round-robin.
@@ -2645,7 +2992,9 @@ public final void get(EventLoop eventLoop, RecordArrayListener listener, BatchPo
* @param policy batch configuration parameters, pass in null for defaults
* @param keys array of unique record identifiers
* @param ops array of read operations on record
- * @throws AerospikeException if event loop registration fails
+ * @throws AerospikeException when event loop registration fails
+ * @see #get(BatchPolicy, Key[], Operation...)
+ * @see RecordSequenceListener
*/
public final void get(EventLoop eventLoop, RecordSequenceListener listener, BatchPolicy policy, Key[] keys, Operation... ops)
throws AerospikeException {
@@ -2688,14 +3037,21 @@ public final void get(EventLoop eventLoop, RecordSequenceListener listener, Batc
}
/**
- * Read multiple record header data for specified keys in one batch call.
- * The returned records are in positional order with the original key array order.
- * If a key is not found, the positional record will be null.
+ * Read multiple record headers (metadata only) for specified keys; result order matches key order.
+ * Example usage for this method.
+ *{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Key[] keys = new Key[] { new Key("ns", "set", "k1"), new Key("ns", "set", "k2") };
+ * Record[] headers = client.getHeader(null, keys);
+ * client.close();
+ * }
*
* @param policy batch configuration parameters, pass in null for defaults
* @param keys array of unique record identifiers
- * @return array of records
- * @throws AerospikeException.BatchRecords which contains results for keys that did complete
+ * @return array of records (metadata only; null for missing keys)
+ * @throws AerospikeException.BatchRecords when some keys fail (contains partial results)
+ * @see #getHeader(Policy, Key)
+ * @see #get(BatchPolicy, Key[])
*/
public final Record[] getHeader(BatchPolicy policy, Key[] keys)
throws AerospikeException {
@@ -2742,19 +3098,26 @@ public final Record[] getHeader(BatchPolicy policy, Key[] keys)
}
/**
- * Asynchronously read multiple record header data for specified keys in one batch call.
- * This method registers the command with an event loop and returns.
- * The event loop thread will process the command and send the results to the listener.
- * - * The returned records are in positional order with the original key array order. - * If a key is not found, the positional record will be null. + * Asynchronously read multiple record headers (metadata only); results in one callback. + *
Example usage for this method.
+ *{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * Key[] keys = new Key[] { new Key("ns", "set", "k1"), new Key("ns", "set", "k2") };
+ * client.getHeader(loop, new RecordArrayListener() { ... }, null, keys);
+ * }
*
* @param eventLoop event loop that will process the command. If NULL, the event
* loop will be chosen by round-robin.
* @param listener where to send results
* @param policy batch configuration parameters, pass in null for defaults
* @param keys array of unique record identifiers
- * @throws AerospikeException if event loop registration fails
+ * @throws AerospikeException when event loop registration fails
+ * @see #getHeader(BatchPolicy, Key[])
+ * @see RecordArrayListener
*/
public final void getHeader(EventLoop eventLoop, RecordArrayListener listener, BatchPolicy policy, Key[] keys)
throws AerospikeException {
@@ -2800,19 +3163,26 @@ public final void getHeader(EventLoop eventLoop, RecordArrayListener listener, B
}
/**
- * Asynchronously read multiple record header data for specified keys in one batch call.
- * This method registers the command with an event loop and returns.
- * The event loop thread will process the command and send the results to the listener.
- * - * Each record result is returned in separate onRecord() calls. - * If a key is not found, the record will be null. + * Asynchronously read multiple record headers (metadata only); each result via onRecord(). + *
Example usage for this method.
+ *{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * Key[] keys = new Key[] { new Key("ns", "set", "k1"), new Key("ns", "set", "k2") };
+ * client.getHeader(loop, new RecordSequenceListener() { ... }, null, keys);
+ * }
*
* @param eventLoop event loop that will process the command. If NULL, the event
* loop will be chosen by round-robin.
* @param listener where to send results
* @param policy batch configuration parameters, pass in null for defaults
* @param keys array of unique record identifiers
- * @throws AerospikeException if event loop registration fails
+ * @throws AerospikeException when event loop registration fails
+ * @see #getHeader(BatchPolicy, Key[])
+ * @see RecordSequenceListener
*/
public final void getHeader(EventLoop eventLoop, RecordSequenceListener listener, BatchPolicy policy, Key[] keys)
throws AerospikeException {
@@ -2860,22 +3230,27 @@ public final void getHeader(EventLoop eventLoop, RecordSequenceListener listener
//-------------------------------------------------------
/**
- * Perform multiple read/write operations on a single key in one batch call.
- * An example would be to add an integer value to an existing record and then
- * read the result, all in one database call.
+ * Perform multiple read/write operations on a single key in one call.
+ * Example usage for this method.
+ *{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Key key = new Key("ns", "set", "mykey");
+ * Record rec = client.operate(null, key, Operation.add(new Bin("ctr", 1)), Operation.get("ctr"));
+ * client.close();
+ * }
* * The server executes operations in the same order as the operations array. * Both scalar bin operations (Operation) and CDT bin operations (ListOperation, * MapOperation) can be performed in same call. - *
* Operation results are stored with their associated bin name in the returned record. - * The bin's result type will be a list when multiple operations occur on the same bin. * * @param policy write configuration parameters, pass in null for defaults * @param key unique record identifier * @param operations database operations to perform - * @return record results - * @throws AerospikeException if command fails + * @return record with operation results + * @throws AerospikeException when command fails + * @see #operate(EventLoop, RecordListener, WritePolicy, Key, Operation...) + * @see Operation */ public final Record operate(WritePolicy policy, Key key, Operation... operations) throws AerospikeException { @@ -2907,19 +3282,16 @@ public final Record operate(WritePolicy policy, Key key, Operation... operations } /** - * Asynchronously perform multiple read/write operations on a single key in one batch call. - * This method registers the command with an event loop and returns. - * The event loop thread will process the command and send the results to the listener. - *
- * An example would be to add an integer value to an existing record and then - * read the result, all in one database call. - *
- * The server executes operations in the same order as the operations array. - * Both scalar bin operations (Operation) and CDT bin operations (ListOperation, - * MapOperation) can be performed in same call. - *
- * Operation results are stored with their associated bin name in the returned record. - * The bin's result type will be a list when multiple operations occur on the same bin. + * Asynchronously perform multiple read/write operations on a single key in one call. + *
Example usage for this method.
+ *{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * client.operate(loop, recordListener, null, key, Operation.add(new Bin("ctr", 1)), Operation.get("ctr"));
+ * }
*
* @param eventLoop event loop that will process the command. If NULL, the event
* loop will be chosen by round-robin.
@@ -2927,7 +3299,9 @@ public final Record operate(WritePolicy policy, Key key, Operation... operations
* @param policy write configuration parameters, pass in null for defaults
* @param key unique record identifier
* @param operations database operations to perform
- * @throws AerospikeException if event loop registration fails
+ * @throws AerospikeException when event loop registration fails
+ * @see #operate(WritePolicy, Key, Operation...)
+ * @see RecordListener
*/
public final void operate(EventLoop eventLoop, RecordListener listener, WritePolicy policy, Key key, Operation... operations)
throws AerospikeException {
@@ -2961,19 +3335,26 @@ public final void operate(EventLoop eventLoop, RecordListener listener, WritePol
//-------------------------------------------------------
/**
- * Read/Write multiple records for specified batch keys in one batch call.
- * This method allows different namespaces/bins for each key in the batch.
- * The returned records are located in the same list.
+ * Read/write multiple records in one batch call; each item can be a different namespace/set/ops.
+ * Example usage for this method.
+ *{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * java.util.List<BatchRecord> records = java.util.Arrays.asList(
+ * new BatchRead(new Key("ns", "set", "k1")),
+ * new BatchWrite(new Key("ns", "set", "k2"), new Bin("x", 1)));
+ * boolean ok = client.operate(null, records);
+ * client.close();
+ * }
* * {@link BatchRecord} can be {@link BatchRead}, {@link BatchWrite}, {@link BatchDelete} or - * {@link BatchUDF}. - *
- * Requires server version 6.0+
+ * {@link BatchUDF}. Requires server version 6.0+.
*
* @param policy batch configuration parameters, pass in null for defaults
- * @param records list of unique record identifiers and read/write operations
+ * @param records list of batch record operations
* @return true if all batch sub-commands succeeded
- * @throws AerospikeException if command fails
+ * @throws AerospikeException when command fails
+ * @see BatchRead
+ * @see BatchWrite
*/
public final boolean operate(BatchPolicy policy, List
- * This method allows different namespaces/bins to be requested for each key in the batch.
- * The returned records are located in the same list.
+ * Asynchronously read/write multiple records in one batch; results in one callback.
+ * Example usage for this method.
* {@link BatchRecord} can be {@link BatchRead}, {@link BatchWrite}, {@link BatchDelete} or
- * {@link BatchUDF}.
- *
- * Requires server version 6.0+
+ * {@link BatchUDF}. Requires server version 6.0+.
*
* @param eventLoop event loop that will process the command. If NULL, the event
* loop will be chosen by round-robin.
* @param listener where to send results
* @param policy batch configuration parameters, pass in null for defaults
- * @param records list of unique record identifiers and read/write operations
- * @throws AerospikeException if event loop registration fails
+ * @param records list of batch record operations
+ * @throws AerospikeException when event loop registration fails
+ * @see #operate(BatchPolicy, List)
+ * @see BatchOperateListListener
*/
public final void operate(
EventLoop eventLoop,
@@ -3205,24 +3591,29 @@ public final void operate(
}
/**
- * Asynchronously read/write multiple records for specified batch keys in one batch call.
- * This method registers the command with an event loop and returns.
- * The event loop thread will process the command and send the results to the listener.
- *
- * This method allows different namespaces/bins to be requested for each key in the batch.
- * Each record result is returned in separate onRecord() calls.
+ * Asynchronously read/write multiple records in one batch; each result via onRecord().
+ * Example usage for this method.
* {@link BatchRecord} can be {@link BatchRead}, {@link BatchWrite}, {@link BatchDelete} or
- * {@link BatchUDF}.
- *
- * Requires server version 6.0+
+ * {@link BatchUDF}. Requires server version 6.0+.
*
* @param eventLoop event loop that will process the command. If NULL, the event
* loop will be chosen by round-robin.
* @param listener where to send results
* @param policy batch configuration parameters, pass in null for defaults
- * @param records list of unique record identifiers and read/write operations
- * @throws AerospikeException if event loop registration fails
+ * @param records list of batch record operations
+ * @throws AerospikeException when event loop registration fails
+ * @see #operate(BatchPolicy, List)
+ * @see BatchRecordSequenceListener
*/
public final void operate(
EventLoop eventLoop,
@@ -3335,19 +3726,27 @@ public final void operate(
}
/**
- * Perform read/write operations on multiple keys. If a key is not found, the corresponding result
- * {@link BatchRecord#resultCode} will be {@link ResultCode#KEY_NOT_FOUND_ERROR}.
+ * Perform the same read/write operations on multiple keys; result order matches key order.
+ * Example usage for this method.
- * Requires server version 6.0+
+ * If a key is not found, the corresponding result {@link BatchRecord#resultCode} will be
+ * {@link ResultCode#KEY_NOT_FOUND_ERROR}. Use {@link Operation#get(String)} per bin; {@link Operation#get()} is not allowed.
+ * Requires server version 6.0+.
*
* @param batchPolicy batch configuration parameters, pass in null for defaults
* @param writePolicy write configuration parameters, pass in null for defaults
* @param keys array of unique record identifiers
- * @param ops
- * read/write operations to perform. {@link Operation#get()} is not allowed because it returns a
- * variable number of bins and makes it difficult (sometimes impossible) to lineup operations
- * with results. Instead, use {@link Operation#get(String)} for each bin name.
- * @throws AerospikeException.BatchRecordArray which contains results for keys that did complete
+ * @param ops read/write operations to perform
+ * @return batch results (one per key)
+ * @throws AerospikeException.BatchRecordArray when some keys fail (contains partial results)
+ * @see #operate(WritePolicy, Key, Operation...)
+ * @see BatchResults
*/
public final BatchResults operate(
BatchPolicy batchPolicy,
@@ -3418,14 +3817,17 @@ public final BatchResults operate(
}
/**
- * Asynchronously perform read/write operations on multiple keys.
- * This method registers the command with an event loop and returns.
- * The event loop thread will process the command and send the results to the listener.
- *
- * If a key is not found, the corresponding result {@link BatchRecord#resultCode} will be
- * {@link ResultCode#KEY_NOT_FOUND_ERROR}.
- *
- * Requires server version 6.0+
+ * Asynchronously perform the same read/write operations on multiple keys; results in one callback.
+ * Example usage for this method.
- * Each record result is returned in separate onRecord() calls.
- * If a key is not found, the corresponding result {@link BatchRecord#resultCode} will be
- * {@link ResultCode#KEY_NOT_FOUND_ERROR}.
- *
- * Requires server version 6.0+
+ * Asynchronously perform the same read/write operations on multiple keys; each result via onRecord().
+ * Example usage for this method. Example usage for this method. Example usage for this method.
- * {@code udf file =
- * The function operates on a single record.
- * The package name is used to locate the udf file location:
- *
- * {@code udf file = Example usage for this method.
- * {@code udf file = Example usage for this method.
- * Requires server version 6.0+
+ * UDF file location: {@code
- * The package name is used to locate the udf file location:
+ * Asynchronously execute a UDF on each of the given keys; results in one callback.
+ * Example usage for this method.
- * {@code udf file =
- * Requires server version 6.0+
+ * Requires server version 6.0+.
*
* @param eventLoop event loop that will process the command. If NULL, the event
* loop will be chosen by round-robin.
@@ -4101,7 +4532,9 @@ public final BatchResults execute(
* @param packageName server package name where user defined function resides
* @param functionName user defined function
* @param functionArgs arguments passed in to user defined function
- * @throws AerospikeException if command fails
+ * @throws AerospikeException when event loop registration fails
+ * @see #execute(BatchPolicy, BatchUDFPolicy, Key[], String, String, Value...)
+ * @see BatchRecordArrayListener
*/
public final void execute(
EventLoop eventLoop,
@@ -4166,16 +4599,19 @@ public final void execute(
}
/**
- * Asynchronously execute user defined function on server for each key and return results.
- * This method registers the command with an event loop and returns.
- * The event loop thread will process the command and send the results to the listener.
- * Each record result is returned in separate onRecord() calls.
- *
- * The package name is used to locate the udf file location:
+ * Asynchronously execute a UDF on each of the given keys; each result via onRecord().
+ * Example usage for this method.
- * {@code udf file =
- * Requires server version 6.0+
+ * Requires server version 6.0+.
*
* @param eventLoop event loop that will process the command. If NULL, the event
* loop will be chosen by round-robin.
@@ -4186,7 +4622,9 @@ public final void execute(
* @param packageName server package name where user defined function resides
* @param functionName user defined function
* @param functionArgs arguments passed in to user defined function
- * @throws AerospikeException if command fails
+ * @throws AerospikeException when event loop registration fails
+ * @see #execute(BatchPolicy, BatchUDFPolicy, Key[], String, String, Value...)
+ * @see BatchRecordSequenceListener
*/
public final void execute(
EventLoop eventLoop,
@@ -4250,18 +4688,25 @@ public final void execute(
//----------------------------------------------------------
/**
- * Apply user defined function on records that match the background query statement filter.
- * Records are not returned to the client.
- * This asynchronous server call will return before the command is complete.
- * The user can optionally wait for command completion by using the returned
- * ExecuteTask instance.
+ * Run a UDF in the background on all records matching the statement; returns a task to wait for completion.
+ * Example usage for this method. Example usage for this method. Example usage for this method.
- * This method is not recommended for paginated queries when the user does not iterate through
- * all records in the RecordSet. In this case, there is a lag between when the client marks the
- * last record retrieved from the server and when the record is retrieved from the RecordSet.
- * For this case, use {@link #query(QueryPolicy, Statement, QueryListener)} which uses a listener
- * callback (without a buffer) instead of a RecordSet.
+ * For paginated use without consuming the full RecordSet, prefer {@link #query(QueryPolicy, Statement, QueryListener)}.
*
* @param policy query configuration parameters, pass in null for defaults
* @param statement query definition
* @return record iterator
- * @throws AerospikeException if query fails
+ * @throws AerospikeException when query fails
+ * @see #query(EventLoop, RecordSequenceListener, QueryPolicy, Statement)
+ * @see Statement
+ * @see RecordSet
*/
public final RecordSet query(QueryPolicy policy, Statement statement)
throws AerospikeException {
@@ -4376,18 +4833,26 @@ public final RecordSet query(QueryPolicy policy, Statement statement)
}
/**
- * Asynchronously execute query on all server nodes.
- * This method registers the command with an event loop and returns.
- * The event loop thread will process the command and send the results to the listener.
- *
- * Each record result is returned in separate onRecord() calls.
+ * Asynchronously execute a query on all nodes; each record via onRecord().
+ * Example usage for this method.
- * If {@link com.aerospike.client.policy.QueryPolicy#maxConcurrentNodes} is not 1, the supplied
- * listener must handle shared data in a thread-safe manner, because the listener will be called
- * by multiple query threads (one thread per node) in parallel.
+ * Execute a query on all nodes and deliver records via the listener; blocks until complete.
+ * Example usage for this method.
- * Requires server version 6.0+ if using a secondary index query.
+ * If maxConcurrentNodes is not 1, the listener may be called from multiple threads.
+ * Requires server version 6.0+ for secondary index queries.
*
* @param policy query configuration parameters, pass in null for defaults
* @param statement query definition
* @param listener where to send results
- * @throws AerospikeException if query fails
+ * @throws AerospikeException when query fails
+ * @see #query(QueryPolicy, Statement)
+ * @see QueryListener
*/
public final void query(
QueryPolicy policy,
@@ -4450,25 +4920,29 @@ public final void query(
}
/**
- * Execute query for specified partitions and return records via the listener. This method will
- * block until the query is complete. Listener callbacks are made within the scope of this call.
+ * Execute a query for specified partitions and deliver records via the listener; blocks until complete.
+ * Example usage for this method.
- * If {@link com.aerospike.client.policy.QueryPolicy#maxConcurrentNodes} is not 1, the supplied
- * listener must handle shared data in a thread-safe manner, because the listener will be called
- * by multiple query threads (one thread per node) in parallel.
- *
- * The completion status of all partitions is stored in the partitionFilter when the query terminates.
- * This partitionFilter can then be used to resume an incomplete query at a later time.
- * This is the preferred method for query terminate/resume functionality.
- *
- * Requires server version 6.0+ if using a secondary index query.
+ * Completion status is stored in partitionFilter when the query ends; use it to resume later.
+ * If maxConcurrentNodes is not 1, the listener may be called from multiple threads.
+ * Requires server version 6.0+ for secondary index queries.
*
* @param policy query configuration parameters, pass in null for defaults
* @param statement query definition
- * @param partitionFilter data partition filter. Set to
- * {@link com.aerospike.client.query.PartitionFilter#all()} for all partitions.
+ * @param partitionFilter partition filter (e.g. {@link com.aerospike.client.query.PartitionFilter#all()}); updated on completion for resume
* @param listener where to send results
- * @throws AerospikeException if query fails
+ * @throws AerospikeException when query fails
+ * @see #queryPartitions(QueryPolicy, Statement, PartitionFilter)
+ * @see #queryPartitions(EventLoop, RecordSequenceListener, QueryPolicy, Statement, PartitionFilter)
+ * @see QueryListener
+ * @see PartitionFilter
*/
public final void query(
QueryPolicy policy,
@@ -4494,15 +4968,26 @@ public final void query(
}
/**
- * Execute query on a single server node and return record iterator. The query executor puts
- * records on a queue in a separate thread. The calling thread concurrently pops records off
- * the queue through the record iterator.
+ * Execute a query on a single node and return a record iterator.
+ * Example usage for this method. Example usage for this method.
- * Requires server version 6.0+ if using a secondary index query.
+ * Requires server version 6.0+ for secondary index queries.
*
* @param policy query configuration parameters, pass in null for defaults
* @param statement query definition
- * @param partitionFilter filter on a subset of data partitions
- * @throws AerospikeException if query fails
+ * @param partitionFilter filter on a subset of data partitions (e.g. PartitionFilter.all())
+ * @return record iterator
+ * @throws AerospikeException when query fails
+ * @see #query(QueryPolicy, Statement, PartitionFilter, QueryListener)
+ * @see #queryPartitions(EventLoop, RecordSequenceListener, QueryPolicy, Statement, PartitionFilter)
+ * @see PartitionFilter
+ * @see RecordSet
*/
public final RecordSet queryPartitions(
QueryPolicy policy,
@@ -4560,21 +5057,32 @@ public final RecordSet queryPartitions(
}
/**
- * Asynchronously execute query for specified partitions.
- * This method registers the command with an event loop and returns.
- * The event loop thread will process the command and send the results to the listener.
- *
- * Each record result is returned in separate onRecord() calls.
+ * Asynchronously execute a query for specified partitions; each record via onRecord().
+ * Example usage for this method.
- * Requires server version 6.0+ if using a secondary index query.
+ * Requires server version 6.0+ for secondary index queries.
*
* @param eventLoop event loop that will process the command. If NULL, the event
* loop will be chosen by round-robin.
* @param listener where to send results
* @param policy query configuration parameters, pass in null for defaults
* @param statement query definition
- * @param partitionFilter filter on a subset of data partitions
- * @throws AerospikeException if query fails
+ * @param partitionFilter filter on a subset of data partitions (e.g. PartitionFilter.all())
+ * @throws AerospikeException when event loop registration fails or query fails
+ * @see #queryPartitions(QueryPolicy, Statement, PartitionFilter)
+ * @see #query(QueryPolicy, Statement, PartitionFilter, QueryListener)
+ * @see RecordSequenceListener
+ * @see PartitionFilter
*/
public final void queryPartitions(
EventLoop eventLoop,
@@ -4605,23 +5113,27 @@ public final void queryPartitions(
}
/**
- * Execute query, apply statement's aggregation function, and return result iterator. The query
- * executor puts results on a queue in separate threads. The calling thread concurrently pops
- * results off the queue through the result iterator.
- *
- * The aggregation function is called on both server and client (final reduce). Therefore,
- * the Lua script files must also reside on both server and client.
- * The package name is used to locate the udf file location:
+ * Execute a query with an aggregation UDF and return a result iterator; UDF is specified by package/function.
+ * Example usage for this method.
- * {@code udf file = Example usage for this method.
- * The query executor puts results on a queue in separate threads. The calling thread
- * concurrently pops results off the queue through the ResultSet iterator.
- * The aggregation function is called on both server and client (final reduce).
- * Therefore, the Lua script file must also reside on both server and client.
+ * Aggregation runs on server and client (final reduce); UDF must exist on both.
*
* @param policy query configuration parameters, pass in null for defaults
- * @param statement query definition
- * @throws AerospikeException if query fails
+ * @param statement query definition (aggregation set via setAggregateFunction())
+ * @return result iterator
+ * @throws AerospikeException when query fails
+ * @see #queryAggregate(QueryPolicy, Statement, String, String, Value...)
+ * @see #queryAggregateNode(QueryPolicy, Statement, Node)
+ * @see ResultSet
*/
public final ResultSet queryAggregate(QueryPolicy policy, Statement statement)
throws AerospikeException {
@@ -4662,20 +5182,28 @@ public final ResultSet queryAggregate(QueryPolicy policy, Statement statement)
}
/**
- * Execute query on a single server node, apply statement's aggregation function, and return
- * result iterator.
- * The aggregation function should be initialized via the statement's setAggregateFunction()
- * and should be located in a resource or a filesystem file.
+ * Execute a query with aggregation on a single node; use statement's setAggregateFunction() first.
+ * Example usage for this method.
- * The query executor puts results on a queue in separate threads. The calling thread
- * concurrently pops results off the queue through the ResultSet iterator.
- * The aggregation function is called on both server and client (final reduce).
- * Therefore, the Lua script file must also reside on both server and client.
+ * Aggregation runs on server and client (final reduce); UDF must exist on both.
*
* @param policy query configuration parameters, pass in null for defaults
- * @param statement query definition
+ * @param statement query definition (aggregation set via setAggregateFunction())
* @param node server node to execute query
- * @throws AerospikeException if query fails
+ * @return result iterator
+ * @throws AerospikeException when query fails
+ * @see #queryAggregate(QueryPolicy, Statement)
+ * @see ResultSet
+ * @see Node
*/
public final ResultSet queryAggregateNode(QueryPolicy policy, Statement statement, Node node)
throws AerospikeException {
@@ -4694,10 +5222,14 @@ public final ResultSet queryAggregateNode(QueryPolicy policy, Statement statemen
//--------------------------------------------------------
/**
- * Create scalar secondary index.
- * This asynchronous server call will return before command is complete.
- * The user can optionally wait for command completion by using the returned
- * IndexTask instance.
+ * Create a scalar secondary index; returns a task to wait for completion.
+ * Example usage for this method. Example usage for this method. Example usage for this method. Example usage for this method. Example usage for this method. Example usage for this method. Example usage for this method. Example usage for this method.
- * The info protocol is a name/value pair based system, where an individual
- * database server node is queried to determine its configuration and status.
- * The list of supported info commands can be found at:
- * https://www.aerospike.com/docs/reference/info/index.html
+ * Info is a name/value protocol for node configuration and status. Supported commands:
+ * aerospike.com/docs/reference/info
*
* @param eventLoop event loop that will process the command. If NULL, the event
* loop will be chosen by round-robin.
* @param listener where to send results
* @param policy info configuration parameters, pass in null for defaults
* @param node server node to execute command, pass in null for random node
- * @param commands list of info commands
- * @throws AerospikeException if info commands fail
+ * @param commands list of info commands (e.g. "build", "statistics")
+ * @throws AerospikeException when info commands fail
+ * @see Info
+ * @see InfoListener
*/
public final void info(
EventLoop eventLoop,
@@ -5015,15 +5608,26 @@ public final void info(
//-----------------------------------------------------------------
/**
- * Set XDR filter for given datacenter name and namespace. The expression filter indicates
- * which records XDR should ship to the datacenter. If the expression filter is null, the
- * XDR filter will be removed.
+ * Set or remove XDR filter for a datacenter and namespace; null filter removes the filter.
+ * Example usage for this method. Example usage for this method. Example usage for this method. Example usage for this method. Example usage for this method. Example usage for this method. Example usage for this method. Example usage for this method.
+ * Quotas require server "enable-quotas" to be true.
*
* @param policy admin configuration parameters, pass in null for defaults
* @param roleName role name
- * @param privileges optional list of privileges assigned to role.
- * @param whitelist optional list of allowable IP addresses assigned to role.
- * IP addresses can contain wildcards (ie. 10.1.2.0/24).
- * @param readQuota optional maximum reads per second limit, pass in zero for no limit.
- * @param writeQuota optional maximum writes per second limit, pass in zero for no limit.
- * @throws AerospikeException if command fails
+ * @param privileges optional list of privileges assigned to role
+ * @param whitelist optional list of allowable IP addresses (e.g. 10.1.2.0/24)
+ * @param readQuota maximum reads per second, or zero for no limit
+ * @param writeQuota maximum writes per second, or zero for no limit
+ * @throws AerospikeException when command fails
+ * @see #createRole(AdminPolicy, String, List, List)
+ * @see #setQuotas(AdminPolicy, String, int, int)
*/
public final void createRole(
AdminPolicy policy,
@@ -5215,11 +5897,19 @@ public final void createRole(
}
/**
- * Drop user defined role.
+ * Drop a user-defined role.
+ * Example usage for this method. Example usage for this method. Example usage for this method. Example usage for this method. Example usage for this method. Example usage for this method. Example usage for this method.
+ * Use {@link #getResultCode()} and {@link ResultCode#getResultString(int)} to interpret; use {@link #getBaseMessage()} for the message without metadata. Subclasses denote timeout, connection, batch, transaction commit, and scan/query termination.
+ *
+ * Example:
+ * Catch an exception, get result code and message, and check in-doubt for writes.
+ * Fields {@link #connectTimeout}, {@link #socketTimeout}, {@link #timeout} reflect policy values; {@link #client} is true for client-initiated timeout.
+ *
+ * @see ResultCode#TIMEOUT
+ * @see com.aerospike.client.policy.Policy#totalTimeout
*/
public static final class Timeout extends AerospikeException {
private static final long serialVersionUID = 1L;
@@ -310,7 +349,9 @@ public Timeout(Node node, int connectTimeout, int socketTimeout, int totalTimeou
}
/**
- * Exception thrown when a Java serialization error occurs.
+ * Thrown when a Java serialization error occurs (e.g. value cannot be serialized for the wire).
+ *
+ * @see ResultCode#SERIALIZE_ERROR
*/
public static final class Serialize extends AerospikeException {
private static final long serialVersionUID = 1L;
@@ -325,7 +366,9 @@ public Serialize(String message) {
}
/**
- * Exception thrown when client can't parse data returned from server.
+ * Thrown when the client cannot parse data returned from the server.
+ *
+ * @see ResultCode#PARSE_ERROR
*/
public static final class Parse extends AerospikeException {
private static final long serialVersionUID = 1L;
@@ -336,7 +379,9 @@ public Parse(String message) {
}
/**
- * Exception thrown when client can't connect to the server.
+ * Thrown when the client cannot connect to the server (e.g. host unreachable, connection refused).
+ *
+ * @see ResultCode#SERVER_NOT_AVAILABLE
*/
public static final class Connection extends AerospikeException {
private static final long serialVersionUID = 1L;
@@ -359,8 +404,9 @@ public Connection(int resultCode, String message) {
}
/**
- * Exception thrown when the selected node is not active, or when the namespace
- * is removed after the client has connected.
+ * Thrown when the selected node is not active or the namespace is removed after the client has connected.
+ *
+ * @see ResultCode#INVALID_NODE_ERROR
*/
public static final class InvalidNode extends AerospikeException {
private static final long serialVersionUID = 1L;
@@ -380,7 +426,9 @@ public InvalidNode(String message) {
}
/**
- * Exception thrown when namespace is invalid.
+ * Thrown when the namespace is invalid or not found in the partition map.
+ *
+ * @see ResultCode#INVALID_NAMESPACE
*/
public static final class InvalidNamespace extends AerospikeException {
private static final long serialVersionUID = 1L;
@@ -392,11 +440,14 @@ public InvalidNamespace(String ns, int mapSize) {
}
/**
- * Exception thrown when a batch exists method fails.
+ * Thrown when a batch exists method fails; {@link #exists} holds per-key existence results for keys that were completed.
+ *
+ * @see com.aerospike.client.AerospikeClient#exists(BatchPolicy, Key[])
*/
public static final class BatchExists extends AerospikeException {
private static final long serialVersionUID = 1L;
+ /** Existence result per key; length matches the request key array. */
public final boolean[] exists;
public BatchExists(boolean[] exists, Throwable e) {
@@ -406,13 +457,14 @@ public BatchExists(boolean[] exists, Throwable e) {
}
/**
- * Exception thrown when a batch read method fails.
- * The records fields contains responses for key requests that succeeded and null
- * records for key requests that failed.
+ * Thrown when a batch read method fails; {@link #records} contains responses for keys that succeeded (null for failed keys).
+ *
+ * @see com.aerospike.client.AerospikeClient#get
*/
public static final class BatchRecords extends AerospikeException {
private static final long serialVersionUID = 1L;
+ /** Record per key; null for keys that failed or were not found. */
public final Record[] records;
public BatchRecords(Record[] records, Throwable e) {
@@ -422,13 +474,16 @@ public BatchRecords(Record[] records, Throwable e) {
}
/**
- * Exception thrown when a batch write method fails.
- * The records fields contains responses for key requests that succeeded
- * and resultCodes for key requests that failed.
+ * Thrown when a batch write/operate/delete method fails; {@link #records} contains per-key results (use {@link BatchRecord#resultCode} for each).
+ *
+ * @see BatchRecord
+ * @see com.aerospike.client.AerospikeClient#operate
+ * @see com.aerospike.client.AerospikeClient#delete
*/
public static final class BatchRecordArray extends AerospikeException {
private static final long serialVersionUID = 1L;
+ /** BatchRecord per key; check each resultCode. */
public final BatchRecord[] records;
public BatchRecordArray(BatchRecord[] records, Throwable e) {
@@ -443,7 +498,10 @@ public BatchRecordArray(BatchRecord[] records, String message, Throwable e) {
}
/**
- * Exception thrown when scan was terminated prematurely.
+ * Thrown when a scan is terminated prematurely (e.g. by the user throwing from {@link com.aerospike.client.ScanCallback}).
+ *
+ * @see ResultCode#SCAN_TERMINATED
+ * @see com.aerospike.client.ScanCallback
*/
public static final class ScanTerminated extends AerospikeException {
private static final long serialVersionUID = 1L;
@@ -458,7 +516,10 @@ public ScanTerminated(Throwable e) {
}
/**
- * Exception thrown when query was terminated prematurely.
+ * Thrown when a query is terminated prematurely (e.g. by the user throwing from {@link com.aerospike.client.query.QueryListener}).
+ *
+ * @see ResultCode#QUERY_TERMINATED
+ * @see com.aerospike.client.query.QueryListener
*/
public static final class QueryTerminated extends AerospikeException {
private static final long serialVersionUID = 1L;
@@ -473,8 +534,10 @@ public QueryTerminated(Throwable e) {
}
/**
- * Exception thrown when async command was rejected because the
- * async delay queue is full.
+ * Thrown when an async command was rejected because the async delay queue is full.
+ *
+ * @see ResultCode#ASYNC_QUEUE_FULL
+ * @see Backoff
*/
public static final class AsyncQueueFull extends Backoff {
private static final long serialVersionUID = 1L;
@@ -485,8 +548,9 @@ public AsyncQueueFull() {
}
/**
- * Exception thrown when node is in backoff mode due to excessive
- * number of errors.
+ * Thrown when a node is in backoff mode due to an excessive number of errors.
+ *
+ * @see AsyncQueueFull
*/
public static class Backoff extends AerospikeException {
private static final long serialVersionUID = 1L;
@@ -497,26 +561,36 @@ public Backoff(int resultCode) {
}
/**
- * Exception thrown when a transaction commit fails.
+ * Thrown when a transaction commit fails; use {@link #error} for the commit error code and {@link #verifyRecords}/{@link #rollRecords} for per-key details.
+ *
+ * Catch when calling {@link com.aerospike.client.AerospikeClient#commit}; then call {@link com.aerospike.client.AerospikeClient#abort} if appropriate.
+ *
+ * Example:
+ * Catch commit failure, read error and abort the transaction.
+ * Pass a list to {@link com.aerospike.client.AerospikeClient#operate} (BatchRecord list can mix BatchDelete with other types) or use {@link com.aerospike.client.AerospikeClient#delete(BatchPolicy, BatchDeletePolicy, Key[])} for keys-only with a single policy. After the call, check {@link BatchRecord#resultCode}.
+ *
+ * Use when each key needs different bins or operations. Pass an array to {@link com.aerospike.client.AerospikeClient#get(BatchPolicy, BatchRead[])} or async overloads with {@link com.aerospike.client.listener.BatchListListener} / {@link com.aerospike.client.listener.BatchSequenceListener}. Use {@link Operation#get(String)} per bin, not {@link Operation#get()}.
+ *
+ *
+ * Pass an array to {@link com.aerospike.client.AerospikeClient#operate} (same as batch operate) or async overloads. Each element can use a different UDF or args.
+ *
+ * Pass an array to {@link com.aerospike.client.AerospikeClient#operate} or async overloads with {@link com.aerospike.client.listener.BatchRecordArrayListener} / {@link com.aerospike.client.listener.BatchRecordSequenceListener}. Use {@link Operation#get(String)} per bin, not {@link Operation#get()}, so results align with operations.
+ *
+ * Bin names are limited to {@link #MAX_BIN_NAME_LENGTH} characters. Use {@link Value} for typed values.
+ *
+ * Example:
+ * Put a record with multiple bins using Bin name/value pairs. Example:
+ * Catch commit exception and handle CommitError (e.g. verify failure). Example:
+ * Commit a transaction and handle the returned status (OK, abandoned, etc.).
+ * Format for parsing: {@code hostname[:tlsname][:port],...}. Use {@link #parseHosts(String, int)} or {@link #parseServiceHosts(String)} to build a list.
+ *
+ * Example:
+ * Parse host string and port into Host array and create a client.
- * The info protocol is a name/value pair based system, where an individual
- * database server node is queried to determine its configuration and status.
- * The list of supported names can be found at:
- *
- * https://www.aerospike.com/docs/reference/info/index.html
+ * Query a single node for configuration and status. Supported command names: Aerospike Info Reference.
+ *
+ * Example:
+ * Request info from a node (e.g. "build" or "statistics").
+ * The user key is hashed to a digest; set {@link com.aerospike.client.policy.WritePolicy#sendKey} to store/retrieve the key on the server.
+ *
+ * Example:
+ * Create a key and use it to get a record.
+ * Pass to {@link com.aerospike.client.AerospikeClient#register} for UDF package registration.
+ *
+ * Example:
+ * Register a UDF package using Language.LUA.
+ * Supports read (get, getHeader), write (put, append, prepend, add), touch, and delete. Multiple operations are executed atomically.
+ *
+ * Example:
+ * Atomically add to a bin and read it back using operate.
+ * Use {@link #getValue(String)} or typed getters such as {@link #getString(String)}, {@link #getLong(String)} to read bins.
+ *
+ * Example:
+ * Read a record and access bins with getString/getLong.
+ * Use {@link AerospikeException#getResultCode()} and {@link #getResultString(int)} to interpret failures.
+ *
+ * Example:
+ * Get result code and message from an AerospikeException after a failed put. Use {@link com.aerospike.client.query.QueryListener} with
- * {@link com.aerospike.client.AerospikeClient#query(com.aerospike.client.policy.QueryPolicy, com.aerospike.client.query.Statement, com.aerospike.client.query.QueryListener)}
- * instead. create a {@link com.aerospike.client.query.Statement} with the same namespace and set name (no filter),
- * set bin names if needed, then call {@code query(queryPolicy, statement, queryListener)}.
- * For partition-scoped reads use {@link com.aerospike.client.AerospikeClient#queryPartitions(com.aerospike.client.policy.QueryPolicy, com.aerospike.client.query.Statement, com.aerospike.client.query.PartitionFilter)}.
- * Use {@link com.aerospike.client.query.QueryListener} with {@link com.aerospike.client.AerospikeClient#query}
+ * instead.Create a {@link com.aerospike.client.query.Statement} with the same namespace and set name (no filter),
+ * then call {@code query(queryPolicy, statement, queryListener)}. For partition-scoped reads use
+ * {@link com.aerospike.client.AerospikeClient#queryPartitions}.
+ *
+ * Example (deprecated; prefer query with QueryListener):
+ *
- * If {@link com.aerospike.client.policy.ScanPolicy#concurrentNodes} is true and
- * {@link com.aerospike.client.policy.ScanPolicy#maxConcurrentNodes} is not equal one, then
- * your scanCallback implementation must be thread safe.
+ * If {@link com.aerospike.client.policy.ScanPolicy#concurrentNodes} is true and maxConcurrentNodes is not one, the implementation must be thread-safe.
*
- * @param key unique record identifier
- * @param record container for bins and record meta-data
- * @throws AerospikeException if error occurs or scan should be terminated.
+ * @param key unique record identifier; never null
+ * @param record container for bins and metadata; never null
+ * @throws AerospikeException when the callback wishes to abort the scan or report an error (e.g. throw ScanTerminated to abort).
*/
public void scanCallback(Key key, Record record) throws AerospikeException;
}
diff --git a/client/src/com/aerospike/client/Txn.java b/client/src/com/aerospike/client/Txn.java
index 17823bd8a..9fb658eaf 100644
--- a/client/src/com/aerospike/client/Txn.java
+++ b/client/src/com/aerospike/client/Txn.java
@@ -23,12 +23,32 @@
import java.util.concurrent.atomic.AtomicLong;
/**
- * Multi-record transaction. Each command in the transaction must use the same namespace.
+ * Multi-record transaction; all commands must use the same namespace. Set {@link com.aerospike.client.policy.Policy#txn} on the write policy, then call {@link com.aerospike.client.AerospikeClient#commit} or {@link com.aerospike.client.AerospikeClient#abort}.
+ *
+ * Example:
+ * Run a multi-record transaction: get, put with txn policy, then commit.
+ * Concrete types represent strings, numbers, blobs, lists, maps, GeoJSON, etc. Use with {@link Bin} and
+ * {@link com.aerospike.client.AerospikeClient#put}, {@link com.aerospike.client.AerospikeClient#operate}, and expression APIs.
+ *
+ * Concrete value types (child classes): {@link NullValue}, {@link BytesValue}, {@link ByteSegmentValue}, {@link ByteValue},
+ * {@link StringValue}, {@link ShortValue}, {@link IntegerValue}, {@link LongValue}, {@link DoubleValue}, {@link FloatValue},
+ * {@link BooleanValue}, {@link BoolIntValue}, {@link GeoJSONValue}, {@link HLLValue}, {@link ValueArray}, {@link ListValue},
+ * {@link MapValue}, {@link SortedMapValue}, {@link InfinityValue}, and {@link WildcardValue}.
+ *
+ * Example:
+ * Put a record with string and integer bins using IAerospikeClient. Example:
+ * Store a null bin using Value.getAsNull(). Example:
+ * Store a blob bin with Value.get(byte[]). Example:
+ * Store a byte segment with Value.get(array, offset, length). Example:
+ * Store a byte bin with Value.get(byte). Example:
+ * Store a string bin with Value.get(String). Example:
+ * Store a short bin with Value.get(short). Example:
+ * Store an integer bin with Value.get(int). Example:
+ * Store a long bin with Value.get(long). Example:
+ * Store a double bin with Value.get(double). Example:
+ * Store a float bin with Value.get(float). Example:
+ * Store a boolean bin with Value.get(boolean). Example:
+ * Store boolean as integer when UseBoolBin is false. Example:
+ * Store a GeoJSON bin with Value.getAsGeoJSON(String). Example:
+ * Store an HLL bin with Value.getAsHLL(byte[]). Example:
+ * Store a list bin from Value array with Value.get(Value[]). Example:
+ * Store a list bin with Value.get(List). Example:
+ * Store a map bin with Value.get(Map). Example:
+ * Store a sorted map bin with Value.get(SortedMap). Example:
+ * Use Value.INFINITY in map/list range operations (e.g. getByValueRange). Example:
+ * Use Value.WILDCARD in map/list range operations (e.g. getByValueRange).
+ * Set {@link #namespace} and {@link #setName} to null for global scope when the privilege allows it; use {@link PrivilegeCode#canScope()} to check.
+ *
+ * Example:
+ * Create a privilege with namespace scope and use it in createRole.
+ * Use {@link #fromId(int)} to map server-returned IDs; use {@link #canScope()} to see if namespace/set scope applies.
+ *
+ * Example:
+ * Create a role with READ_WRITE privilege scoped to a namespace.
+ * Use the static constants (e.g. {@link #Read}, {@link #ReadWrite}) as role names when creating users; use {@link Privilege} for fine-grained role definitions.
+ *
+ * Example:
+ * Query a role and read its name and privileges.
+ * {@link #readInfo} and {@link #writeInfo} are server-defined statistic lists (e.g. quota, TPS, RPS); offsets may change in future server versions.
+ *
+ * Example:
+ * Query a user and read name and roles.
+ * Use {@link #queryStatus(EventLoop, InfoPolicy, Node, TaskStatusListener)} to check a node; all nodes must report 100% load for the task to be done.
+ *
+ * Obtain an event loop from {@link EventLoops#next()} or {@link EventLoops#get(int)} and pass it
+ * to async client methods (e.g. {@link com.aerospike.client.IAerospikeClient#get}).
+ *
+ * Value is approximate when called from a different thread. For accuracy from another thread, run this inside {@link #execute(Runnable)} on this event loop.
+ * @return approximate process size (non-negative)
*/
public int getProcessSize();
/**
- * Return the approximate number of commands stored on this event loop's
- * delay queue that have not been started yet. The value is approximate
- * because the call may be from a different thread than the event loop’s
- * thread and there are no locks or atomics used.
- *
- * If accuracy is important and not running in the event loop thread,
- * the slower execute(Runnable) can be called to run this method in the
- * event loop thread.
+ * Approximate number of commands on this event loop's delay queue not yet started.
+ *
+ * Value is approximate when called from a different thread. For accuracy from another thread, run this inside {@link #execute(Runnable)} on this event loop.
+ * @return approximate queue size (non-negative)
*/
public int getQueueSize();
- /**
- * Return event loop array index.
- */
+ /** @return this event loop's index in its {@link EventLoops} array */
public int getIndex();
- /**
- * Is current thread the event loop thread.
-= */
+ /** @return true if the current thread is this event loop's thread */
public boolean inEventLoop();
- /**
- * For internal use only.
- */
+ /** For internal use only. */
public EventState createState();
}
diff --git a/client/src/com/aerospike/client/async/EventLoopStats.java b/client/src/com/aerospike/client/async/EventLoopStats.java
index 4f8997c54..66b8ab67b 100644
--- a/client/src/com/aerospike/client/async/EventLoopStats.java
+++ b/client/src/com/aerospike/client/async/EventLoopStats.java
@@ -17,32 +17,32 @@
package com.aerospike.client.async;
/**
- * Event loop statistics.
+ * Snapshot of a single event loop's load (process and queue sizes).
+ *
+ * Used in {@link com.aerospike.client.cluster.ClusterStats#eventLoops}; obtain via {@link com.aerospike.client.AerospikeClient#getClusterStats()}.
+ *
+ * @see com.aerospike.client.cluster.ClusterStats
+ * @see EventLoop#getProcessSize
+ * @see EventLoop#getQueueSize
*/
public final class EventLoopStats {
- /**
- * Approximate number of commands actively being processed on
- * the event loop.
- */
+ /** Approximate number of commands actively being processed on the event loop. */
public final int processSize;
- /**
- * Approximate number of commands stored on this event loop's
- * delay queue that have not been started yet.
- */
+ /** Approximate number of commands on the event loop's delay queue not yet started. */
public final int queueSize;
/**
- * Event loop statistics constructor.
+ * Builds stats from the given event loop (values are snapshots at construction time).
+ * @param eventLoop event loop (must not be null)
*/
public EventLoopStats(EventLoop eventLoop) {
this.processSize = eventLoop.getProcessSize();
this.queueSize = eventLoop.getQueueSize();
}
- /**
- * Convert statistics to string.
- */
+ /** @return processSize and queueSize as a comma-separated string */
+ @Override
public String toString() {
return "" + processSize + ',' + queueSize;
}
diff --git a/client/src/com/aerospike/client/async/EventLoopType.java b/client/src/com/aerospike/client/async/EventLoopType.java
index f2073b7e4..ae4fdf63a 100644
--- a/client/src/com/aerospike/client/async/EventLoopType.java
+++ b/client/src/com/aerospike/client/async/EventLoopType.java
@@ -17,31 +17,25 @@
package com.aerospike.client.async;
/**
- * Type of async event loop used.
+ * Type of async event loop implementation (Netty or direct NIO).
+ *
+ * Used when constructing {@link NettyEventLoops} with an explicit type; otherwise the type is inferred from the Netty {@link io.netty.channel.EventLoopGroup}.
+ *
+ * @see NettyEventLoops
*/
public enum EventLoopType {
- /**
- * Direct NIO
- */
+ /** Direct NIO (used by {@link NioEventLoops}). */
DIRECT_NIO,
- /**
- * Netty NIO
- */
+ /** Netty NIO. */
NETTY_NIO,
- /**
- * Netty epoll. Available on Linux.
- */
+ /** Netty epoll; available on Linux. */
NETTY_EPOLL,
- /**
- * Netty kqueue. Available on MacOS, FreeBSD.
- */
+ /** Netty kqueue; available on MacOS, FreeBSD. */
NETTY_KQUEUE,
- /**
- * Netty io_uring. Available on Linux.
- */
+ /** Netty io_uring; available on Linux. */
NETTY_IOURING
}
diff --git a/client/src/com/aerospike/client/async/EventLoops.java b/client/src/com/aerospike/client/async/EventLoops.java
index a2741122c..18d71790a 100644
--- a/client/src/com/aerospike/client/async/EventLoops.java
+++ b/client/src/com/aerospike/client/async/EventLoops.java
@@ -19,34 +19,41 @@
import java.io.Closeable;
/**
- * Aerospike event loops interface.
+ * Group of event loops used for asynchronous Aerospike operations.
+ *
+ * Set on {@link com.aerospike.client.policy.ClientPolicy#eventLoops} when constructing the client, or obtain from {@link com.aerospike.client.AerospikeClient#getEventLoops()}. Use {@link #next()} or {@link #get(int)} to get an event loop for async API calls.
+ *
+ * Pass to {@link NioEventLoops} or {@link NettyEventLoops} constructors. Defaults are suitable for most cases; tune when limiting concurrent commands or memory.
+ *
+ * Use when the application already uses Netty; create from your {@link io.netty.channel.EventLoopGroup} and set on {@link com.aerospike.client.policy.ClientPolicy#eventLoops}.
+ *
+ * Optionally set on {@link com.aerospike.client.policy.TlsPolicy#nettyContext} to share one TLS context across multiple {@link com.aerospike.client.AerospikeClient} instances that use Netty.
+ *
+ * Create and set on {@link com.aerospike.client.policy.ClientPolicy#eventLoops} before constructing the client. Use one event loop per CPU core by default, or pass an explicit size.
+ *
+ * An array of CTX identifies location of the list/map on multiple levels on nesting.
+ * Build nested path with CTX for operate and index creation.
+ * Use with {@link com.aerospike.client.AerospikeClient#operate} to select values or apply expressions inside nested CDTs. Build context with {@link CTX#mapKey}, {@link CTX#listIndex}, {@link CTX#allChildren}, {@link CTX#allChildrenWithFilter}, etc.
+ * Select and modify nested CDT values by path with CTX.
- * List operations support negative indexing. If the index is negative, the
- * resolved index starts backwards from end of list. If an index is out of bounds,
- * a parameter error will be returned. If a range is partially out of bounds, the
- * valid part of the range will be returned. Index/Range examples:
+ * Index (item offset from start; negative = from end):
*
- * Nested CDT operations are supported by optional CTX context arguments. Examples:
- * Append, pop, size, appendItems, getRange; get by index/range; nested append with CTX.
+ * Use {@link #ORDERED} when you need rank/getByRank; default is {@link #UNORDERED}.
+ *
+ * @see ListPolicy
+ * @see ListOperation
*/
public enum ListOrder {
/**
diff --git a/client/src/com/aerospike/client/cdt/ListPolicy.java b/client/src/com/aerospike/client/cdt/ListPolicy.java
index d98f68660..53fc40350 100644
--- a/client/src/com/aerospike/client/cdt/ListPolicy.java
+++ b/client/src/com/aerospike/client/cdt/ListPolicy.java
@@ -17,12 +17,24 @@
package com.aerospike.client.cdt;
/**
- * List policy directives when creating a list and writing list items.
+ * List policy: order and write flags when creating a list or writing list items.
+ *
+ * Use with {@link ListOperation#create}, {@link ListOperation#append}, {@link ListOperation#appendItems}, {@link ListOperation#increment}, etc. when the list may not exist or when you need ordered/unique semantics.
+ * Use list policy with appendItems and increment.
+ * Pass to {@link ListOperation#get}, {@link ListOperation#getByIndex}, {@link ListOperation#getByRank}, {@link ListOperation#getRange}, {@link ListOperation#removeByValue}, and similar.
+ * Use ListReturnType in getByIndex and getByValue.
+ * Combine list write flags and pass to ListPolicy.
- * The server will validate map key types in an upcoming release.
- *
- * All maps maintain an index and a rank. The index is the item offset from the start of the map,
- * for both unordered and ordered maps. The rank is the sorted index of the value component.
- * Map supports negative indexing for index and rank.
+ * Map bin operations for the client operate command. Default unique-key map is unordered. Valid
+ * map key types: String, Integer, byte[] (server will validate in an upcoming release). Maps have
+ * index (item offset) and rank (sorted index of value component); both support negative indexing.
+ * Use optional {@link CTX} for nested CDT paths.
*
- * Index examples:
+ * Index (item offset from start; negative = from end):
*
- * Rank examples:
+ * Rank (sorted index of value; negative = from highest):
*
- * Nested CDT operations are supported by optional CTX context arguments. Examples:
- * Put, getByKey, size, putItems; get by index/rank; nested put with CTX.
+ * Use {@link #KEY_ORDERED} or {@link #KEY_VALUE_ORDERED} for rank/getByRank; default is {@link #UNORDERED}.
+ *
+ * @see MapPolicy
+ * @see MapOperation
*/
public enum MapOrder {
/**
diff --git a/client/src/com/aerospike/client/cdt/MapPolicy.java b/client/src/com/aerospike/client/cdt/MapPolicy.java
index 5ae4dcce4..b96410289 100644
--- a/client/src/com/aerospike/client/cdt/MapPolicy.java
+++ b/client/src/com/aerospike/client/cdt/MapPolicy.java
@@ -17,12 +17,25 @@
package com.aerospike.client.cdt;
/**
- * Map policy directives when creating a map and writing map items.
+ * Map policy: order and write flags when creating a map or writing map items.
+ *
+ * Use with {@link MapOperation#put}, {@link MapOperation#putItems}, {@link MapOperation#replace}, etc. when the map may not exist or when you need key-ordered or update semantics.
+ * Use MapPolicy with put and putItems.
+ * Pass to {@link MapOperation#getByKey}, {@link MapOperation#getByIndex}, {@link MapOperation#getByRank}, {@link MapOperation#removeByKey}, and similar.
+ * Use MapReturnType in getByKey and getByRank.
+ * Combine map write flags and pass to MapPolicy.
+ * The client and policy constructors that take a ConfigurationProvider use it to populate policy fields from the fetched {@link Configuration}. Implement this interface to provide config from a custom source.
+ *
* The bin expression argument in these methods can be a reference to a bin or the
* result of another expression. Expressions that modify bin values are only used
@@ -33,6 +33,21 @@
* Offset orientation is left-to-right. Negative offsets are supported.
* If the offset is negative, the offset starts backwards from end of the bitmap.
* If an offset is out of bounds, a parameter error will be returned.
+ * Filter or read by bit count and resize expression. Example for this expression. Example for this expression. Example for this expression. Example for this expression. Example for this expression. Example for this expression. Example for this expression. Example for this expression. Example for this expression.
+ * Use with {@link Exp#build(Exp)} in {@link com.aerospike.client.policy.Policy#filterExp} or inside other expressions. Complements {@link com.aerospike.client.cdt.CdtOperation} (operate-only) with expression form for filtering.
+ * Filter by nested path with CdtExp.selectByPath.
+ * Build expressions with {@link #build(Exp)} then use on {@link com.aerospike.client.policy.WritePolicy#filterExp}, {@link com.aerospike.client.policy.Policy#filterExp}, {@link com.aerospike.client.query.Statement#setFilter}, or {@link com.aerospike.client.exp.ExpOperation#read} / {@link ExpOperation#write}. Use {@link ListExp}, {@link MapExp}, and {@link CdtExp} for CDT bin expressions.
+ * Use filter expressions on put, get, and ExpOperation.read. Example for this expression. Example for this expression. Example for this expression. Example for this expression. Example for this expression. Example for this expression. Example for this expression.
+ * Use with {@link com.aerospike.client.AerospikeClient#operate}. Read stores the expression result in a bin-name variable; write stores the result in the given bin.
+ * Write and read expression results with operate.
+ * Use with {@link ExpOperation#read}. {@link #EVAL_NO_FAIL} returns the record without the expression result instead of failing.
+ * Use ExpReadFlags with ExpOperation.read.
+ * Combine ExpWriteFlags and pass to ExpOperation.write.
+ * Create with {@link Exp#build(Exp)}. Use {@link #getBytes()} or {@link #fromBytes(byte[])} / {@link #fromBase64(String)} for serialization.
+ * Build expression for filter and ExpOperation.read.
* The bin expression argument in these methods can be a reference to a bin or the
* result of another expression. Expressions that modify bin values are only used
* for temporary expression evaluation and are not permanently applied to the bin.
* HLL modify expressions return the HLL bin's value.
+ * Below example illustrates filter by HLL count and read count with ExpOperation. Example for this expression. Example for this expression. Example for this expression. Example for this expression. Example for this expression. Example for this expression. Example for this expression. Example for this expression. Example for this expression. Example for this expression.
- * The bin expression argument in these methods can be a reference to a bin or the
- * result of another expression. Expressions that modify bin values are only used
- * for temporary expression evaluation and are not permanently applied to the bin.
+ * The bin argument can be a bin reference or an expression that returns a list. List modify
+ * expressions return the bin's value (a list, or a map when the list is nested in a map). Negative
+ * indexing is supported; index out of bounds returns a parameter error; a range partially out of
+ * bounds returns the valid part. Use optional {@link com.aerospike.client.cdt.CTX} for nested
+ * lists/maps.
*
- * List modify expressions return the bin's value. This value will be a list except
- * when the list is nested within a map. In that case, a map is returned for the
- * list modify expression.
- *
- * List expressions support negative indexing. If the index is negative, the
- * resolved index starts backwards from end of list. If an index is out of bounds,
- * a parameter error will be returned. If a range is partially out of bounds, the
- * valid part of the range will be returned. Index/Range examples:
- *
- * Nested expressions are supported by optional CTX context arguments. Example:
+ * Index (item offset; negative = from end):
* Filter by list size, read by index/range, and nested CTX (e.g. size of last list). Example for this expression. Example for this expression. Example for this expression. Example for this expression. Example for this expression.
+ * Use with {@link Exp#mapLoopVar}, {@link Exp#stringLoopVar}, {@link Exp#intLoopVar}, {@link Exp#floatLoopVar} when building filter/apply expressions over map or list elements.
+ * Filter nested children by loop variable key or value.
- * The bin expression argument in these methods can be a reference to a bin or the
- * result of another expression. Expressions that modify bin values are only used
- * for temporary expression evaluation and are not permanently applied to the bin.
+ * The bin argument can be a bin reference or an expression that returns a map. Map modify
+ * expressions return the bin's value (a map, or a list when the map is nested in a list). Valid
+ * map key types: String, Integer, byte[]. Maps support index (item offset) and rank (sorted value
+ * index), including negative indexing; use optional {@link com.aerospike.client.cdt.CTX} for
+ * nested maps/lists. For loop variables in filters use {@link Exp#mapLoopVar}, {@link Exp#stringLoopVar}
+ * with {@link LoopVarPart}.
*
- * Map modify expressions return the bin's value. This value will be a map except
- * when the map is nested within a list. In that case, a list is returned for the
- * map modify expression.
- *
- * Valid map key types are:
+ * Index (item offset from start; negative = from end):
*
- * The server will validate map key types in an upcoming release.
- *
- * All maps maintain an index and a rank. The index is the item offset from the start of the map,
- * for both unordered and ordered maps. The rank is the sorted index of the value component.
- * Map supports negative indexing for index and rank.
- *
- * Index examples:
+ * Rank (sorted index of value; negative = from highest):
*
- * Rank examples:
- *
- * Nested expressions are supported by optional CTX context arguments. Example:
- * Filter by map, read with index/rank and nested CTX, and use a loop variable. Example for this expression. Example for this expression. Example for this expression. Example for this expression.
+ * Pass to {@link com.aerospike.client.IAerospikeClient#abort(com.aerospike.client.async.EventLoop, AbortListener, com.aerospike.client.Txn)}. Abort does not report failure via a separate callback.
+ *
+ * Pass to {@link com.aerospike.client.IAerospikeClient#get} is null when the key is not found.
+ *
+ * Pass to {@link com.aerospike.client.IAerospikeClient#operate(com.aerospike.client.async.EventLoop, BatchOperateListListener, com.aerospike.client.policy.BatchPolicy, java.util.List)}. Each record's result is in {@link com.aerospike.client.BatchRecord#record} (null on error).
+ *
+ * Pass to {@link com.aerospike.client.IAerospikeClient#operate(com.aerospike.client.async.EventLoop, BatchRecordArrayListener, com.aerospike.client.policy.BatchPolicy, com.aerospike.client.BatchRecord[])}. Records are in same order as input; check each {@link com.aerospike.client.BatchRecord#resultCode}.
+ *
+ * Pass to {@link com.aerospike.client.IAerospikeClient#operate}. Order of onRecord is not guaranteed.
+ *
+ * Pass to {@link com.aerospike.client.IAerospikeClient#get}. Order of onRecord is not guaranteed; {@link com.aerospike.client.BatchRead#record} is null when key is not found.
+ *
+ * Pass to {@link com.aerospike.client.IAerospikeClient#getClusterStats}.
+ *
+ * Pass to {@link com.aerospike.client.IAerospikeClient#commit}
+ *
+ * Pass to {@link com.aerospike.client.IAerospikeClient#delete}
+ *
+ * Pass to {@link com.aerospike.client.IAerospikeClient#execute}
+ *
+ * Pass to {@link com.aerospike.client.IAerospikeClient#exists(com.aerospike.client.async.EventLoop, ExistsArrayListener, com.aerospike.client.policy.BatchPolicy, com.aerospike.client.Key[])}.
+ *
+ * Pass to {@link com.aerospike.client.IAerospikeClient#exists} or untouched
+ *
+ * Pass to {@link com.aerospike.client.IAerospikeClient#exists}. Order of onExists is not guaranteed.
+ *
+ * Pass to {@link com.aerospike.client.IAerospikeClient#createIndex} and dropIndex overloads. Use the task in onSuccess to call {@link com.aerospike.client.async.AsyncIndexTask#queryStatus} for completion.
+ *
+ * Pass to {@link com.aerospike.client.IAerospikeClient#info}
+ *
+ * Pass to {@link com.aerospike.client.IAerospikeClient#get}. Records align by index with keys; null record means key not found.
+ *
+ * Pass to {@link com.aerospike.client.IAerospikeClient#get} or operate overloads. Called once per key with the record (or null if not found) or with an exception.
+ *
+ * Pass to {@link com.aerospike.client.AerospikeClient#query} or {@link com.aerospike.client.AerospikeClient#get} async overloads. For scan/query, throw {@link com.aerospike.client.AerospikeException.QueryTerminated} or {@link com.aerospike.client.AerospikeException.ScanTerminated} to abort; the exception is reported in {@link #onFailure}.
+ *
+ *
- * If this listener is used in a scan/query command, The user may throw a
- * {@link com.aerospike.client.AerospikeException.QueryTerminated AerospikeException.QueryTerminated}
- * exception if the command should be aborted. If any exception is thrown, parallel command threads
- * to other nodes will also be terminated and the exception will be propagated back through the
- * onFailure() call.
- *
- * If this listener is used in a batch command, an user thrown exception will terminate the batch
- * to the current node, but parallel batch command threads to other nodes will continue to run.
+ * Called when an asynchronous record is received; order is not guaranteed. For scan/query, throw QueryTerminated or ScanTerminated to abort (reported in onFailure). For batch, a thrown exception stops only the current node.
*
- * @param key unique record identifier
- * @param record record instance, will be null if the key is not found
- * @throws AerospikeException if error occurs or scan should be terminated.
+ * @param key unique record identifier; never null
+ * @param record record instance; null if the key is not found
+ * @throws AerospikeException when an error occurs or the scan/query should be terminated (e.g. throw ScanTerminated or QueryTerminated to abort).
*/
public void onRecord(Key key, Record record) throws AerospikeException;
- /**
- * This method is called when the asynchronous batch get or scan command completes.
- */
+ /** Called when the asynchronous batch get or scan/query completes successfully. */
public void onSuccess();
- /**
- * This method is called when an asynchronous batch get or scan command fails.
- */
+ /** Called when the asynchronous batch get or scan/query fails; receives the exception. */
public void onFailure(AerospikeException ae);
}
diff --git a/client/src/com/aerospike/client/listener/TaskStatusListener.java b/client/src/com/aerospike/client/listener/TaskStatusListener.java
index f3aed9ac1..bcd12f765 100644
--- a/client/src/com/aerospike/client/listener/TaskStatusListener.java
+++ b/client/src/com/aerospike/client/listener/TaskStatusListener.java
@@ -19,18 +19,32 @@
import com.aerospike.client.AerospikeException;
/**
- * Asynchronous result notifications for index status command.
+ * Async callback for index task status (e.g. from {@link com.aerospike.client.async.AsyncIndexTask#queryStatus}); receives load percentage or exception.
+ *
+ * Pass to {@link com.aerospike.client.async.AsyncIndexTask#queryStatus}. Status 100 means complete; see {@link com.aerospike.client.task.Task}.
+ *
+ * Pass to {@link com.aerospike.client.IAerospikeClient#put} and other write overloads.
+ *
- * Bit operations on bitmap items nested in lists/maps are not currently
- * supported by the server.
+ * Use with {@link com.aerospike.client.AerospikeClient#operate}. Nested bitmaps in list/map bins are not supported by the server. For expression-based bit ops in filters, see {@link com.aerospike.client.exp.BitExp}.
+ * Resize a bit bin and read bytes with operate.
+ * Pass to {@link BitOperation#add}, {@link BitOperation#subtract}, {@link BitOperation#setInt}, {@link BitOperation#getInt}.
+ *
+ * @see BitOperation
*/
public enum BitOverflowAction {
/**
diff --git a/client/src/com/aerospike/client/operation/BitPolicy.java b/client/src/com/aerospike/client/operation/BitPolicy.java
index 13f3d67a4..e89a32753 100644
--- a/client/src/com/aerospike/client/operation/BitPolicy.java
+++ b/client/src/com/aerospike/client/operation/BitPolicy.java
@@ -17,12 +17,24 @@
package com.aerospike.client.operation;
/**
- * Bit operation policy.
+ * Policy for bit (byte[]) operations; holds {@link BitWriteFlags} used by {@link BitOperation}.
+ *
+ * Pass to {@link BitOperation#resize}, {@link BitOperation#insert}, {@link BitOperation#set}, and other BitOperation methods.
+ * Use BitPolicy with resize and set.
+ * Combine with BITWISE OR when needed. Pass to {@link BitOperation#resize(BitPolicy, String, int, int)}.
+ *
+ * @see BitOperation#resize
*/
public final class BitResizeFlags {
/**
diff --git a/client/src/com/aerospike/client/operation/BitWriteFlags.java b/client/src/com/aerospike/client/operation/BitWriteFlags.java
index 6b8e90810..1cf6777ec 100644
--- a/client/src/com/aerospike/client/operation/BitWriteFlags.java
+++ b/client/src/com/aerospike/client/operation/BitWriteFlags.java
@@ -17,11 +17,17 @@
package com.aerospike.client.operation;
/**
- * Bitwise operation policy write bit flags. Use BITWISE OR to combine flags. Example:
- *
- *
+ * Combine bit write flags and pass to BitPolicy.
- * HyperLogLog operations on HLL items nested in lists/maps are not currently
- * supported by the server.
+ * Use with {@link com.aerospike.client.AerospikeClient#operate}. HLL bins nested in list/map are not supported by the server. For expression-based HLL in filters, see {@link com.aerospike.client.exp.HLLExp}.
+ * Init and add to an HLL bin then count.
+ * Pass to {@link HLLOperation#init}, {@link HLLOperation#add}, and other HLLOperation methods.
+ * Use HLLPolicy with init and add.
+ * Combine HLL write flags and pass to HLLPolicy.
+ * Pass to {@link com.aerospike.client.AerospikeClient#createUser}, {@link com.aerospike.client.AerospikeClient#createRole}, and other admin methods. Default timeout 0 (no timeout).
+ *
+ * Example:
+ * Create a user with a 5-second timeout for the admin command.
+ * Pass to {@link com.aerospike.client.AerospikeClient#delete(BatchPolicy, BatchDeletePolicy, Key[])}. Omit or use null for defaults.
+ *
+ * Example:
+ * Use master-only commit for batch delete to reduce latency.
+ * Pass to {@link com.aerospike.client.AerospikeClient#get}, {@link com.aerospike.client.AerospikeClient#operate}, {@link com.aerospike.client.AerospikeClient#delete} batch overloads. Extends {@link Policy}.
+ *
+ * Example:
+ * Allow inline batch processing and set a 2-second total timeout for batch get.
+ * Pass to batch get overloads when using key-specific policies; otherwise batch uses {@link BatchPolicy} and default read behavior.
+ *
+ * Example:
+ * Use availability read mode ONE for batch reads when passing key-specific policies (e.g. in BatchRecord).
+ * Pass to batch execute overloads. Omit or use null for defaults.
+ *
+ * Example:
+ * Run batch UDF execute with commit-all consistency so all replicas commit before returning.
+ * Pass to batch operate or batch write overloads alongside {@link BatchPolicy}. Extends write options per key when using key-specific policies.
+ *
+ * Example:
+ * Replace existing records and commit to master only for batch operate or batch write.
+ * Pass to {@link com.aerospike.client.AerospikeClient} constructors. Default policies (read, write, batch, etc.) are used when null is passed to operations.
+ *
+ * Example:
+ * Connect to the cluster with authentication and a 2-second tend timeout.
+ * Pass to {@link com.aerospike.client.Info#request} and related overloads, or use for cluster tend. Default timeout is 1000 ms.
+ *
+ * Example:
+ * Use a 2-second socket timeout for info requests to a node (e.g. to fetch "build").
+ * Subclasses define operation-specific options (e.g. {@link WritePolicy}, {@link QueryPolicy}). Set {@link #txn} for multi-record transactions.
+ *
+ * Example (expression filter):
+ * Apply an expression filter so only records where bin "a" equals 11 are read.
* Default: null
- *
- *
- * Inherited Policy fields {@link Policy#txn} and {@link Policy#failOnFilteredOut} are ignored
- * in query commands.
+ * Pass to {@link com.aerospike.client.AerospikeClient#query} and {@link com.aerospike.client.AerospikeClient#queryAggregate}. {@link Policy#txn} and {@link Policy#failOnFilteredOut} are ignored for query.
+ *
+ * Example:
+ * Run a short-duration query and include bin data in the returned records.
- * How duplicates should be consulted in a read operation.
- * Only makes a difference during migrations and only applicable in AP mode.
+ * Read policy for AP (availability) namespaces; how many duplicates to consult (ONE or ALL). Only applies during migrations in AP mode.
+ *
+ * @see Policy#readModeAP
+ * @see BatchReadPolicy#readModeAP
*/
public enum ReadModeAP {
/**
diff --git a/client/src/com/aerospike/client/policy/ReadModeSC.java b/client/src/com/aerospike/client/policy/ReadModeSC.java
index eed429b13..d07df2788 100644
--- a/client/src/com/aerospike/client/policy/ReadModeSC.java
+++ b/client/src/com/aerospike/client/policy/ReadModeSC.java
@@ -17,9 +17,10 @@
package com.aerospike.client.policy;
/**
- * Read policy for SC (strong consistency) namespaces.
- *
- * Determines SC read consistency options.
+ * Read policy for SC (strong consistency) namespaces; session, linearize, or allow-unavailable.
+ *
+ * @see Policy#readModeSC
+ * @see BatchReadPolicy#readModeSC
*/
public enum ReadModeSC {
/**
diff --git a/client/src/com/aerospike/client/policy/RecordExistsAction.java b/client/src/com/aerospike/client/policy/RecordExistsAction.java
index 818488fd8..67f8380a3 100644
--- a/client/src/com/aerospike/client/policy/RecordExistsAction.java
+++ b/client/src/com/aerospike/client/policy/RecordExistsAction.java
@@ -17,7 +17,10 @@
package com.aerospike.client.policy;
/**
- * How to handle writes when the record already exists.
+ * How to handle writes when the record already exists (update, replace, create-only, etc.).
+ *
+ * @see WritePolicy#recordExistsAction
+ * @see BatchWritePolicy#recordExistsAction
*/
public enum RecordExistsAction {
/**
diff --git a/client/src/com/aerospike/client/policy/Replica.java b/client/src/com/aerospike/client/policy/Replica.java
index 655f18b9d..d1335a715 100644
--- a/client/src/com/aerospike/client/policy/Replica.java
+++ b/client/src/com/aerospike/client/policy/Replica.java
@@ -17,7 +17,9 @@
package com.aerospike.client.policy;
/**
- * Defines algorithm used to determine the target node for a command.
+ * Algorithm used to determine the target node for a partition (master, replica, rack-aware, etc.).
+ *
+ * @see Policy#replica
*/
public enum Replica {
/**
diff --git a/client/src/com/aerospike/client/policy/ScanPolicy.java b/client/src/com/aerospike/client/policy/ScanPolicy.java
index 0ff0eec7f..4a27015f0 100644
--- a/client/src/com/aerospike/client/policy/ScanPolicy.java
+++ b/client/src/com/aerospike/client/policy/ScanPolicy.java
@@ -23,15 +23,24 @@
import com.aerospike.client.configuration.serializers.dynamicconfig.DynamicScanConfig;
/**
- * Container object for optional parameters used in scan operations.
+ * Policy for scan operations (max records, records per second, concurrent nodes, include bin data).
*
- * Inherited Policy fields {@link Policy#txn} and {@link Policy#failOnFilteredOut} are ignored in
- * scan commands.
+ * {@link Policy#txn} and {@link Policy#failOnFilteredOut} are ignored for scan.
*
- * @deprecated Scan operation related policies have been deprecated and will be removed eventually.
- * Use {@link QueryPolicy} with {@link com.aerospike.client.AerospikeClient#query(com.aerospike.client.policy.QueryPolicy, com.aerospike.client.query.Statement, com.aerospike.client.query.QueryListener)}
- * or {@link com.aerospike.client.AerospikeClient#queryPartitions(com.aerospike.client.policy.QueryPolicy, com.aerospike.client.query.Statement, com.aerospike.client.query.PartitionFilter)}
- * instead (use statement with namespace and set name, no filter). Example:
+ * Run a scan with a record limit and include bin data (prefer {@link QueryPolicy} with query for new code). Example:
+ * Enable TCP keep-alive with custom idle/interval/probes when using Netty epoll (set on {@link ClientPolicy#keepAlive}).
+ * Set on {@link ClientPolicy#tlsPolicy}. Optionally provide {@link #context} (SSLContext) or {@link #nettyContext} (NettyTlsContext) for shared TLS state across clients.
+ *
+ * Example:
+ * Connect over TLS using TLSv1.2 by attaching TlsPolicy to ClientPolicy.
+ * Used internally when {@link com.aerospike.client.AerospikeClient#commit} or {@link com.aerospike.client.AerospikeClient#abort} applies write results. Can be set on {@link ClientPolicy#txnRollPolicyDefault}.
+ *
+ * Example:
+ * Set a custom transaction roll policy as the client default for commit/abort phase.
+ * Used internally when {@link com.aerospike.client.AerospikeClient#commit} verifies read keys. Can be set on {@link ClientPolicy#txnVerifyPolicyDefault}.
+ *
+ * Example:
+ * Set a custom transaction verify policy as the client default for the commit verify phase.
+ * Pass to put, append, prepend, add, delete, touch, operate, and execute. Extends {@link Policy} for timeouts and retries.
+ *
+ * Example:
+ * Replace existing records and set record TTL to one hour (3600 seconds).
+ * Use {@link #equal(String, long, CTX...)}, {@link #equal(String, String, CTX...)}, {@link #range}, or other static methods; pass to {@link Statement#setFilter}. Use optional {@link com.aerospike.client.cdt.CTX} for CDT/list/map context (e.g. {@link #range(String, long, long, CTX...)}).
+ * Set Filter.equal on a statement and run query.
+ * Pass to {@link com.aerospike.client.AerospikeClient#createIndex} for list/map bins; use the same value in {@link Filter#range} or {@link Filter#equal} for CDT context.
+ *
+ * @see IndexType
+ * @see Filter
+ * @see com.aerospike.client.AerospikeClient#createIndex
*/
public enum IndexCollectionType {
/**
diff --git a/client/src/com/aerospike/client/query/IndexType.java b/client/src/com/aerospike/client/query/IndexType.java
index 5cfb445c4..f28e74059 100644
--- a/client/src/com/aerospike/client/query/IndexType.java
+++ b/client/src/com/aerospike/client/query/IndexType.java
@@ -17,7 +17,13 @@
package com.aerospike.client.query;
/**
- * Underlying data type of secondary index.
+ * Data type of a secondary index; used when creating an index and must match the bin type and {@link Filter}.
+ *
+ * Pass to {@link com.aerospike.client.AerospikeClient#createIndex} and {@link com.aerospike.client.AerospikeClient#dropIndex}. Use with {@link IndexCollectionType} for list/map indexes.
+ *
+ * @see IndexCollectionType
+ * @see Filter
+ * @see com.aerospike.client.AerospikeClient#createIndex
*/
public enum IndexType {
/**
diff --git a/client/src/com/aerospike/client/query/KeyRecord.java b/client/src/com/aerospike/client/query/KeyRecord.java
index e1d401b37..d856a924e 100644
--- a/client/src/com/aerospike/client/query/KeyRecord.java
+++ b/client/src/com/aerospike/client/query/KeyRecord.java
@@ -22,7 +22,25 @@
import java.util.Objects;
/**
- * Container object for key identifier and record data.
+ * Key and record pair returned by query/scan iteration; obtained from {@link RecordSet#getKeyRecord()} after {@link RecordSet#next()}.
+ *
+ * In normal iteration {@link #key} is not null; {@link #record} is null when the key was not found. Also used as sentinel {@link RecordSet#END}.
+ * Iterate query results and get KeyRecord from RecordSet. Query a partition range with queryPartitions.
+ * Pass to {@link com.aerospike.client.AerospikeClient#query(com.aerospike.client.policy.QueryPolicy, Statement, QueryListener)} when processing records one-by-one instead of buffering a {@link RecordSet}. Throw {@link com.aerospike.client.AerospikeException.QueryTerminated} from {@link #onRecord} to abort.
+ * Query with a QueryListener to process each record in a callback.
- * The user may throw a
- * {@link com.aerospike.client.AerospikeException.QueryTerminated AerospikeException.QueryTerminated}
- * exception if the command should be aborted. If an exception is thrown, parallel query command
- * threads to other nodes will also be terminated.
- *
- * @param key unique record identifier
- * @param record record instance
- * @throws AerospikeException if error occurs or query should be terminated.
+ * Called when a record is received; order is not guaranteed. Throw {@link com.aerospike.client.AerospikeException.QueryTerminated} to abort.
+ * @param key record key (must not be null)
+ * @param record record if found, otherwise null
+ * @throws AerospikeException when the query should be terminated (e.g. throw QueryTerminated to abort)
*/
public void onRecord(Key key, Record record);
}
diff --git a/client/src/com/aerospike/client/query/RecordSet.java b/client/src/com/aerospike/client/query/RecordSet.java
index 11cc6a568..082aaf72d 100644
--- a/client/src/com/aerospike/client/query/RecordSet.java
+++ b/client/src/com/aerospike/client/query/RecordSet.java
@@ -26,11 +26,36 @@
import com.aerospike.client.Record;
/**
- * This class manages record retrieval from queries.
- * Multiple threads will retrieve records from the server nodes and put these records on the queue.
- * The single user thread consumes these records from the queue.
+ * Iterable set of key/record pairs from a query; call {@link #next()} then {@link #getKeyRecord()} (or iterate) and always {@link #close()} when done.
+ *
+ * Returned by {@link com.aerospike.client.AerospikeClient#query}. Use {@link #END} to detect end when iterating; {@link #next()} returns false when no more records. Close in a finally block to release resources.
+ * Run a query and iterate RecordSet with next() and getKeyRecord().
+ * Used in {@link com.aerospike.client.exp.Exp#regexCompare} and filter APIs that accept regex flags.
+ * Combine regex flags with bitwise OR.
+ * Returned by {@link com.aerospike.client.AerospikeClient#queryAggregate}. Use {@link #END} to detect end when iterating; {@link #next()} returns false when no more results. Close in a finally block to release resources.
+ * Run queryAggregate and iterate ResultSet with next() and getObject().{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * java.util.List<BatchRecord> records = java.util.Arrays.asList(new BatchRead(new Key("ns", "set", "k1")));
+ * client.operate(loop, new BatchOperateListListener() { ... }, null, records);
+ * }
* {@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * java.util.List<BatchRecord> records = java.util.Arrays.asList(new BatchRead(new Key("ns", "set", "k1")));
+ * client.operate(loop, new BatchRecordSequenceListener() { ... }, null, records);
+ * }
* {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Key[] keys = new Key[] { new Key("ns", "set", "k1"), new Key("ns", "set", "k2") };
+ * BatchResults results = client.operate(null, null, keys, Operation.get("bin1"));
+ * client.close();
+ * }
* {@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * Key[] keys = new Key[] { new Key("ns", "set", "k1"), new Key("ns", "set", "k2") };
+ * client.operate(loop, new BatchRecordArrayListener() { ... }, null, null, keys, Operation.get("bin1"));
+ * }
*
* @param eventLoop event loop that will process the command. If NULL, the event
* loop will be chosen by round-robin.
@@ -3433,11 +3835,10 @@ public final BatchResults operate(
* @param batchPolicy batch configuration parameters, pass in null for defaults
* @param writePolicy write configuration parameters, pass in null for defaults
* @param keys array of unique record identifiers
- * @param ops
- * read/write operations to perform. {@link Operation#get()} is not allowed because it returns a
- * variable number of bins and makes it difficult (sometimes impossible) to lineup operations
- * with results. Instead, use {@link Operation#get(String)} for each bin name.
- * @throws AerospikeException if event loop registration fails
+ * @param ops read/write operations (use Operation.get(String) per bin)
+ * @throws AerospikeException when event loop registration fails
+ * @see #operate(BatchPolicy, BatchWritePolicy, Key[], Operation...)
+ * @see BatchRecordArrayListener
*/
public final void operate(
EventLoop eventLoop,
@@ -3504,15 +3905,17 @@ public final void operate(
}
/**
- * Asynchronously perform read/write operations on multiple keys.
- * This method registers the command with an event loop and returns.
- * The event loop thread will process the command and send the results to the listener.
- * {@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * Key[] keys = new Key[] { new Key("ns", "set", "k1"), new Key("ns", "set", "k2") };
+ * client.operate(loop, new BatchRecordSequenceListener() { ... }, null, null, keys, Operation.get("bin1"));
+ * }
*
* @param eventLoop event loop that will process the command. If NULL, the event
* loop will be chosen by round-robin.
@@ -3520,11 +3923,10 @@ public final void operate(
* @param batchPolicy batch configuration parameters, pass in null for defaults
* @param writePolicy write configuration parameters, pass in null for defaults
* @param keys array of unique record identifiers
- * @param ops
- * read/write operations to perform. {@link Operation#get()} is not allowed because it returns a
- * variable number of bins and makes it difficult (sometimes impossible) to lineup operations
- * with results. Instead, use {@link Operation#get(String)} for each bin name.
- * @throws AerospikeException if event loop registration fails
+ * @param ops read/write operations (use Operation.get(String) per bin)
+ * @throws AerospikeException when event loop registration fails
+ * @see #operate(BatchPolicy, BatchWritePolicy, Key[], Operation...)
+ * @see BatchRecordSequenceListener
*/
public final void operate(
EventLoop eventLoop,
@@ -3783,16 +4185,23 @@ public final void scanPartitions(EventLoop eventLoop, RecordSequenceListener lis
//---------------------------------------------------------------
/**
- * Register package located in a file containing user defined functions with server.
- * This asynchronous server call will return before command is complete.
- * The user can optionally wait for command completion by using the returned
- * RegisterTask instance.
+ * Register a UDF package from a file with the server; returns a task to wait for completion.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * RegisterTask task = client.register(null, "myudf.lua", "myudf.lua", Language.LUA);
+ * task.waitTillComplete(1000);
+ * client.close();
+ * }
*
* @param policy generic configuration parameters, pass in null for defaults
* @param clientPath path of client file containing user defined functions, relative to current directory
- * @param serverPath path to store user defined functions on the server, relative to configured script directory.
+ * @param serverPath path to store user defined functions on the server, relative to configured script directory
* @param language language of user defined functions
- * @throws AerospikeException if register fails
+ * @return task to wait for completion
+ * @throws AerospikeException when register fails
+ * @see RegisterTask
+ * @see #execute(WritePolicy, Key, String, String, Value...)
*/
public final RegisterTask register(Policy policy, String clientPath, String serverPath, Language language)
throws AerospikeException {
@@ -3900,11 +4309,16 @@ public final void removeUdf(InfoPolicy policy, String serverPath)
}
/**
- * Execute user defined function on server and return results.
- * The function operates on a single record.
- * The package name is used to locate the udf file location:
+ * Execute a UDF on a single record and return the result.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Key key = new Key("ns", "set", "mykey");
+ * Object result = client.execute(null, key, "myudf", "myFunc", Value.get("arg1"));
+ * client.close();
+ * }
* {@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * client.execute(loop, executeListener, null, key, "myudf", "myFunc", Value.get("arg1"));
+ * }
*
* @param eventLoop event loop that will process the command. If NULL, the event
* loop will be chosen by round-robin.
@@ -3974,7 +4392,9 @@ public final Object execute(WritePolicy policy, Key key, String packageName, Str
* @param packageName server package name where user defined function resides
* @param functionName user defined function
* @param functionArgs arguments passed in to user defined function
- * @throws AerospikeException if event loop registration fails
+ * @throws AerospikeException when event loop registration fails
+ * @see #execute(WritePolicy, Key, String, String, Value...)
+ * @see ExecuteListener
*/
public final void execute(
EventLoop eventLoop,
@@ -4000,12 +4420,16 @@ public final void execute(
}
/**
- * Execute user defined function on server for each key and return results.
- * The package name is used to locate the udf file location:
- * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Key[] keys = new Key[] { new Key("ns", "set", "k1"), new Key("ns", "set", "k2") };
+ * BatchResults results = client.execute(null, null, keys, "myudf", "myFunc", Value.get("arg1"));
+ * client.close();
+ * }
* {@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * Key[] keys = new Key[] { new Key("ns", "set", "k1"), new Key("ns", "set", "k2") };
+ * client.execute(loop, new BatchRecordArrayListener() { ... }, null, null, keys, "myudf", "myFunc", Value.get("arg1"));
+ * }
* {@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * Key[] keys = new Key[] { new Key("ns", "set", "k1"), new Key("ns", "set", "k2") };
+ * client.execute(loop, new BatchRecordSequenceListener() { ... }, null, null, keys, "myudf", "myFunc", Value.get("arg1"));
+ * }
* {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Statement stmt = new Statement("ns", "set");
+ * ExecuteTask task = client.execute(null, stmt, "myudf", "myFunc", Value.get("arg1"));
+ * task.waitTillComplete(5000);
+ * client.close();
+ * }
*
* @param policy write configuration parameters, pass in null for defaults
* @param statement background query definition
* @param packageName server package where user defined function resides
* @param functionName function name
- * @param functionArgs to pass to function name, if any
- * @throws AerospikeException if command fails
+ * @param functionArgs arguments to pass to function, if any
+ * @return task to wait for completion
+ * @throws AerospikeException when command fails
+ * @see ExecuteTask
+ * @see #execute(WritePolicy, Statement, Operation...)
*/
public final ExecuteTask execute(
WritePolicy policy,
@@ -4293,16 +4738,23 @@ public final ExecuteTask execute(
}
/**
- * Apply operations on records that match the background query statement filter.
- * Records are not returned to the client.
- * This asynchronous server call will return before the command is complete.
- * The user can optionally wait for command completion by using the returned
- * ExecuteTask instance.
+ * Run operations in the background on all records matching the statement; returns a task to wait for completion.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Statement stmt = new Statement("ns", "set");
+ * ExecuteTask task = client.execute(null, stmt, Operation.put(new Bin("flag", 1)));
+ * task.waitTillComplete(5000);
+ * client.close();
+ * }
*
* @param policy write configuration parameters, pass in null for defaults
* @param statement background query definition
- * @param operations list of operations to be performed on selected records
- * @throws AerospikeException if command fails
+ * @param operations operations to perform on selected records
+ * @return task to wait for completion
+ * @throws AerospikeException when command fails
+ * @see ExecuteTask
+ * @see #execute(WritePolicy, Statement, String, String, Value...)
*/
public final ExecuteTask execute(
WritePolicy policy,
@@ -4338,20 +4790,25 @@ public final ExecuteTask execute(
//--------------------------------------------------------
/**
- * Execute query on all server nodes and return record iterator. The query executor puts
- * records on a queue in separate threads. The calling thread concurrently pops records off
- * the queue through the record iterator.
+ * Execute a query on all nodes and return a record iterator.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Statement stmt = new Statement("ns", "set");
+ * RecordSet rs = client.query(null, stmt);
+ * try { while (rs.next()) { Record r = rs.getRecord(); } } finally { rs.close(); }
+ * client.close();
+ * }
* {@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * Statement stmt = new Statement("ns", "set");
+ * client.query(loop, new RecordSequenceListener() { ... }, null, stmt);
+ * }
*
* @param eventLoop event loop that will process the command. If NULL, the event
* loop will be chosen by round-robin.
* @param listener where to send results
* @param policy query configuration parameters, pass in null for defaults
* @param statement query definition
- * @throws AerospikeException if event loop registration fails
+ * @throws AerospikeException when event loop registration fails
+ * @see #query(QueryPolicy, Statement)
+ * @see RecordSequenceListener
*/
public final void query(EventLoop eventLoop, RecordSequenceListener listener, QueryPolicy policy, Statement statement)
throws AerospikeException {
@@ -4413,19 +4878,24 @@ public final void query(EventLoop eventLoop, RecordSequenceListener listener, Qu
}
/**
- * Execute query on all server nodes and return records via the listener. This method will
- * block until the query is complete. Listener callbacks are made within the scope of this call.
- * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Statement stmt = new Statement("ns", "set");
+ * client.query(null, stmt, new QueryListener() { ... });
+ * client.close();
+ * }
* {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Statement stmt = new Statement("ns", "set");
+ * PartitionFilter filter = PartitionFilter.all();
+ * client.query(null, stmt, filter, new QueryListener() { ... });
+ * client.close();
+ * }
* {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Statement stmt = new Statement("ns", "set");
+ * Node node = client.getNodes()[0];
+ * RecordSet rs = client.queryNode(null, stmt, node);
+ * try { while (rs.next()) { Record r = rs.getRecord(); } } finally { rs.close(); }
+ * client.close();
+ * }
*
* @param policy query configuration parameters, pass in null for defaults
* @param statement query definition
* @param node server node to execute query
* @return record iterator
- * @throws AerospikeException if query fails
+ * @throws AerospikeException when query fails
+ * @see #query(QueryPolicy, Statement)
+ * @see #queryPartitions(QueryPolicy, Statement, PartitionFilter)
+ * @see RecordSet
+ * @see Node
*/
public final RecordSet queryNode(QueryPolicy policy, Statement statement, Node node)
throws AerospikeException {
@@ -4525,16 +5010,28 @@ public final RecordSet queryNode(QueryPolicy policy, Statement statement, Node n
}
/**
- * Execute query for specified partitions and return record iterator. The query executor puts
- * records on a queue in separate threads. The calling thread concurrently pops records off
- * the queue through the record iterator.
+ * Execute a query for specified partitions and return a record iterator.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Statement stmt = new Statement("ns", "set");
+ * PartitionFilter filter = PartitionFilter.all();
+ * RecordSet rs = client.queryPartitions(null, stmt, filter);
+ * try { while (rs.next()) { Record r = rs.getRecord(); } } finally { rs.close(); }
+ * client.close();
+ * }
* {@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * Statement stmt = new Statement("ns", "set");
+ * PartitionFilter filter = PartitionFilter.all();
+ * client.queryPartitions(loop, new RecordSequenceListener() { ... }, null, stmt, filter);
+ * }
* {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Statement stmt = new Statement("ns", "set");
+ * ResultSet rs = client.queryAggregate(null, stmt, "myudf", "sum_single_bin", Value.get("bin1"));
+ * try { while (rs.next()) { Object v = rs.getObject(); } } finally { rs.close(); }
+ * client.close();
+ * }
* {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Statement stmt = new Statement("ns", "set");
+ * stmt.setAggregateFunction("myudf", "sum_single_bin", Value.get("bin1"));
+ * ResultSet rs = client.queryAggregate(null, stmt);
+ * try { while (rs.next()) { Object v = rs.getObject(); } } finally { rs.close(); }
+ * client.close();
+ * }
* {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Statement stmt = new Statement("ns", "set");
+ * stmt.setAggregateFunction("myudf", "sum_single_bin", Value.get("bin1"));
+ * Node node = client.getNodes()[0];
+ * ResultSet rs = client.queryAggregateNode(null, stmt, node);
+ * try { while (rs.next()) { Object v = rs.getObject(); } } finally { rs.close(); }
+ * client.close();
+ * }
* {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * IndexTask task = client.createIndex(null, "ns", "set", "idx_bin1", "bin1", IndexType.STRING);
+ * task.waitTillComplete(1000);
+ * client.close();
+ * }
*
* @param policy generic configuration parameters, pass in null for defaults
* @param namespace namespace - equivalent to database name
@@ -4705,7 +5237,10 @@ public final ResultSet queryAggregateNode(QueryPolicy policy, Statement statemen
* @param indexName name of secondary index
* @param binName bin name that data is indexed on
* @param indexType underlying data type of secondary index
- * @throws AerospikeException if index create fails
+ * @return task to wait for completion
+ * @throws AerospikeException when index create fails
+ * @see IndexTask
+ * @see #dropIndex(Policy, String, String, String)
*/
public final IndexTask createIndex(
Policy policy,
@@ -4719,10 +5254,14 @@ public final IndexTask createIndex(
}
/**
- * Create complex secondary index to be used on bins containing collections.
- * This asynchronous server call will return before command is complete.
- * The user can optionally wait for command completion by using the returned
- * IndexTask instance.
+ * Create a complex (CDT) secondary index on a collection bin; returns a task to wait for completion.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * IndexTask task = client.createIndex(null, "ns", "set", "idx_list", "bin1", IndexType.STRING, IndexCollectionType.LIST);
+ * task.waitTillComplete(1000);
+ * client.close();
+ * }
*
* @param policy generic configuration parameters, pass in null for defaults
* @param namespace namespace - equivalent to database name
@@ -4732,7 +5271,11 @@ public final IndexTask createIndex(
* @param indexType underlying data type of secondary index
* @param indexCollectionType index collection type
* @param ctx optional context to index on elements within a CDT
- * @throws AerospikeException if index create fails
+ * @return task to wait for completion
+ * @throws AerospikeException when index create fails
+ * @see #createIndex(Policy, String, String, String, String, IndexType)
+ * @see IndexTask
+ * @see IndexCollectionType
*/
public final IndexTask createIndex(
Policy policy,
@@ -4765,9 +5308,16 @@ public final IndexTask createIndex(
}
/**
- * Asynchronously create complex secondary index to be used on bins containing collections.
- * This method registers the command with an event loop and returns.
- * The event loop thread will process the command and send the results to the listener.
+ * Asynchronously create a complex (CDT) secondary index on a collection bin.
+ * {@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * client.createIndex(loop, new IndexListener() { ... }, null, "ns", "set", "idx_list", "bin1", IndexType.STRING, IndexCollectionType.LIST);
+ * }
*
* @param eventLoop event loop that will process the command. If NULL, the event
* loop will be chosen by round-robin.
@@ -4780,7 +5330,9 @@ public final IndexTask createIndex(
* @param indexType underlying data type of secondary index
* @param indexCollectionType index collection type
* @param ctx optional context to index on elements within a CDT
- * @throws AerospikeException if index create fails
+ * @throws AerospikeException when index create fails
+ * @see #createIndex(Policy, String, String, String, String, IndexType, IndexCollectionType, CTX...)
+ * @see IndexListener
*/
public final void createIndex(
EventLoop eventLoop,
@@ -4809,10 +5361,15 @@ public final void createIndex(
}
/**
- * Create an expression-based secondary index with the provided index collection type
- * This asynchronous server call will return before command is complete.
- * The user can optionally wait for command completion by using the returned
- * IndexTask instance.
+ * Create an expression-based secondary index; returns a task to wait for completion.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Expression exp = com.aerospike.client.exp.Exp.build(com.aerospike.client.exp.Exp.eq(com.aerospike.client.exp.Exp.stringBin("bin1"), com.aerospike.client.exp.Exp.val(1)));
+ * IndexTask task = client.createIndex(null, "ns", "set", "idx_exp", IndexType.STRING, IndexCollectionType.DEFAULT, exp);
+ * task.waitTillComplete(1000);
+ * client.close();
+ * }
*
* @param policy generic configuration parameters, pass in null for defaults
* @param namespace namespace - equivalent to database name
@@ -4821,7 +5378,11 @@ public final void createIndex(
* @param indexType underlying data type of secondary index
* @param indexCollectionType index collection type
* @param exp expression on which to build the index
- * @throws AerospikeException
+ * @return task to wait for completion
+ * @throws AerospikeException when index create fails
+ * @see #createIndex(Policy, String, String, String, String, IndexType)
+ * @see Expression
+ * @see IndexTask
*/
public final IndexTask createIndex(
Policy policy,
@@ -4853,10 +5414,17 @@ public final IndexTask createIndex(
}
/**
- * Asynchronously create an expression-based secondary index with the provided index collection type
- * This asynchronous server call will return before command is complete.
- * The user can optionally wait for command completion by using the returned
- * IndexTask instance.
+ * Asynchronously create an expression-based secondary index.
+ * {@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * Expression exp = com.aerospike.client.exp.Exp.build(com.aerospike.client.exp.Exp.eq(com.aerospike.client.exp.Exp.stringBin("bin1"), com.aerospike.client.exp.Exp.val(1)));
+ * client.createIndex(loop, new IndexListener() { ... }, null, "ns", "set", "idx_exp", IndexType.STRING, IndexCollectionType.DEFAULT, exp);
+ * }
*
* @param policy generic configuration parameters, pass in null for defaults
* @param namespace namespace - equivalent to database name
@@ -4865,7 +5433,9 @@ public final IndexTask createIndex(
* @param indexType underlying data type of secondary index
* @param indexCollectionType index collection type
* @param exp expression on which to build the index
- * @throws AerospikeException
+ * @throws AerospikeException when index create fails
+ * @see #createIndex(Policy, String, String, String, IndexType, IndexCollectionType, Expression)
+ * @see IndexListener
*/
public final void createIndex(
EventLoop eventLoop,
@@ -4893,16 +5463,23 @@ public final void createIndex(
}
/**
- * Delete secondary index.
- * This asynchronous server call will return before command is complete.
- * The user can optionally wait for command completion by using the returned
- * IndexTask instance.
+ * Delete a secondary index; returns a task to wait for completion.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * IndexTask task = client.dropIndex(null, "ns", "set", "idx_bin1");
+ * task.waitTillComplete(1000);
+ * client.close();
+ * }
*
* @param policy generic configuration parameters, pass in null for defaults
* @param namespace namespace - equivalent to database name
* @param setName optional set name - equivalent to database table
* @param indexName name of secondary index
- * @throws AerospikeException if index drop fails
+ * @return task to wait for completion
+ * @throws AerospikeException when index drop fails
+ * @see #createIndex(Policy, String, String, String, String, IndexType)
+ * @see IndexTask
*/
public final IndexTask dropIndex(
Policy policy,
@@ -4930,9 +5507,16 @@ public final IndexTask dropIndex(
}
/**
- * Asynchronously delete secondary index.
- * This method registers the command with an event loop and returns.
- * The event loop thread will process the command and send the results to the listener.
+ * Asynchronously delete a secondary index.
+ * {@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * client.dropIndex(loop, new IndexListener() { ... }, null, "ns", "set", "idx_bin1");
+ * }
*
* @param eventLoop event loop that will process the command. If NULL, the event
* loop will be chosen by round-robin.
@@ -4941,7 +5525,9 @@ public final IndexTask dropIndex(
* @param namespace namespace - equivalent to database name
* @param setName optional set name - equivalent to database table
* @param indexName name of secondary index
- * @throws AerospikeException if index drop fails
+ * @throws AerospikeException when index drop fails
+ * @see #dropIndex(Policy, String, String, String)
+ * @see IndexListener
*/
public final void dropIndex(
EventLoop eventLoop,
@@ -4970,22 +5556,29 @@ public final void dropIndex(
//-----------------------------------------------------------------
/**
- * Asynchronously make info commands.
- * This method registers the command with an event loop and returns.
- * The event loop thread will process the command and send the results to the listener.
+ * Asynchronously send info command(s) to a node; results delivered to the listener.
+ * {@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * client.info(loop, new InfoListener() { ... }, null, null, "build", "statistics");
+ * }
* {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * // Filter: only replicate records where bin1 equals 1 (build expression via Exp, same as in filter policies)
+ * Expression filter = com.aerospike.client.exp.Exp.build(
+ * com.aerospike.client.exp.Exp.eq(com.aerospike.client.exp.Exp.intBin("bin1"), com.aerospike.client.exp.Exp.val(1)));
+ * client.setXDRFilter(null, "DC1", "ns", filter);
+ * // Remove filter for the datacenter/namespace:
+ * client.setXDRFilter(null, "DC1", "ns", null);
+ * client.close();
+ * }
*
* @param policy info configuration parameters, pass in null for defaults
* @param datacenter XDR datacenter name
* @param namespace namespace - equivalent to database name
- * @param filter expression filter
- * @throws AerospikeException if command fails
+ * @param filter expression filter, or null to remove
+ * @throws AerospikeException when command fails
+ * @see Expression
+ * @see com.aerospike.client.exp.Exp
*/
public final void setXDRFilter(
InfoPolicy policy,
@@ -5054,14 +5658,21 @@ public final void setXDRFilter(
//-------------------------------------------------------
/**
- * Create user with password and roles. Clear-text password will be hashed using bcrypt
- * before sending to server.
+ * Create a user with password and roles; password is hashed (bcrypt) before sending.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * client.createUser(null, "newuser", "password", java.util.Arrays.asList("read-write"));
+ * client.close();
+ * }
*
* @param policy admin configuration parameters, pass in null for defaults
* @param user user name
* @param password user password in clear-text format
- * @param roles variable arguments array of role names. Predefined roles are listed in {@link com.aerospike.client.admin.Role}
- * @throws AerospikeException if command fails
+ * @param roles list of role names; see {@link com.aerospike.client.admin.Role}
+ * @throws AerospikeException when command fails
+ * @see #dropUser(AdminPolicy, String)
+ * @see #queryUser(AdminPolicy, String)
*/
public final void createUser(AdminPolicy policy, String user, String password, List{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * client.createPkiUser(null, "pkiuser", java.util.Arrays.asList("read-write"));
+ * client.close();
+ * }
*
* @param policy admin configuration parameters, pass in null for defaults
* @param user user name
- * @param roles variable arguments array of role names. Predefined roles are listed in {@link com.aerospike.client.admin.Role}
- * @throws AerospikeException if command fails
+ * @param roles list of role names; see {@link com.aerospike.client.admin.Role}
+ * @throws AerospikeException when command fails
+ * @see #createUser(AdminPolicy, String, String, List)
+ * @see #dropUser(AdminPolicy, String)
*/
public final void createPkiUser(AdminPolicy policy, String user, List{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * client.dropUser(null, "olduser");
+ * client.close();
+ * }
*
* @param policy admin configuration parameters, pass in null for defaults
* @param user user name
- * @throws AerospikeException if command fails
+ * @throws AerospikeException when command fails
+ * @see #createUser(AdminPolicy, String, String, List)
+ * @see #queryUser(AdminPolicy, String)
*/
public final void dropUser(AdminPolicy policy, String user)
throws AerospikeException {
@@ -5099,12 +5725,19 @@ public final void dropUser(AdminPolicy policy, String user)
}
/**
- * Change user's password.
+ * Change a user's password (caller or another user if admin).
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * client.changePassword(null, "myuser", "newpassword");
+ * client.close();
+ * }
*
* @param policy admin configuration parameters, pass in null for defaults
* @param user user name
- * @param password user password in clear-text format
- * @throws AerospikeException if command fails
+ * @param password new password in clear-text format
+ * @throws AerospikeException when command fails
+ * @see #createUser(AdminPolicy, String, String, List)
*/
public final void changePassword(AdminPolicy policy, String user, String password)
throws AerospikeException {
@@ -5132,12 +5765,20 @@ public final void changePassword(AdminPolicy policy, String user, String passwor
}
/**
- * Add roles to user's list of roles.
+ * Add roles to a user's list of roles.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * client.grantRoles(null, "myuser", java.util.Arrays.asList("read-write", "user-admin"));
+ * client.close();
+ * }
*
* @param policy admin configuration parameters, pass in null for defaults
* @param user user name
- * @param roles role names. Predefined roles are listed in {@link com.aerospike.client.admin.Role}
- * @throws AerospikeException if command fails
+ * @param roles role names; see {@link com.aerospike.client.admin.Role}
+ * @throws AerospikeException when command fails
+ * @see #revokeRoles(AdminPolicy, String, List)
+ * @see #queryUser(AdminPolicy, String)
*/
public final void grantRoles(AdminPolicy policy, String user, List{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * client.revokeRoles(null, "myuser", java.util.Arrays.asList("user-admin"));
+ * client.close();
+ * }
*
* @param policy admin configuration parameters, pass in null for defaults
* @param user user name
- * @param roles role names. Predefined roles are listed in {@link com.aerospike.client.admin.Role}
- * @throws AerospikeException if command fails
+ * @param roles role names to remove; see {@link com.aerospike.client.admin.Role}
+ * @throws AerospikeException when command fails
+ * @see #grantRoles(AdminPolicy, String, List)
+ * @see #queryUser(AdminPolicy, String)
*/
public final void revokeRoles(AdminPolicy policy, String user, List{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Privilege p = new Privilege();
+ * p.code = PrivilegeCode.READ_WRITE;
+ * p.namespace = "ns";
+ * client.createRole(null, "myrole", java.util.Collections.singletonList(p));
+ * client.close();
+ * }
*
* @param policy admin configuration parameters, pass in null for defaults
* @param roleName role name
- * @param privileges privileges assigned to the role.
- * @throws AerospikeException if command fails
+ * @param privileges privileges assigned to the role
+ * @throws AerospikeException when command fails
+ * @see #dropRole(AdminPolicy, String)
+ * @see #queryRole(AdminPolicy, String)
+ * @see Privilege
*/
public final void createRole(AdminPolicy policy, String roleName, List{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Privilege p = new Privilege();
+ * p.code = PrivilegeCode.READ_WRITE;
+ * p.namespace = "ns";
+ * client.createRole(null, "myrole", java.util.Collections.singletonList(p), java.util.Arrays.asList("10.1.2.0/24"));
+ * client.close();
+ * }
*
* @param policy admin configuration parameters, pass in null for defaults
* @param roleName role name
- * @param privileges optional list of privileges assigned to role.
- * @param whitelist optional list of allowable IP addresses assigned to role.
- * IP addresses can contain wildcards (ie. 10.1.2.0/24).
- * @throws AerospikeException if command fails
+ * @param privileges optional list of privileges assigned to role
+ * @param whitelist optional list of allowable IP addresses (e.g. 10.1.2.0/24)
+ * @throws AerospikeException when command fails
+ * @see #createRole(AdminPolicy, String, List)
+ * @see #setWhitelist(AdminPolicy, String, List)
*/
public final void createRole(AdminPolicy policy, String roleName, List{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Privilege p = new Privilege();
+ * p.code = PrivilegeCode.READ_WRITE;
+ * p.namespace = "ns";
+ * client.createRole(null, "myrole", java.util.Collections.singletonList(p), java.util.Arrays.asList("10.1.2.0/24"), 1000, 500);
+ * client.close();
+ * }
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * client.dropRole(null, "myrole");
+ * client.close();
+ * }
*
* @param policy admin configuration parameters, pass in null for defaults
* @param roleName role name
- * @throws AerospikeException if command fails
+ * @throws AerospikeException when command fails
+ * @see #createRole(AdminPolicy, String, List)
+ * @see #queryRole(AdminPolicy, String)
*/
public final void dropRole(AdminPolicy policy, String roleName)
throws AerospikeException {
@@ -5228,12 +5918,24 @@ public final void dropRole(AdminPolicy policy, String roleName)
}
/**
- * Grant privileges to an user defined role.
+ * Grant privileges to a user-defined role.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Privilege p = new Privilege();
+ * p.code = PrivilegeCode.DATA_ADMIN;
+ * p.namespace = "ns";
+ * client.grantPrivileges(null, "myrole", java.util.Collections.singletonList(p));
+ * client.close();
+ * }
*
* @param policy admin configuration parameters, pass in null for defaults
* @param roleName role name
- * @param privileges privileges assigned to the role.
- * @throws AerospikeException if command fails
+ * @param privileges privileges to add to the role
+ * @throws AerospikeException when command fails
+ * @see #revokePrivileges(AdminPolicy, String, List)
+ * @see #queryRole(AdminPolicy, String)
+ * @see Privilege
*/
public final void grantPrivileges(AdminPolicy policy, String roleName, List{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Privilege p = new Privilege();
+ * p.code = PrivilegeCode.DATA_ADMIN;
+ * p.namespace = "ns";
+ * client.revokePrivileges(null, "myrole", java.util.Collections.singletonList(p));
+ * client.close();
+ * }
*
* @param policy admin configuration parameters, pass in null for defaults
* @param roleName role name
- * @param privileges privileges assigned to the role.
- * @throws AerospikeException if command fails
+ * @param privileges privileges to remove from the role
+ * @throws AerospikeException when command fails
+ * @see #grantPrivileges(AdminPolicy, String, List)
+ * @see #queryRole(AdminPolicy, String)
+ * @see Privilege
*/
public final void revokePrivileges(AdminPolicy policy, String roleName, List{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * client.setWhitelist(null, "myrole", java.util.Arrays.asList("10.1.2.0/24", "192.168.1.0/24"));
+ * client.close();
+ * }
*
* @param policy admin configuration parameters, pass in null for defaults
* @param roleName role name
- * @param whitelist list of allowable IP addresses or null.
- * IP addresses can contain wildcards (ie. 10.1.2.0/24).
- * @throws AerospikeException if command fails
+ * @param whitelist list of allowable IP addresses (e.g. 10.1.2.0/24), or null to remove
+ * @throws AerospikeException when command fails
+ * @see #createRole(AdminPolicy, String, List, List)
+ * @see #queryRole(AdminPolicy, String)
*/
public final void setWhitelist(AdminPolicy policy, String roleName, List{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * client.setQuotas(null, "myrole", 1000, 500);
+ * client.close();
+ * }
*
* @param policy admin configuration parameters, pass in null for defaults
* @param roleName role name
- * @param readQuota maximum reads per second limit, pass in zero for no limit.
- * @param writeQuota maximum writes per second limit, pass in zero for no limit.
- * @throws AerospikeException if command fails
+ * @param readQuota maximum reads per second, or zero for no limit
+ * @param writeQuota maximum writes per second, or zero for no limit
+ * @throws AerospikeException when command fails
+ * @see #createRole(AdminPolicy, String, List, List, int, int)
+ * @see #queryRole(AdminPolicy, String)
*/
public final void setQuotas(AdminPolicy policy, String roleName, int readQuota, int writeQuota)
throws AerospikeException {
@@ -5287,11 +6015,21 @@ public final void setQuotas(AdminPolicy policy, String roleName, int readQuota,
}
/**
- * Retrieve roles for a given user.
+ * Retrieve a single user and their roles.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * User u = client.queryUser(null, "myuser");
+ * client.close();
+ * }
*
* @param policy admin configuration parameters, pass in null for defaults
- * @param user user name filter
- * @throws AerospikeException if command fails
+ * @param user user name
+ * @return user with roles, or null if not found
+ * @throws AerospikeException when command fails
+ * @see #queryUsers(AdminPolicy)
+ * @see #createUser(AdminPolicy, String, String, List)
+ * @see User
*/
public final User queryUser(AdminPolicy policy, String user)
throws AerospikeException {
@@ -5301,9 +6039,18 @@ public final User queryUser(AdminPolicy policy, String user)
/**
* Retrieve all users and their roles.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * java.util.List<User> users = client.queryUsers(null);
+ * client.close();
+ * }
*
* @param policy admin configuration parameters, pass in null for defaults
- * @throws AerospikeException if command fails
+ * @return list of users with roles
+ * @throws AerospikeException when command fails
+ * @see #queryUser(AdminPolicy, String)
+ * @see User
*/
public final List{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Role r = client.queryRole(null, "myrole");
+ * client.close();
+ * }
*
* @param policy admin configuration parameters, pass in null for defaults
- * @param roleName role name filter
- * @throws AerospikeException if command fails
+ * @param roleName role name
+ * @return role definition, or null if not found
+ * @throws AerospikeException when command fails
+ * @see #queryRoles(AdminPolicy)
+ * @see #createRole(AdminPolicy, String, List)
+ * @see Role
*/
public final Role queryRole(AdminPolicy policy, String roleName)
throws AerospikeException {
@@ -5325,10 +6082,19 @@ public final Role queryRole(AdminPolicy policy, String roleName)
}
/**
- * Retrieve all roles.
+ * Retrieve all role definitions.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * java.util.List<Role> roles = client.queryRoles(null);
+ * client.close();
+ * }
*
* @param policy admin configuration parameters, pass in null for defaults
- * @throws AerospikeException if command fails
+ * @return list of roles
+ * @throws AerospikeException when command fails
+ * @see #queryRole(AdminPolicy, String)
+ * @see Role
*/
public final List{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * try {
+ * client.put(null, key, bins);
+ * } catch (AerospikeException e) {
+ * int code = e.getResultCode();
+ * String msg = ResultCode.getResultString(code);
+ * if (e.getInDoubt()) {
+ * // write may have completed
+ * }
+ * }
+ * }
+ *
+ * @see ResultCode
+ * @see #getResultCode
+ * @see #getBaseMessage
+ * @see #keepConnection()
+ * @see Timeout
+ * @see Connection
+ * @see InvalidNode
+ * @see BatchRecords
+ * @see BatchRecordArray
+ * @see Commit
+ * @see ScanTerminated
+ * @see QueryTerminated
*/
public class AerospikeException extends RuntimeException {
private static final long serialVersionUID = 1L;
@@ -121,7 +151,9 @@ public String getMessage() {
}
/**
- * Return base message without extra metadata.
+ * Return base message without extra metadata (result code, node, policy, inDoubt).
+ *
+ * @return the underlying message or the result code string if null
*/
public String getBaseMessage() {
String message = super.getMessage();
@@ -129,7 +161,9 @@ public String getBaseMessage() {
}
/**
- * Should connection be put back into pool.
+ * Whether the connection should be returned to the pool after this exception.
+ *
+ * @return true if the connection is reusable
*/
public final boolean keepConnection() {
return ResultCode.keepConnection(resultCode);
@@ -224,7 +258,12 @@ public void setInDoubt(boolean inDoubt) {
}
/**
- * Exception thrown when database request expires before completing.
+ * Thrown when a database request expires before completing (client or server timeout).
+ * {@code
+ * try {
+ * client.commit(txn);
+ * } catch (AerospikeException.Commit e) {
+ * CommitError err = e.error;
+ * client.abort(txn);
+ * }
+ * }
+ *
+ * @see CommitError
+ * @see CommitStatus
+ * @see com.aerospike.client.AerospikeClient#commit
+ * @see com.aerospike.client.AerospikeClient#abort
*/
public static final class Commit extends AerospikeException {
private static final long serialVersionUID = 1L;
- /**
- * Error status of the attempted commit.
- */
+ /** Error status of the attempted commit. */
public final CommitError error;
- /**
- * Verify result for each read key in the transaction. May be null if failure occurred
- * before verify.
- */
+ /** Verify result per read key; null if failure occurred before verify. */
public final BatchRecord[] verifyRecords;
- /**
- * Roll forward/backward result for each write key in the transaction. May be null if
- * failure occurred before roll forward/backward.
- */
+ /** Roll forward/backward result per write key; null if failure occurred before roll. */
public final BatchRecord[] rollRecords;
public Commit(CommitError error, BatchRecord[] verifyRecords, BatchRecord[] rollRecords) {
diff --git a/client/src/com/aerospike/client/BatchDelete.java b/client/src/com/aerospike/client/BatchDelete.java
index 931babd94..c29a04ed9 100644
--- a/client/src/com/aerospike/client/BatchDelete.java
+++ b/client/src/com/aerospike/client/BatchDelete.java
@@ -23,7 +23,25 @@
import com.aerospike.client.policy.Policy;
/**
- * Batch delete operation.
+ * Batch delete item: one key to delete; optional {@link com.aerospike.client.policy.BatchDeletePolicy}.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * BatchDelete[] deletes = new BatchDelete[] {
+ * new BatchDelete(new Key("ns", "set", "k1")),
+ * new BatchDelete(new BatchDeletePolicy(), new Key("ns", "set", "k2"))
+ * };
+ * client.operate(null, java.util.Arrays.asList(deletes));
+ * for (BatchDelete bd : deletes) {
+ * int rc = bd.resultCode;
+ * }
+ * client.close();
+ * }
+ *
+ * @see BatchRecord
+ * @see com.aerospike.client.AerospikeClient#operate
+ * @see com.aerospike.client.AerospikeClient#delete
*/
public final class BatchDelete extends BatchRecord {
/**
diff --git a/client/src/com/aerospike/client/BatchRead.java b/client/src/com/aerospike/client/BatchRead.java
index c9454171f..7320585cf 100644
--- a/client/src/com/aerospike/client/BatchRead.java
+++ b/client/src/com/aerospike/client/BatchRead.java
@@ -23,8 +23,27 @@
import com.aerospike.client.policy.Policy;
/**
- * Batch key and read only operations with default policy.
- * Used in batch read commands where different bins are needed for each key.
+ * Batch get item: one key with optional bin names, read-all-bins flag, or {@link Operation} list (variable bins per key).
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * BatchRead[] batchReads = new BatchRead[] {
+ * new BatchRead(new Key("ns", "set", "k1"), new String[] { "a", "b" }),
+ * new BatchRead(new Key("ns", "set", "k2"), true),
+ * new BatchRead(new Key("ns", "set", "k3"), new Operation[] { Operation.get("x"), Operation.get("y") })
+ * };
+ * client.get(null, batchReads);
+ * for (BatchRead br : batchReads) {
+ * if (br.record != null) { Record r = br.record; }
+ * }
+ * client.close();
+ * }
+ *
+ * @see BatchRecord
+ * @see com.aerospike.client.AerospikeClient#get
+ * @see com.aerospike.client.listener.BatchListListener
+ * @see com.aerospike.client.listener.BatchSequenceListener
*/
public final class BatchRead extends BatchRecord {
/**
diff --git a/client/src/com/aerospike/client/BatchRecord.java b/client/src/com/aerospike/client/BatchRecord.java
index 7a1b32ca6..58c285f66 100644
--- a/client/src/com/aerospike/client/BatchRecord.java
+++ b/client/src/com/aerospike/client/BatchRecord.java
@@ -20,7 +20,29 @@
import com.aerospike.client.policy.Policy;
/**
- * Batch key and record result.
+ * Base for a single key in a batch get, operate, delete, or UDF; holds key, record (or null), resultCode, and inDoubt flag.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * BatchRead[] batchReads = new BatchRead[] {
+ * new BatchRead(new Key("ns", "set", "k1"), new String[] { "bin1", "bin2" }),
+ * new BatchRead(new Key("ns", "set", "k2"), true)
+ * };
+ * client.get(null, batchReads);
+ * for (BatchRead br : batchReads) {
+ * if (br.record != null) { Object v = br.record.getValue("bin1"); }
+ * }
+ * client.close();
+ * }
+ *
+ * @see BatchRead
+ * @see BatchWrite
+ * @see BatchDelete
+ * @see BatchUDF
+ * @see ResultCode
+ * @see com.aerospike.client.AerospikeException.BatchRecords
+ * @see com.aerospike.client.AerospikeClient#get
+ * @see com.aerospike.client.AerospikeClient#operate
*/
public class BatchRecord {
/**
diff --git a/client/src/com/aerospike/client/BatchUDF.java b/client/src/com/aerospike/client/BatchUDF.java
index 665a264dd..0f386e5c1 100644
--- a/client/src/com/aerospike/client/BatchUDF.java
+++ b/client/src/com/aerospike/client/BatchUDF.java
@@ -25,7 +25,25 @@
import com.aerospike.client.util.Packer;
/**
- * Batch user defined functions.
+ * Batch UDF item: one key and a Lua module/function with optional arguments.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * BatchUDF[] udfs = new BatchUDF[] {
+ * new BatchUDF(new Key("ns", "set", "k1"), "mymodule", "myfunc", new Value[] { Value.get(1), Value.get("x") }),
+ * new BatchUDF(new BatchUDFPolicy(), new Key("ns", "set", "k2"), "mymodule", "other", null)
+ * };
+ * client.operate(null, udfs);
+ * for (BatchUDF bu : udfs) {
+ * if (bu.record != null) { Object result = bu.record.getValue("result"); }
+ * }
+ * client.close();
+ * }
+ *
+ * @see BatchRecord
+ * @see com.aerospike.client.AerospikeClient#operate
+ * @see com.aerospike.client.listener.BatchRecordArrayListener
*/
public final class BatchUDF extends BatchRecord {
/**
diff --git a/client/src/com/aerospike/client/BatchWrite.java b/client/src/com/aerospike/client/BatchWrite.java
index b83c7e216..fc7d9a771 100644
--- a/client/src/com/aerospike/client/BatchWrite.java
+++ b/client/src/com/aerospike/client/BatchWrite.java
@@ -24,7 +24,30 @@
import com.aerospike.client.policy.Policy;
/**
- * Batch key and read/write operations with write policy.
+ * Batch operate item: one key with a list of read/write {@link Operation}s (put, delete, append, etc.).
+ * {@code
+ * AerospikeClient client = new AerospikeClient("localhost", 3000);
+ * BatchWrite[] records = new BatchWrite[] {
+ * new BatchWrite(new Key("ns", "set", "k1"), new Operation[] {
+ * Operation.put(new Bin("a", 1)),
+ * Operation.get("a")
+ * }),
+ * new BatchWrite(new Key("ns", "set", "k2"), new Operation[] { Operation.delete() })
+ * };
+ * client.operate(null, records);
+ * for (BatchWrite bw : records) {
+ * if (bw.record != null) { Record r = bw.record; }
+ * }
+ * client.close();
+ * }
+ *
+ * @see BatchRecord
+ * @see Operation
+ * @see com.aerospike.client.AerospikeClient#operate
+ * @see com.aerospike.client.listener.BatchRecordArrayListener
+ * @see com.aerospike.client.listener.BatchRecordSequenceListener
*/
public final class BatchWrite extends BatchRecord {
/**
diff --git a/client/src/com/aerospike/client/Bin.java b/client/src/com/aerospike/client/Bin.java
index f8de8ac93..d530fe538 100644
--- a/client/src/com/aerospike/client/Bin.java
+++ b/client/src/com/aerospike/client/Bin.java
@@ -24,7 +24,25 @@
import com.aerospike.client.cdt.MapOrder;
/**
- * Column name/value pair.
+ * Name/value pair for a single bin (column); used in put and operate calls.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * try {
+ * Key key = new Key("test", "set1", "id1");
+ * client.put(null, key, new Bin("name", "Alice"), new Bin("age", 30));
+ * } finally {
+ * client.close();
+ * }
+ * }
+ *
+ * @see Value
+ * @see com.aerospike.client.AerospikeClient#put
+ * @see com.aerospike.client.AerospikeClient#operate
*/
public final class Bin {
/**
@@ -246,19 +264,21 @@ public Bin(String name, Value value) {
}
/**
- * Create bin with a null value. This is useful for bin deletions within a record.
+ * Create a bin with a null value (useful for bin deletions within a record).
*
- * @param name bin name, current limit is 15 characters
+ * @param name bin name; current limit 15 characters; must not be null
+ * @return a Bin whose value is null
*/
public static Bin asNull(String name) {
return new Bin(name, Value.getAsNull());
}
/**
- * Create bin with a GeoJSON value.
+ * Create a bin with a GeoJSON string value.
*
- * @param name bin name, current limit is 15 characters
- * @param value bin value
+ * @param name bin name; current limit 15 characters; must not be null
+ * @param value GeoJSON string; must not be null
+ * @return a Bin with GeoJSON value
*/
public static Bin asGeoJSON(String name, String value) {
return new Bin(name, Value.getAsGeoJSON(value));
diff --git a/client/src/com/aerospike/client/CommitError.java b/client/src/com/aerospike/client/CommitError.java
index 92be65dbc..68e2c8c64 100644
--- a/client/src/com/aerospike/client/CommitError.java
+++ b/client/src/com/aerospike/client/CommitError.java
@@ -17,7 +17,29 @@
package com.aerospike.client;
/**
- * Transaction error status.
+ * Transaction commit error code in {@link AerospikeException.Commit}; {@link #str} holds a human-readable message.
+ *
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * try {
+ * client.commit(txn);
+ * } catch (AerospikeException.Commit e) {
+ * CommitError err = e.error;
+ * switch (err) {
+ * case VERIFY_FAIL:
+ * case VERIFY_FAIL_CLOSE_ABANDONED:
+ * break;
+ * default:
+ * System.err.println(err.str);
+ * }
+ * }
+ * }
+ *
+ * @see AerospikeException.Commit
+ * @see CommitStatus
+ * @see AbortStatus
*/
public enum CommitError {
VERIFY_FAIL("Transaction verify failed. Transaction aborted."),
@@ -25,6 +47,7 @@ public enum CommitError {
VERIFY_FAIL_ABORT_ABANDONED("Transaction verify failed. Transaction client abort abandoned. Server will eventually abort the transaction."),
MARK_ROLL_FORWARD_ABANDONED("Transaction client mark roll forward abandoned. Server will eventually abort the transaction.");
+ /** Human-readable message for this error. */
public final String str;
CommitError(String str) {
diff --git a/client/src/com/aerospike/client/CommitStatus.java b/client/src/com/aerospike/client/CommitStatus.java
index 435192827..76714d2d9 100644
--- a/client/src/com/aerospike/client/CommitStatus.java
+++ b/client/src/com/aerospike/client/CommitStatus.java
@@ -17,7 +17,27 @@
package com.aerospike.client;
/**
- * Transaction commit status code.
+ * Transaction commit result returned by {@link com.aerospike.client.AerospikeClient#commit}. OK and ALREADY_COMMITTED indicate success; abandoned statuses mean the server will complete asynchronously.
+ *
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * CommitStatus status = client.commit(txn);
+ * switch (status) {
+ * case OK:
+ * case ALREADY_COMMITTED:
+ * break;
+ * case ROLL_FORWARD_ABANDONED:
+ * case CLOSE_ABANDONED:
+ * System.err.println(status.str);
+ * break;
+ * }
+ * }
+ *
+ * @see AbortStatus
+ * @see CommitError
+ * @see com.aerospike.client.AerospikeClient#commit
*/
public enum CommitStatus {
OK("Commit succeeded"),
@@ -25,6 +45,7 @@ public enum CommitStatus {
ROLL_FORWARD_ABANDONED("Transaction client roll forward abandoned. Server will eventually commit the transaction."),
CLOSE_ABANDONED("Transaction has been rolled forward, but transaction client close was abandoned. Server will eventually close the transaction.");
+ /** Human-readable message for this status. */
public final String str;
CommitStatus(String str) {
diff --git a/client/src/com/aerospike/client/Host.java b/client/src/com/aerospike/client/Host.java
index a4c9e16e7..0ad8d8e35 100644
--- a/client/src/com/aerospike/client/Host.java
+++ b/client/src/com/aerospike/client/Host.java
@@ -20,7 +20,21 @@
import java.util.List;
/**
- * Host name/port of database server.
+ * Host name and port (and optional TLS name) for a database server; used as seed for {@link com.aerospike.client.AerospikeClient} and parsed by {@link #parseHosts}.
+ * {@code
+ * Host[] hosts = Host.parseHosts("localhost", 3000);
+ * IAerospikeClient client = new AerospikeClient(new ClientPolicy(), hosts);
+ * client.close();
+ * }
+ *
+ * @see #parseHosts
+ * @see #parseServiceHosts
+ * @see com.aerospike.client.AerospikeClient
*/
public final class Host {
/**
@@ -95,6 +109,11 @@ public boolean equals(Object obj) {
*
* IPv6 addresses must be enclosed by brackets.
* tlsname and port are optional.
+ *
+ * @param str comma-separated host[:tls][:port] list; must not be null
+ * @param defaultPort port when not specified per host
+ * @return array of Host; never null
+ * @throws AerospikeException when the string format is invalid (e.g. missing host:port or bad port).
*/
public static Host[] parseHosts(String str, int defaultPort) {
try {
@@ -115,6 +134,10 @@ public static Host[] parseHosts(String str, int defaultPort) {
* {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * try {
+ * Node node = client.getNodes()[0];
+ * String build = Info.request(node, "build");
+ * Map m = Info.request(null, node, "build", "statistics");
+ * } finally {
+ * client.close();
+ * }
+ * }
+ *
+ * @see #request(Node, String)
+ * @see #request(InfoPolicy, Node, String)
+ * @see #request(InfoPolicy, Node, String...)
*/
public class Info {
//-------------------------------------------------------
@@ -50,10 +63,11 @@ public class Info {
/**
* Get one info value by name from the specified database server node.
- * This method supports user authentication.
*
- * @param node server node
- * @param name name of variable to retrieve
+ * @param node server node; must not be null
+ * @param name name of the info variable (e.g. "build", "statistics")
+ * @return the value string for the requested name
+ * @throws AerospikeException when the request fails (e.g. timeout, connection error, or invalid command).
*/
public static String request(Node node, String name) throws AerospikeException {
Connection conn = node.getConnection(DEFAULT_TIMEOUT);
diff --git a/client/src/com/aerospike/client/Key.java b/client/src/com/aerospike/client/Key.java
index f03e098c0..b453fdb2c 100644
--- a/client/src/com/aerospike/client/Key.java
+++ b/client/src/com/aerospike/client/Key.java
@@ -22,10 +22,28 @@
import com.aerospike.client.util.Crypto;
/**
- * Unique record identifier. Records can be identified using a specified namespace,
- * an optional set name, and a user defined key which must be unique within a set.
- * Records can also be identified by namespace/digest which is the combination used
- * on the server.
+ * Unique record identifier: namespace, optional set name, and user key (or namespace/digest on the server).
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * try {
+ * Key key = new Key("test", "set1", "id1");
+ * Record rec = client.get(null, key);
+ * if (rec != null) {
+ * String name = (String) rec.getValue("name");
+ * }
+ * } finally {
+ * client.close();
+ * }
+ * }
+ *
+ * @see Record
+ * @see com.aerospike.client.AerospikeClient#get
+ * @see com.aerospike.client.policy.WritePolicy#sendKey
*/
public final class Key {
/**
@@ -83,7 +101,7 @@ public final class Key {
* @param namespace namespace
* @param setName optional set name, enter null when set does not exist
* @param key user defined unique identifier within set.
- * @throws AerospikeException if digest computation fails
+ * @throws AerospikeException when digest computation fails (e.g. unsupported or invalid key type).
*/
public Key(String namespace, String setName, String key) throws AerospikeException {
this.namespace = namespace;
@@ -119,7 +137,7 @@ public Key(String namespace, String setName, String key) throws AerospikeExcepti
* @param namespace namespace
* @param setName optional set name, enter null when set does not exist
* @param key user defined unique identifier within set.
- * @throws AerospikeException if digest computation fails
+ * @throws AerospikeException when digest computation fails (e.g. unsupported or invalid key type).
*/
public Key(String namespace, String setName, byte[] key) throws AerospikeException {
this.namespace = namespace;
@@ -157,7 +175,7 @@ public Key(String namespace, String setName, byte[] key) throws AerospikeExcepti
* @param key user defined unique identifier within set.
* @param offset byte array segment offset
* @param length byte array segment length
- * @throws AerospikeException if digest computation fails
+ * @throws AerospikeException when digest computation fails (e.g. unsupported or invalid key type).
*/
public Key(String namespace, String setName, byte[] key, int offset, int length) throws AerospikeException {
this.namespace = namespace;
@@ -180,7 +198,7 @@ public Key(String namespace, String setName, byte[] key, int offset, int length)
* @param namespace namespace
* @param setName optional set name, enter null when set does not exist
* @param key user defined unique identifier within set.
- * @throws AerospikeException if digest computation fails
+ * @throws AerospikeException when digest computation fails (e.g. unsupported or invalid key type).
*/
public Key(String namespace, String setName, int key) throws AerospikeException {
this.namespace = namespace;
@@ -203,7 +221,7 @@ public Key(String namespace, String setName, int key) throws AerospikeException
* @param namespace namespace
* @param setName optional set name, enter null when set does not exist
* @param key user defined unique identifier within set.
- * @throws AerospikeException if digest computation fails
+ * @throws AerospikeException when digest computation fails (e.g. unsupported or invalid key type).
*/
public Key(String namespace, String setName, long key) throws AerospikeException {
this.namespace = namespace;
@@ -226,7 +244,7 @@ public Key(String namespace, String setName, long key) throws AerospikeException
* @param namespace namespace
* @param setName optional set name, enter null when set does not exist
* @param key user defined unique identifier within set.
- * @throws AerospikeException if digest computation fails
+ * @throws AerospikeException when digest computation fails (e.g. unsupported or invalid key type).
*/
public Key(String namespace, String setName, Value key) throws AerospikeException {
this.namespace = namespace;
@@ -309,8 +327,8 @@ public boolean equals(Object obj) {
*
* @param setName optional set name, enter null when set does not exist
* @param key record identifier, unique within set
- * @return unique server hash value
- * @throws AerospikeException if digest computation fails
+ * @return unique server hash value (RIPEMD-160 digest)
+ * @throws AerospikeException when digest computation fails (e.g. unsupported or invalid key type).
*/
public static byte[] computeDigest(String setName, Value key) throws AerospikeException {
return Crypto.computeDigest(setName, key);
diff --git a/client/src/com/aerospike/client/Language.java b/client/src/com/aerospike/client/Language.java
index 625a23ce6..692915235 100644
--- a/client/src/com/aerospike/client/Language.java
+++ b/client/src/com/aerospike/client/Language.java
@@ -17,11 +17,25 @@
package com.aerospike.client;
/**
- * User defined function languages.
+ * UDF language identifier; used when registering or executing user-defined functions.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * try {
+ * com.aerospike.client.task.RegisterTask task = client.register(null, "myudf.lua", "myudf.lua", Language.LUA);
+ * task.waitTillComplete();
+ * } finally {
+ * client.close();
+ * }
+ * }
+ *
+ * @see com.aerospike.client.AerospikeClient#register
*/
public enum Language {
- /**
- * Lua embedded programming language.
- */
+ /** Lua embedded programming language. */
LUA;
}
diff --git a/client/src/com/aerospike/client/Operation.java b/client/src/com/aerospike/client/Operation.java
index 6bb342fc7..e437840a2 100644
--- a/client/src/com/aerospike/client/Operation.java
+++ b/client/src/com/aerospike/client/Operation.java
@@ -17,7 +17,25 @@
package com.aerospike.client;
/**
- * Database operation definition. The class is used in client's operate() method.
+ * Single operation in a multi-op request; use static factories and pass to {@link com.aerospike.client.AerospikeClient#operate}.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * try {
+ * Key key = new Key("test", "set1", "id1");
+ * Record rec = client.operate(null, key, Operation.add(new Bin("count", 1)), Operation.get("count"));
+ * long count = rec.getLong("count");
+ * } finally {
+ * client.close();
+ * }
+ * }
+ *
+ * @see com.aerospike.client.AerospikeClient#operate
+ * @see Bin
*/
public final class Operation {
/**
diff --git a/client/src/com/aerospike/client/Record.java b/client/src/com/aerospike/client/Record.java
index f2d1293fb..3270bb210 100644
--- a/client/src/com/aerospike/client/Record.java
+++ b/client/src/com/aerospike/client/Record.java
@@ -25,7 +25,30 @@
import com.aerospike.client.Value.HLLValue;
/**
- * Container object for records. Records are equivalent to rows.
+ * Container for a record's bins and metadata (generation, expiration); returned by get, query, and scan.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * try {
+ * Key key = new Key("test", "set1", "id1");
+ * Record rec = client.get(null, key);
+ * if (rec != null) {
+ * String name = rec.getString("name");
+ * long age = rec.getLong("age");
+ * }
+ * } finally {
+ * client.close();
+ * }
+ * }
+ *
+ * @see Key
+ * @see #getValue
+ * @see #getString
+ * @see com.aerospike.client.AerospikeClient#get
*/
public final class Record {
/**
@@ -57,7 +80,10 @@ public Record(
}
/**
- * Get bin value given bin name.
+ * Get bin value by name.
+ *
+ * @param name bin name; must not be null
+ * @return the bin value, or null if absent or bins is null
*/
public Object getValue(String name) {
return (bins == null)? null : bins.get(name);
@@ -65,6 +91,9 @@ public Object getValue(String name) {
/**
* Get bin value as String.
+ *
+ * @param name bin name; must not be null
+ * @return the bin value as String, or null if absent or not a string
*/
public String getString(String name) {
return (String)getValue(name);
diff --git a/client/src/com/aerospike/client/ResultCode.java b/client/src/com/aerospike/client/ResultCode.java
index ba90d0ee5..6af1856ea 100644
--- a/client/src/com/aerospike/client/ResultCode.java
+++ b/client/src/com/aerospike/client/ResultCode.java
@@ -17,8 +17,25 @@
package com.aerospike.client;
/**
- * Database operation error codes. The positive numbers align with the server
- * side file proto.h.
+ * Database operation result/error codes; positive values align with server proto.h, negative values are client-side.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * try {
+ * client.put(null, key, bins);
+ * } catch (AerospikeException e) {
+ * int code = e.getResultCode();
+ * String msg = ResultCode.getResultString(code);
+ * }
+ * }
+ *
+ * @see AerospikeException#getResultCode
+ * @see #getResultString(int)
+ * @see #keepConnection(int)
*/
public final class ResultCode {
/**
diff --git a/client/src/com/aerospike/client/ScanCallback.java b/client/src/com/aerospike/client/ScanCallback.java
index 5040e299a..755decce5 100644
--- a/client/src/com/aerospike/client/ScanCallback.java
+++ b/client/src/com/aerospike/client/ScanCallback.java
@@ -20,12 +20,29 @@
* An object implementing this interface is passed in scan() calls, so the caller can
* be notified with scan results.
* @deprecated
- * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * try {
+ * ScanCallback callback = (key, record) -> {
+ * if (record != null) {
+ * Object val = record.getValue("mybin");
+ * }
+ * };
+ * client.scanAll(null, "test", "set1", callback, "mybin");
+ * } finally {
+ * client.close();
+ * }
+ * }
+ *
+ * @see com.aerospike.client.query.QueryListener
+ * @see com.aerospike.client.AerospikeClient#query
+ * @see com.aerospike.client.AerospikeClient#queryPartitions
*/
@Deprecated
public interface ScanCallback {
@@ -36,13 +53,11 @@ public interface ScanCallback {
* to other nodes will also be terminated and the exception will be propagated back through the
* initiating scan call.
* {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * try {
+ * Txn txn = new Txn();
+ * WritePolicy wp = client.getWritePolicyDefault().copy();
+ * wp.txn = txn;
+ * Key k1 = new Key("test", "set1", "id1");
+ * Key k2 = new Key("test", "set1", "id2");
+ * client.get(null, k1);
+ * client.put(wp, k2, new Bin("x", 1));
+ * CommitStatus status = client.commit(txn);
+ * } finally {
+ * client.close();
+ * }
+ * }
+ *
+ * @see com.aerospike.client.policy.Policy#txn
+ * @see com.aerospike.client.AerospikeClient#commit
+ * @see com.aerospike.client.AerospikeClient#abort
*/
public final class Txn {
- /**
- * Transaction state.
- */
+ /** Transaction state. */
public static enum State {
OPEN,
VERIFIED,
diff --git a/client/src/com/aerospike/client/Value.java b/client/src/com/aerospike/client/Value.java
index 0dc598846..9673798c3 100644
--- a/client/src/com/aerospike/client/Value.java
+++ b/client/src/com/aerospike/client/Value.java
@@ -39,7 +39,49 @@
import com.aerospike.client.util.Packer;
/**
- * Polymorphic value classes used to efficiently serialize objects into the wire protocol.
+ * Polymorphic value type used to serialize objects for the wire protocol; use static {@code get()} factories to obtain instances.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * try {
+ * Key key = new Key("test", "set1", "id1");
+ * client.put(null, key, new Bin("name", Value.get("Alice")), new Bin("age", Value.get(30)));
+ * } finally {
+ * client.close();
+ * }
+ * }
+ *
+ * @see NullValue
+ * @see BytesValue
+ * @see ByteSegmentValue
+ * @see ByteValue
+ * @see StringValue
+ * @see ShortValue
+ * @see IntegerValue
+ * @see LongValue
+ * @see DoubleValue
+ * @see FloatValue
+ * @see BooleanValue
+ * @see BoolIntValue
+ * @see GeoJSONValue
+ * @see HLLValue
+ * @see ValueArray
+ * @see ListValue
+ * @see MapValue
+ * @see SortedMapValue
+ * @see InfinityValue
+ * @see WildcardValue
+ * @see Bin
*/
public abstract class Value {
/**
@@ -397,6 +439,13 @@ public long toLong() {
/**
* Empty value.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Key key = new Key("test", "set1", "id1");
+ * client.put(null, key, new Bin("optional", Value.getAsNull()));
+ * }
*/
public static final class NullValue extends Value {
public static final NullValue INSTANCE = new NullValue();
@@ -457,6 +506,13 @@ public final int hashCode() {
/**
* Byte array value.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Key key = new Key("test", "set1", "id1");
+ * client.put(null, key, new Bin("blob", Value.get(new byte[] { 1, 2, 3 })));
+ * }
*/
public static final class BytesValue extends Value {
private final byte[] bytes;
@@ -528,6 +584,13 @@ public int hashCode() {
/**
* Byte segment value.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * byte[] buf = new byte[] { 0, 1, 2, 3, 4 };
+ * client.put(null, new Key("test", "set1", "id1"), new Bin("seg", Value.get(buf, 1, 3)));
+ * }
*/
public static final class ByteSegmentValue extends Value {
private final byte[] bytes;
@@ -628,6 +691,12 @@ public int getLength() {
/**
* Byte value.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * client.put(null, new Key("test", "set1", "id1"), new Bin("flag", Value.get((byte) 1)));
+ * }
*/
public static final class ByteValue extends Value {
private final byte value;
@@ -703,6 +772,12 @@ public long toLong() {
/**
* String value.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * client.put(null, new Key("test", "set1", "id1"), new Bin("name", Value.get("Alice")));
+ * }
*/
public static final class StringValue extends Value {
private final String value;
@@ -766,6 +841,12 @@ public int hashCode() {
/**
* Short value.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * client.put(null, new Key("test", "set1", "id1"), new Bin("count", Value.get((short) 100)));
+ * }
*/
public static final class ShortValue extends Value {
private final short value;
@@ -840,6 +921,12 @@ public long toLong() {
/**
* Integer value.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * client.put(null, new Key("test", "set1", "id1"), new Bin("age", Value.get(30)));
+ * }
*/
public static final class IntegerValue extends Value {
private final int value;
@@ -914,6 +1001,12 @@ public long toLong() {
/**
* Long value.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * client.put(null, new Key("test", "set1", "id1"), new Bin("timestamp", Value.get(1234567890L)));
+ * }
*/
public static final class LongValue extends Value {
private final long value;
@@ -988,6 +1081,12 @@ public long toLong() {
/**
* Double value.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * client.put(null, new Key("test", "set1", "id1"), new Bin("score", Value.get(3.14)));
+ * }
*/
public static final class DoubleValue extends Value {
private final double value;
@@ -1063,6 +1162,12 @@ public long toLong() {
/**
* Float value.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * client.put(null, new Key("test", "set1", "id1"), new Bin("rate", Value.get(1.5f)));
+ * }
*/
public static final class FloatValue extends Value {
private final float value;
@@ -1137,6 +1242,12 @@ public long toLong() {
/**
* Boolean value.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * client.put(null, new Key("test", "set1", "id1"), new Bin("active", Value.get(true)));
+ * }
*/
public static final class BooleanValue extends Value {
private final boolean value;
@@ -1213,6 +1324,13 @@ public long toLong() {
* Boolean value that converts to integer when sending a bin to the server.
* This class will be deleted once full conversion to boolean particle type
* is complete.
+ * {@code
+ * Value.UseBoolBin = false;
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * client.put(null, new Key("test", "set1", "id1"), new Bin("flag", Value.get(false)));
+ * }
*/
public static final class BoolIntValue extends Value {
private final boolean value;
@@ -1288,6 +1406,13 @@ public long toLong() {
/**
* GeoJSON value.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * client.put(null, new Key("test", "set1", "id1"),
+ * new Bin("loc", Value.getAsGeoJSON("{\"type\":\"Point\",\"coordinates\":[-122.0,37.5]}")));
+ * }
*/
public static final class GeoJSONValue extends Value {
private final String value;
@@ -1354,6 +1479,12 @@ public int hashCode() {
/**
* HyperLogLog value.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * client.put(null, new Key("test", "set1", "id1"), new Bin("hll", Value.getAsHLL(hllBytes)));
+ * }
*/
public static final class HLLValue extends Value {
private final byte[] bytes;
@@ -1422,6 +1553,13 @@ public int hashCode() {
/**
* Value array.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * client.put(null, new Key("test", "set1", "id1"),
+ * new Bin("arr", Value.get(new Value[] { Value.get(1), Value.get("x") })));
+ * }
*/
public static final class ValueArray extends Value {
private final Value[] array;
@@ -1488,6 +1626,13 @@ public int hashCode() {
/**
* List value.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * client.put(null, new Key("test", "set1", "id1"),
+ * new Bin("tags", Value.get(Arrays.asList("a", "b", "c"))));
+ * }
*/
public static final class ListValue extends Value {
private final List list;
@@ -1554,6 +1699,14 @@ public int hashCode() {
/**
* Map value.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * java.util.Map
*/
public static final class MapValue extends Value {
private final Map map;
@@ -1635,6 +1788,14 @@ public static MapOrder getMapOrder(Map map) {
/**
* Sorted map value.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * java.util.SortedMap
*/
public static final class SortedMapValue extends Value {
private final List> list;
@@ -1704,7 +1865,13 @@ public int hashCode() {
}
/**
- * Infinity value.
+ * Infinity value to be used in CDT range comparisons only.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * // Use Value.INFINITY in map/list range operations, e.g. getByValueRange(Value.INFINITY, Value.INFINITY)
+ * }
*/
public static final class InfinityValue extends Value {
@Override
@@ -1760,7 +1927,13 @@ public final int hashCode() {
}
/**
- * Wildcard value.
+ * Wildcard value to be used in CDT range comparisons only.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * // Use Value.WILDCARD in map/list range operations, e.g. getByValueRange(Value.WILDCARD, Value.WILDCARD)
+ * }
*/
public static final class WildcardValue extends Value {
@Override
diff --git a/client/src/com/aerospike/client/admin/Privilege.java b/client/src/com/aerospike/client/admin/Privilege.java
index 3cb1fcb2c..a79b691a3 100644
--- a/client/src/com/aerospike/client/admin/Privilege.java
+++ b/client/src/com/aerospike/client/admin/Privilege.java
@@ -17,23 +17,37 @@
package com.aerospike.client.admin;
/**
- * User privilege.
+ * Single privilege (code plus optional namespace/set scope) for role-based access; use in {@link com.aerospike.client.AerospikeClient#createRole} and {@link com.aerospike.client.AerospikeClient#grantPrivileges}.
+ * {@code
+ * Privilege p = new Privilege();
+ * p.code = PrivilegeCode.READ_WRITE;
+ * p.namespace = "test";
+ * p.setName = null;
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * try {
+ * client.createRole(null, "myrole", Collections.singletonList(p));
+ * } finally {
+ * client.close();
+ * }
+ * }
+ *
+ * @see PrivilegeCode
+ * @see com.aerospike.client.AerospikeClient#createRole
+ * @see com.aerospike.client.AerospikeClient#grantPrivileges
+ * @see com.aerospike.client.AerospikeClient#revokePrivileges
*/
public final class Privilege {
- /**
- * Privilege code.
- */
+ /** Privilege type; must not be null. */
public PrivilegeCode code;
- /**
- * Namespace scope. Apply permission to this namespace only.
- * If namespace is null, the privilege applies to all namespaces.
- */
+ /** Namespace scope; null means all namespaces (when privilege allows). */
public String namespace;
- /**
- * Set name scope. Apply permission to this set within namespace only.
- * If set is null, the privilege applies to all sets within namespace.
- */
+ /** Set name scope within namespace; null means all sets in the namespace. */
public String setName;
}
diff --git a/client/src/com/aerospike/client/admin/PrivilegeCode.java b/client/src/com/aerospike/client/admin/PrivilegeCode.java
index acf760c8b..e3f0369f3 100644
--- a/client/src/com/aerospike/client/admin/PrivilegeCode.java
+++ b/client/src/com/aerospike/client/admin/PrivilegeCode.java
@@ -19,7 +19,23 @@
import com.aerospike.client.AerospikeException;
/**
- * Permission codes define the type of permission granted for a user's role.
+ * Permission codes for role privileges (read, write, admin, etc.); use with {@link Privilege} in createRole and grantPrivileges.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Privilege p = new Privilege();
+ * p.code = PrivilegeCode.READ_WRITE;
+ * p.namespace = "test";
+ * client.createRole(null, "myrole", java.util.Collections.singletonList(p));
+ * }
+ *
+ * @see Privilege
+ * @see com.aerospike.client.AerospikeClient#createRole
+ * @see com.aerospike.client.AerospikeClient#grantPrivileges
*/
public enum PrivilegeCode {
/**
@@ -107,7 +123,9 @@ private PrivilegeCode(int id, String value) {
}
/**
- * Can privilege be scoped with namespace and set.
+ * Whether this privilege can be scoped with namespace and set (data privileges); global-only privileges return false.
+ *
+ * @return true if namespace/set scope can be applied
*/
public boolean canScope() {
// Unknown privileges cannot be scoped since we don't know their characteristics
@@ -117,9 +135,11 @@ public boolean canScope() {
}
/**
- * Convert ID to privilege code enum.
- * Returns UNKNOWN for unrecognized privilege codes to support
- * forward compatibility with newer server versions.
+ * Convert wire-protocol privilege ID to enum.
+ *
+ * @param id privilege ID from server (e.g. 10 for READ, 11 for READ_WRITE)
+ * @return the corresponding PrivilegeCode
+ * @throws AerospikeException when the given ID is not a known privilege code (invalid or reserved).
*/
public static PrivilegeCode fromId(int id) {
switch (id) {
diff --git a/client/src/com/aerospike/client/admin/Role.java b/client/src/com/aerospike/client/admin/Role.java
index 2f0349171..950fe1b88 100644
--- a/client/src/com/aerospike/client/admin/Role.java
+++ b/client/src/com/aerospike/client/admin/Role.java
@@ -19,97 +19,83 @@
import java.util.List;
/**
- * Role definition.
+ * Role definition: name, privileges, optional whitelist and read/write quotas. Returned by {@link com.aerospike.client.AerospikeClient#queryRole}; privilege list is used in createRole and grantPrivileges.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * try {
+ * Role role = client.queryRole(null, "myrole");
+ * if (role != null) {
+ * String name = role.name;
+ * List privs = role.privileges;
+ * }
+ * } finally {
+ * client.close();
+ * }
+ * }
+ *
+ * @see Privilege
+ * @see com.aerospike.client.AerospikeClient#queryRole
+ * @see com.aerospike.client.AerospikeClient#queryRoles
+ * @see com.aerospike.client.AerospikeClient#createRole
*/
public final class Role {
- /**
- * Manage users their roles.
- */
+ /** Role name for user administration. */
public static final String UserAdmin = "user-admin";
- /**
- * Manage server configuration.
- */
+ /** Role name for server configuration. */
public static final String SysAdmin = "sys-admin";
- /**
- * Manage user defined functions and indicies.
- */
+ /** Role name for UDF and index administration. */
public static final String DataAdmin = "data-admin";
- /**
- * Manage user defined functions.
- */
+ /** Role name for UDF administration. */
public static final String UDFAdmin = "udf-admin";
- /**
- * Manage indicies.
- */
+ /** Role name for index administration. */
public static final String SIndexAdmin = "sindex-admin";
- /**
- * Allow read commands.
- */
+ /** Role name for read-only access. */
public static final String Read = "read";
- /**
- * Allow read and write commands.
- */
+ /** Role name for read and write access. */
public static final String ReadWrite = "read-write";
- /**
- * Allow read and write commands within user defined functions.
- */
+ /** Role name for read/write via UDF. */
public static final String ReadWriteUdf = "read-write-udf";
- /**
- * Allow write commands.
- */
+ /** Role name for write-only access. */
public static final String Write = "write";
- /**
- * Allow truncate.
- */
+ /** Role name for truncate. */
public static final String Truncate = "truncate";
- /**
- * Manage data masking.
- */
+ /** Role name for data masking administration. */
public static final String MaskingAdmin = "masking-admin";
- /**
- * Allow read masked data.
- */
+ /** Role name for read masked data. */
public static final String ReadMasked = "read-masked";
- /**
- * Allow write masked data.
- */
+ /** Role name for write masked data. */
public static final String WriteMasked = "write-masked";
- /**
- * Role name.
- */
+ /** Role name. */
public String name;
- /**
- * List of assigned privileges.
- */
+ /** Assigned privileges (namespace/set-scoped when applicable). */
public List{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * try {
+ * User user = client.queryUser(null, "jdoe");
+ * if (user != null) {
+ * String name = user.name;
+ * List roles = user.roles;
+ * }
+ * } finally {
+ * client.close();
+ * }
+ * }
+ *
+ * @see com.aerospike.client.AerospikeClient#queryUser
+ * @see com.aerospike.client.AerospikeClient#queryUsers
+ * @see com.aerospike.client.AerospikeClient#createUser
+ * @see Role
*/
public final class User {
- /**
- * User name.
- */
+ /** User name. */
public String name;
- /**
- * List of assigned roles.
- */
+ /** Assigned role names. */
public List
- *
- * Future server releases may add additional statistics.
+ * Read statistics (may be null). Current offsets: 0 = read quota (RPS), 1 = read TPS, 2 = read scan/query RPS, 3 = limitless read scans/queries. Future server versions may add more.
*/
public List
- *
- * Future server releases may add additional statistics.
+ * Write statistics (may be null). Current offsets: 0 = write quota (RPS), 1 = write TPS, 2 = write scan/query RPS, 3 = limitless write scans/queries. Future server versions may add more.
*/
public List{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * InfoPolicy policy = new InfoPolicy();
+ * Node node = client.getNodes()[0];
+ *
+ * client.createIndex(loop, policy, "ns", "set", "idx1", "bin1", IndexType.STRING, new IndexListener() {
+ * public void onSuccess(AsyncIndexTask task) {
+ * task.queryStatus(loop, policy, node, new TaskStatusListener() { ... });
+ * }
+ * public void onFailure(AerospikeException e) { }
+ * });
+ * }
+ *
+ * @see IAerospikeClient#createIndex
+ * @see com.aerospike.client.listener.TaskStatusListener
*/
public class AsyncIndexTask {
private final IAerospikeClient client;
@@ -38,7 +59,10 @@ public class AsyncIndexTask {
private final boolean isCreate;
/**
- * Initialize task with fields needed to query server nodes.
+ * @param client client (must not be null)
+ * @param namespace namespace
+ * @param indexName index name
+ * @param isCreate true for create, false for drop
*/
public AsyncIndexTask(IAerospikeClient client, String namespace, String indexName, boolean isCreate) {
this.client = client;
@@ -48,8 +72,11 @@ public AsyncIndexTask(IAerospikeClient client, String namespace, String indexNam
}
/**
- * Asynchronously query node for task completion status.
- * All nodes must respond with load_pct of 100 to be considered done.
+ * Asynchronously queries the given node for this task's completion status; all nodes must report load_pct 100 for the task to be done.
+ * @param eventLoop event loop to run the request on (must not be null)
+ * @param policy info policy (must not be null)
+ * @param node node to query (must not be null)
+ * @param listener callback for status or failure (must not be null)
*/
public void queryStatus(EventLoop eventLoop, InfoPolicy policy, Node node, TaskStatusListener listener) {
if (client.getNodes().length == 0) {
diff --git a/client/src/com/aerospike/client/async/EventLoop.java b/client/src/com/aerospike/client/async/EventLoop.java
index b619a3fb8..f896f1bfe 100644
--- a/client/src/com/aerospike/client/async/EventLoop.java
+++ b/client/src/com/aerospike/client/async/EventLoop.java
@@ -22,77 +22,87 @@
import com.aerospike.client.cluster.Node;
/**
- * Aerospike event loop interface.
+ * Single event loop used to run asynchronous Aerospike operations.
+ * {@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy policy = new ClientPolicy();
+ * policy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(policy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * client.get(loop, new Policy(), new RecordListener() { ... }, key);
+ * }
+ *
+ * @see EventLoops
+ * @see NioEventLoop
+ * @see NettyEventLoop
*/
public interface EventLoop {
/**
- * Execute async command. Execute immediately if in event loop.
- * Otherwise, place command on event loop queue.
+ * Executes an async command on this event loop; runs immediately if called from the event loop thread, otherwise enqueues.
+ * @param cluster cluster (must not be null)
+ * @param command command to run (must not be null)
*/
public void execute(Cluster cluster, AsyncCommand command);
/**
- * Schedule execution of runnable command on event loop.
- * Command is placed on event loop queue and is never executed directly.
+ * Schedules a runnable on this event loop; always enqueues and never runs in the caller thread.
+ * @param command runnable to run (must not be null)
*/
public void execute(Runnable command);
- /**
- * Retry async batch command. For internal use only.
- */
+ /** Retry async batch command. For internal use only. */
public void executeBatchRetry(Runnable other, AsyncCommand command, long deadline);
/**
- * Schedule execution of runnable command with delay.
+ * Schedules a runnable to run after the given delay.
+ * @param command runnable to run (must not be null)
+ * @param delay delay amount
+ * @param unit unit of delay (must not be null)
*/
public void schedule(Runnable command, long delay, TimeUnit unit);
/**
- * Schedule execution with a reusable ScheduleTask.
+ * Schedules a reusable task to run after the given delay.
+ * @param task task to run (must not be null)
+ * @param delay delay amount
+ * @param unit unit of delay (must not be null)
*/
public void schedule(ScheduleTask task, long delay, TimeUnit unit);
/**
- * Create async connector command.
+ * Creates an async connector command for the given cluster and node.
+ * @param cluster cluster (must not be null)
+ * @param node node (must not be null)
+ * @param listener listener (must not be null)
+ * @return new connector command
*/
public AsyncConnector createConnector(Cluster cluster, Node node, AsyncConnector.Listener listener);
- /**
- * Return the approximate number of commands currently being processed on
- * the event loop. The value is approximate because the call may be from a
- * different thread than the event loop’s thread and there are no locks or
- * atomics used.
- *
- * If accuracy is important and not running in the event loop thread,
- * the slower execute(Runnable) can be called to run this method in the
- * event loop thread.
+/**
+ * Approximate number of commands currently being processed on this event loop.
+ * {@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy policy = new ClientPolicy();
+ * policy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(policy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * }
+ *
+ * @see EventLoop
+ * @see NioEventLoops
+ * @see NettyEventLoops
+ * @see com.aerospike.client.policy.ClientPolicy#eventLoops
*/
public interface EventLoops extends Closeable {
- /**
- * Return array of Aerospike event loops.
- */
+ /** @return array of all event loops in this group (must not be null) */
public EventLoop[] getArray();
- /**
- * Return number of event loops in this group.
- */
+ /** @return number of event loops in this group */
public int getSize();
/**
- * Return Aerospike event loop given array index..
+ * @param index index in the event loop array (0 to size-1)
+ * @return the event loop at the given index
*/
public EventLoop get(int index);
/**
- * Return next Aerospike event loop in round-robin fashion.
- * Implementations might not use an atomic sequence counter.
- * Non-atomic counters improve performance, but might result
- * in a slightly imperfect round-robin distribution.
+ * Returns the next event loop in round-robin order; implementations may use a non-atomic counter for performance.
+ * @return next event loop (must not be null)
*/
public EventLoop next();
- /**
- * Close event loops.
- */
+ /** Closes this event loop group and releases resources. */
public void close();
}
diff --git a/client/src/com/aerospike/client/async/EventPolicy.java b/client/src/com/aerospike/client/async/EventPolicy.java
index 7971cd5cb..80d3b6217 100644
--- a/client/src/com/aerospike/client/async/EventPolicy.java
+++ b/client/src/com/aerospike/client/async/EventPolicy.java
@@ -17,7 +17,18 @@
package com.aerospike.client.async;
/**
- * Asynchronous event loop configuration.
+ * Configuration for asynchronous event loops (limits, timeouts, queue capacities).
+ * {@code
+ * EventPolicy policy = new EventPolicy();
+ * policy.maxCommandsInProcess = 40;
+ * EventLoops eventLoops = new NioEventLoops(policy, 4);
+ * }
+ *
+ * @see NioEventLoops
+ * @see NettyEventLoops
+ * @see com.aerospike.client.AerospikeException.AsyncQueueFull
*/
public final class EventPolicy {
/**
diff --git a/client/src/com/aerospike/client/async/NettyEventLoops.java b/client/src/com/aerospike/client/async/NettyEventLoops.java
index 8cfc996a6..fcfa44eee 100644
--- a/client/src/com/aerospike/client/async/NettyEventLoops.java
+++ b/client/src/com/aerospike/client/async/NettyEventLoops.java
@@ -36,8 +36,22 @@
import io.netty.util.concurrent.EventExecutor;
/**
- * Aerospike wrapper around netty event loops.
- * Implements the Aerospike EventLoops interface.
+ * Netty-based implementation of {@link EventLoops} (wraps an existing Netty {@link io.netty.channel.EventLoopGroup}).
+ * {@code
+ * EventLoopGroup group = new NioEventLoopGroup(4);
+ * EventLoops eventLoops = new NettyEventLoops(group);
+ * ClientPolicy policy = new ClientPolicy();
+ * policy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(policy, "localhost", 3000);
+ * }
+ *
+ * @see EventLoops
+ * @see NioEventLoops
+ * @see EventPolicy
+ * @see EventLoopType
+ * @see com.aerospike.client.policy.ClientPolicy#eventLoops
*/
public final class NettyEventLoops implements EventLoops {
@@ -47,23 +61,27 @@ public final class NettyEventLoops implements EventLoops {
final EventLoopType eventLoopType;
private int eventIter;
- /**
- * Create Aerospike event loop wrappers from given netty event loops.
- */
+ /** Creates Aerospike event loop wrappers from the given Netty event loop group (type inferred). */
public NettyEventLoops(EventLoopGroup group) {
this(new EventPolicy(), group);
}
/**
- * Create Aerospike event loop wrappers from given netty event loops.
- * The type of event loop is determined from the event loop group instance.
+ * Creates Aerospike event loop wrappers from the given Netty group and policy; type is inferred from the group.
+ * @param policy event loop policy (must not be null)
+ * @param group Netty event loop group (must not be null)
+ * @throws com.aerospike.client.AerospikeException when minTimeout is invalid
*/
public NettyEventLoops(EventPolicy policy, EventLoopGroup group) {
this(policy, group, getEventLoopType(group));
}
/**
- * Create Aerospike event loop wrappers from given netty event loops and specified event loop type.
+ * Creates Aerospike event loop wrappers with an explicit event loop type.
+ * @param policy event loop policy (must not be null)
+ * @param group Netty event loop group (must not be null)
+ * @param type event loop type (must not be null)
+ * @throws com.aerospike.client.AerospikeException when minTimeout is invalid
*/
public NettyEventLoops(EventPolicy policy, EventLoopGroup group, EventLoopType type) {
if (policy.minTimeout < 5) {
diff --git a/client/src/com/aerospike/client/async/NettyTlsContext.java b/client/src/com/aerospike/client/async/NettyTlsContext.java
index a6c64068f..e4f453bd9 100644
--- a/client/src/com/aerospike/client/async/NettyTlsContext.java
+++ b/client/src/com/aerospike/client/async/NettyTlsContext.java
@@ -38,14 +38,27 @@
import io.netty.handler.ssl.SslHandler;
/**
- * Netty SslContext container.
+ * Netty SslContext container for TLS when using Netty-based event loops.
+ * {@code
+ * TlsPolicy tp = new TlsPolicy();
+ * tp.nettyContext = new NettyTlsContext(tp);
+ * ClientPolicy policy = new ClientPolicy();
+ * policy.tlsPolicy = tp;
+ * policy.eventLoops = new NettyEventLoops(...);
+ * }
+ *
+ * @see com.aerospike.client.policy.TlsPolicy#nettyContext
*/
public final class NettyTlsContext implements CipherSuiteFilter {
private final TlsPolicy policy;
private final SslContext context;
/**
- * Construct Netty SslContext.
+ * Builds a Netty SslContext from the given TLS policy.
+ * @param policy TLS policy (must not be null)
+ * @throws com.aerospike.client.AerospikeException when Netty TLS initialization fails
*/
public NettyTlsContext(TlsPolicy policy) {
this.policy = policy;
@@ -94,15 +107,15 @@ public NettyTlsContext(TlsPolicy policy) {
}
/**
- * Create TLS handler.
+ * Creates a TLS handler for the given Netty channel.
+ * @param ch Netty socket channel (must not be null)
+ * @return new SslHandler for the channel
*/
public SslHandler createHandler(SocketChannel ch) {
return context.newHandler(ch.alloc());
}
- /**
- * Return supported ciphers.
- */
+ /** @return supported ciphers per policy, or default from context when policy ciphers are null */
@Override
public String[] filterCipherSuites(Iterable{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy policy = new ClientPolicy();
+ * policy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(policy, "localhost", 3000);
+ * }
+ *
+ * @see EventLoops
+ * @see NettyEventLoops
+ * @see EventPolicy
+ * @see com.aerospike.client.policy.ClientPolicy#eventLoops
*/
public final class NioEventLoops implements EventLoops {
final NioEventLoop[] eventLoops;
private int eventIter;
- /**
- * Create direct NIO event loops, one per CPU core.
- */
+ /** Creates direct NIO event loops, one per CPU core. */
public NioEventLoops() throws AerospikeException {
this(0);
}
/**
- * Create direct NIO event loops.
- *
- * @param size number of event loops to create
+ * Creates direct NIO event loops.
+ * @param size number of event loops (0 for one per CPU core)
+ * @throws com.aerospike.client.AerospikeException when minTimeout is invalid or creation fails
*/
public NioEventLoops(int size) throws AerospikeException {
this(new EventPolicy(), size);
}
/**
- * Create direct NIO event loops.
- *
- * @param policy event loop policy
- * @param size number of event loops to create
+ * Creates direct NIO event loops with the given policy.
+ * @param policy event loop policy (must not be null)
+ * @param size number of event loops (0 for one per CPU core)
+ * @throws com.aerospike.client.AerospikeException when minTimeout is invalid or creation fails
*/
public NioEventLoops(EventPolicy policy, int size) throws AerospikeException {
this(policy, size, false, "aerospike-nio-event-loop");
}
/**
- * Create direct NIO event loops.
- *
- * @param policy event loop policy
- * @param size number of event loops to create
- * @param daemon true if the associated threads should run as a daemons
- * @param poolName event loop thread pool name
+ * Creates direct NIO event loops with the given policy and thread settings.
+ * @param policy event loop policy (must not be null)
+ * @param size number of event loops (0 for one per CPU core)
+ * @param daemon true if event loop threads should be daemon threads
+ * @param poolName name for the event loop thread pool
+ * @throws com.aerospike.client.AerospikeException when minTimeout is invalid or creation fails
*/
public NioEventLoops(EventPolicy policy, int size, boolean daemon, String poolName) throws AerospikeException {
if (policy.minTimeout < 5) {
diff --git a/client/src/com/aerospike/client/cdt/CTX.java b/client/src/com/aerospike/client/cdt/CTX.java
index 88e772d6f..0cb2e494d 100644
--- a/client/src/com/aerospike/client/cdt/CTX.java
+++ b/client/src/com/aerospike/client/cdt/CTX.java
@@ -27,9 +27,31 @@
import com.aerospike.client.util.Unpacker;
/**
- * Nested CDT context. Identifies the location of nested list/map to apply the operation.
- * for the current level. An array of CTX identifies location of the list/map on multiple
- * levels on nesting.
+ * Nested CDT context. Identifies the path to a nested list or map for an operation or query.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Key key = new Key("ns", "set", "mykey");
+ *
+ * // Nested path: map "book" then all list items (e.g. for CdtOperation.selectByPath)
+ * CTX ctx1 = CTX.mapKey(Value.get("book"));
+ * CTX ctx2 = CTX.allChildren();
+ *
+ * // List index -1 = last element (e.g. for Filter.range on list bin)
+ * CTX listCtx = CTX.listIndex(-1);
+ * Filter.range("listbin", 10, 20, listCtx);
+ *
+ * // Query index on last element of list
+ * IndexTask task = client.createIndex(null, "ns", "set", "idx1", "listbin",
+ * IndexType.NUMERIC, IndexCollectionType.DEFAULT, CTX.listRank(-1));
+ * }
+ *
+ * @see com.aerospike.client.cdt.CdtOperation
+ * @see com.aerospike.client.cdt.ListOperation
+ * @see com.aerospike.client.cdt.MapOperation
+ * @see com.aerospike.client.query.Filter#range
*/
public final class CTX {
/**
diff --git a/client/src/com/aerospike/client/cdt/CdtOperation.java b/client/src/com/aerospike/client/cdt/CdtOperation.java
index ab2b5f98a..87190645f 100644
--- a/client/src/com/aerospike/client/cdt/CdtOperation.java
+++ b/client/src/com/aerospike/client/cdt/CdtOperation.java
@@ -26,7 +26,34 @@
import com.aerospike.client.util.Packer;
import com.aerospike.client.exp.Expression;
-public class CdtOperation {
+/**
+ * CDT select and apply operations on nested list/map bins by path (context).
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Key key = new Key("ns", "set", "mykey");
+ * Map rootMap = new HashMap();
+ * rootMap.put("book", booksList);
+ * client.put(null, key, new Bin("bin", rootMap));
+ *
+ * CTX ctx1 = CTX.mapKey(Value.get("book"));
+ * CTX ctx2 = CTX.allChildren();
+ * Operation selectOp = CdtOperation.selectByPath("bin", Exp.SELECT_VALUE, ctx1, ctx2);
+ * Record rec = client.operate(null, key, selectOp);
+ * List results = rec.getList("bin");
+ *
+ * Expression modifyExp = Exp.build(Exp.mul(Exp.floatLoopVar(LoopVarPart.VALUE), Exp.val(1.10)));
+ * Operation applyOp = CdtOperation.modifyByPath("bin", Exp.MODIFY_DEFAULT, modifyExp, ctx1, ctx2, CTX.mapKey(Value.get("price")));
+ * client.operate(null, key, applyOp);
+ * }
+ *
+ * @see CTX
+ * @see com.aerospike.client.exp.Exp
+ * @see com.aerospike.client.AerospikeClient#operate
+ */
+public class CdtOperation {
/**
* Create CDT select operation with context.
*
diff --git a/client/src/com/aerospike/client/cdt/ListOperation.java b/client/src/com/aerospike/client/cdt/ListOperation.java
index 3b11869c7..338bb166e 100644
--- a/client/src/com/aerospike/client/cdt/ListOperation.java
+++ b/client/src/com/aerospike/client/cdt/ListOperation.java
@@ -24,34 +24,54 @@
import com.aerospike.client.util.Packer;
/**
- * List bin operations. Create list operations used by client operate command.
+ * List bin operations for the client operate command. List operations support negative indexing.
+ * Index out of bounds returns a parameter error; a range partially out of bounds returns the valid
+ * part. Use optional {@link CTX} for nested list/map paths. Prefer {@link #appendItems} over
+ * multiple {@link #append} for better performance.
*
- *
- *
- *
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Key key = new Key("ns", "set", "listkey");
+ * client.delete(null, key);
+ *
+ * Record rec = client.operate(null, key,
+ * ListOperation.append("bin", Value.get(55)),
+ * ListOperation.append("bin", Value.get(77)),
+ * ListOperation.pop("bin", -1),
+ * ListOperation.size("bin"));
+ * long size = (Long) rec.getList("bin").get(3);
+ *
+ * List itemList = new ArrayList<>();
+ * itemList.add(Value.get(12));
+ * itemList.add(Value.get("my string"));
+ * client.operate(null, key, ListOperation.appendItems("bin", itemList));
+ * rec = client.operate(null, key, ListOperation.getRange("bin", 0, 4));
+ * List range = (List) rec.getList("bin").get(0);
+ *
+ * // Index/range: get by index 0 or -1, range (1, 2), last three (-3, 3), -5 count 4
+ * client.operate(null, key, ListOperation.getByIndex("bin", 0, ListReturnType.VALUE));
+ * client.operate(null, key, ListOperation.getByIndex("bin", -1, ListReturnType.VALUE));
+ * client.operate(null, key, ListOperation.getByIndexRange("bin", 1, 2, ListReturnType.VALUE));
+ * client.operate(null, key, ListOperation.getByIndexRange("bin", -3, 3, ListReturnType.VALUE));
+ * client.operate(null, key, ListOperation.getByIndexRange("bin", -5, 4, ListReturnType.VALUE));
+ *
+ * // Nested: append 11 to last list (bin = [[7,9,5],[1,2,3],[6,5,4,1]] -> last list gets 11)
+ * client.operate(null, key, ListOperation.append("bin", Value.get(11), CTX.listIndex(-1)));
+ * // Nested with map: append 11 to lowest-ranked list in map "key2"
+ * client.operate(null, key, ListOperation.append("bin", Value.get(11), CTX.mapKey(Value.get("key2")), CTX.listRank(0)));
+ * }
+ *
+ * @see com.aerospike.client.AerospikeClient#operate
+ * @see CTX
+ * @see ListPolicy
+ * @see ListReturnType
*/
public class ListOperation {
private static final int SET_TYPE = 0;
diff --git a/client/src/com/aerospike/client/cdt/ListOrder.java b/client/src/com/aerospike/client/cdt/ListOrder.java
index 43c223f8e..593eaa554 100644
--- a/client/src/com/aerospike/client/cdt/ListOrder.java
+++ b/client/src/com/aerospike/client/cdt/ListOrder.java
@@ -17,7 +17,12 @@
package com.aerospike.client.cdt;
/**
- * List storage order.
+ * List storage order; used in {@link ListPolicy} and {@link ListOperation#create}.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * ListPolicy unordered = ListPolicy.Default;
+ * ListPolicy ordered = new ListPolicy(ListOrder.ORDERED, ListWriteFlags.DEFAULT);
+ * client.operate(null, key, ListOperation.appendItems(ordered, "bin", itemList));
+ * client.operate(null, key, ListOperation.increment(ordered, "bin", 0, Value.get(1)));
+ * }
+ *
+ * @see ListOperation
+ * @see ListOrder
+ * @see ListWriteFlags
*/
public final class ListPolicy {
- /**
- * Default unordered list with normal write semantics.
- */
+ /** Default unordered list with normal write semantics. */
public static final ListPolicy Default = new ListPolicy();
public final int attributes;
diff --git a/client/src/com/aerospike/client/cdt/ListReturnType.java b/client/src/com/aerospike/client/cdt/ListReturnType.java
index 6b764d591..18497061c 100644
--- a/client/src/com/aerospike/client/cdt/ListReturnType.java
+++ b/client/src/com/aerospike/client/cdt/ListReturnType.java
@@ -17,7 +17,17 @@
package com.aerospike.client.cdt;
/**
- * List return type. Type of data to return when selecting or removing items from the list.
+ * What to return from list read/remove operations (index, rank, value, count, etc.).
+ * {@code
+ * Record rec = client.operate(null, key,
+ * ListOperation.getByIndex("bin", 0, ListReturnType.VALUE),
+ * ListOperation.getByValue("bin", Value.get(5), ListReturnType.INDEX));
+ * }
+ *
+ * @see ListOperation
*/
public final class ListReturnType {
/**
diff --git a/client/src/com/aerospike/client/cdt/ListWriteFlags.java b/client/src/com/aerospike/client/cdt/ListWriteFlags.java
index 5680e63ff..53c17328e 100644
--- a/client/src/com/aerospike/client/cdt/ListWriteFlags.java
+++ b/client/src/com/aerospike/client/cdt/ListWriteFlags.java
@@ -17,11 +17,15 @@
package com.aerospike.client.cdt;
/**
- * List write bit flags. Use BITWISE OR to combine flags. Example:
- *
- * {@code
+ * List write bit flags; combine with BITWISE OR and pass to {@link ListPolicy}.
+ * {@code
* int flags = ListWriteFlags.ADD_UNIQUE | ListWriteFlags.NO_FAIL | ListWriteFlags.PARTIAL;
+ * ListPolicy policy = new ListPolicy(ListOrder.ORDERED, flags);
* }
+ *
+ * @see ListPolicy
*/
public final class ListWriteFlags {
/**
diff --git a/client/src/com/aerospike/client/cdt/MapOperation.java b/client/src/com/aerospike/client/cdt/MapOperation.java
index 32557138f..a71655a6e 100644
--- a/client/src/com/aerospike/client/cdt/MapOperation.java
+++ b/client/src/com/aerospike/client/cdt/MapOperation.java
@@ -25,53 +25,58 @@
import com.aerospike.client.util.Packer;
/**
- * Map bin operations. Create map operations used by the client operate command.
- * The default unique key map is unordered. Valid map key types are:
- *
- *
- *
- *
- *
- *
- *
- *
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Key key = new Key("ns", "set", "mapkey");
+ * client.delete(null, key);
+ *
+ * client.operate(null, key,
+ * MapOperation.put(MapPolicy.Default, "bin", Value.get("name"), Value.get("Alice")),
+ * MapOperation.put(MapPolicy.Default, "bin", Value.get("score"), Value.get(100)));
+ * Record rec = client.operate(null, key,
+ * MapOperation.getByKey("bin", Value.get("name"), MapReturnType.VALUE),
+ * MapOperation.size("bin"));
+ * String name = (String) rec.getList("bin").get(0);
+ * long size = (Long) rec.getList("bin").get(1);
+ *
+ * Map items = new HashMap<>();
+ * items.put(Value.get("a"), Value.get(1));
+ * items.put(Value.get("b"), Value.get(2));
+ * client.operate(null, key, MapOperation.putItems(MapPolicy.Default, "bin", items));
+ *
+ * // Index/rank: get by index 0 or -1, by rank 0 or -1
+ * client.operate(null, key, MapOperation.getByIndex("bin", 0, MapReturnType.VALUE));
+ * client.operate(null, key, MapOperation.getByIndex("bin", -1, MapReturnType.VALUE));
+ * client.operate(null, key, MapOperation.getByRank("bin", 0, MapReturnType.VALUE));
+ * client.operate(null, key, MapOperation.getByRank("bin", -1, MapReturnType.VALUE));
+ *
+ * // Nested: put value 11 at key "key21" inside map key "key2" (bin = {key1={...}, key2={key21=3,key22=5}})
+ * client.operate(null, key, MapOperation.put(MapPolicy.Default, "bin", Value.get("key21"), Value.get(11), CTX.mapKey(Value.get("key2"))));
+ * // Nested with rank: put 11 at "key121" in highest-ranked map in "key1" (CTX.mapKey(key1), CTX.mapRank(-1))
+ * client.operate(null, key, MapOperation.put(MapPolicy.Default, "bin", Value.get("key121"), Value.get(11), CTX.mapKey(Value.get("key1")), CTX.mapRank(-1)));
+ * }
+ *
+ * @see com.aerospike.client.AerospikeClient#operate
+ * @see CTX
+ * @see MapPolicy
+ * @see MapReturnType
*/
public class MapOperation {
private static final int SET_TYPE = 64;
diff --git a/client/src/com/aerospike/client/cdt/MapOrder.java b/client/src/com/aerospike/client/cdt/MapOrder.java
index 2fbd25417..b6371feb7 100644
--- a/client/src/com/aerospike/client/cdt/MapOrder.java
+++ b/client/src/com/aerospike/client/cdt/MapOrder.java
@@ -17,7 +17,12 @@
package com.aerospike.client.cdt;
/**
- * Map storage order.
+ * Map storage order; used in {@link MapPolicy} and {@link MapOperation}.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * MapPolicy policy = MapPolicy.Default;
+ * client.operate(null, key, MapOperation.put(policy, "bin", Value.get("k"), Value.get(42)));
+ *
+ * MapPolicy keyOrdered = new MapPolicy(MapOrder.KEY_ORDERED, MapWriteFlags.DEFAULT);
+ * client.operate(null, key, MapOperation.putItems(keyOrdered, "bin", map));
+ * }
+ *
+ * @see MapOperation
+ * @see MapOrder
+ * @see MapWriteFlags
*/
public final class MapPolicy {
- /**
- * Default unordered unique key map with normal put semantics.
- */
+ /** Default unordered unique-key map with normal put semantics. */
public static final MapPolicy Default = new MapPolicy();
public final int attributes;
diff --git a/client/src/com/aerospike/client/cdt/MapReturnType.java b/client/src/com/aerospike/client/cdt/MapReturnType.java
index 755a5828d..462f8b42d 100644
--- a/client/src/com/aerospike/client/cdt/MapReturnType.java
+++ b/client/src/com/aerospike/client/cdt/MapReturnType.java
@@ -17,7 +17,17 @@
package com.aerospike.client.cdt;
/**
- * Map return type. Type of data to return when selecting or removing items from the map.
+ * What to return from map read/remove operations (key, value, index, rank, count, etc.).
+ * {@code
+ * Record rec = client.operate(null, key,
+ * MapOperation.getByKey("bin", Value.get("name"), MapReturnType.VALUE),
+ * MapOperation.getByRank("bin", -1, MapReturnType.KEY_VALUE));
+ * }
+ *
+ * @see MapOperation
*/
public final class MapReturnType {
/**
diff --git a/client/src/com/aerospike/client/cdt/MapWriteFlags.java b/client/src/com/aerospike/client/cdt/MapWriteFlags.java
index 3aea468a8..e656729dc 100644
--- a/client/src/com/aerospike/client/cdt/MapWriteFlags.java
+++ b/client/src/com/aerospike/client/cdt/MapWriteFlags.java
@@ -17,11 +17,15 @@
package com.aerospike.client.cdt;
/**
- * Map write bit flags. Use BITWISE OR to combine flags. Example:
- *
- * {@code
+ * Map write bit flags; combine with BITWISE OR and pass to {@link MapPolicy}.
+ * {@code
* int flags = MapWriteFlags.UPDATE_ONLY | MapWriteFlags.NO_FAIL | MapWriteFlags.PARTIAL;
+ * MapPolicy policy = new MapPolicy(MapOrder.KEY_ORDERED, flags);
* }
+ *
+ * @see MapPolicy
*/
public final class MapWriteFlags {
/**
diff --git a/client/src/com/aerospike/client/configuration/ConfigurationProvider.java b/client/src/com/aerospike/client/configuration/ConfigurationProvider.java
index 8e14cf013..9288af4b2 100644
--- a/client/src/com/aerospike/client/configuration/ConfigurationProvider.java
+++ b/client/src/com/aerospike/client/configuration/ConfigurationProvider.java
@@ -19,9 +19,42 @@
import com.aerospike.client.configuration.serializers.Configuration;
+/**
+ * Supplies static and dynamic client configuration (e.g. from YAML). Pass to {@link com.aerospike.client.policy.ClientPolicy#ClientPolicy(com.aerospike.client.policy.ClientPolicy, com.aerospike.client.configuration.ConfigurationProvider)} so policies can load and apply config.
+ * {@code
+ * ConfigurationProvider provider = YamlConfigProvider.getConfigProvider("file:///path/to/config.yaml");
+ * ClientPolicy clientPolicy = new ClientPolicy(new ClientPolicy(), provider);
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ *
+ * ConfigurationProvider fromClient = client.getConfigProvider();
+ * if (fromClient != null && fromClient.loadConfiguration()) {
+ * Configuration config = fromClient.fetchConfiguration();
+ * }
+ * }
+ *
+ * @see Configuration
+ * @see YamlConfigProvider
+ * @see com.aerospike.client.policy.ClientPolicy#ClientPolicy(ClientPolicy, ConfigurationProvider)
+ * @see com.aerospike.client.IAerospikeClient#getConfigProvider()
+ */
public interface ConfigurationProvider {
+ /**
+ * Loads or reloads configuration from the provider source.
+ * @return true if configuration was loaded successfully
+ */
boolean loadConfiguration();
+ /**
+ * Returns the current static and dynamic configuration snapshot.
+ * @return configuration (must not be null)
+ */
Configuration fetchConfiguration();
+
+ /**
+ * Returns the dynamic part of configuration (for runtime updates).
+ * @return dynamic configuration (must not be null)
+ */
Configuration fetchDynamicConfiguration();
}
diff --git a/client/src/com/aerospike/client/exp/BitExp.java b/client/src/com/aerospike/client/exp/BitExp.java
index a92ad5ab1..c831c37d7 100644
--- a/client/src/com/aerospike/client/exp/BitExp.java
+++ b/client/src/com/aerospike/client/exp/BitExp.java
@@ -23,7 +23,7 @@
import com.aerospike.client.util.Packer;
/**
- * Bit expression generator. See {@link com.aerospike.client.exp.Exp}.
+ * Bit (blob) expression generator for filters and operate; see {@link Exp}.
* {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Expression exp = Exp.build(Exp.eq(BitExp.count(Exp.blobBin("bits"), 0, -1), Exp.val(5)));
+ * Policy policy = new Policy();
+ * policy.filterExp = exp;
+ * Record rec = client.get(policy, key);
+ *
+ * Expression resizeExp = Exp.build(BitExp.resize(Exp.blobBin("a"), 4, BitResizeFlags.DEFAULT));
+ * Record r = client.operate(null, key, ExpOperation.read("a", resizeExp, ExpReadFlags.DEFAULT));
+ * }
+ *
+ * @see Exp
+ * @see com.aerospike.client.operation.BitResizeFlags
+ * @see com.aerospike.client.operation.BitPolicy
*/
public final class BitExp {
private static final int MODULE = 1;
@@ -66,6 +81,7 @@ public final class BitExp {
* {@code
* // Resize bin "a" and compare bit count
* Exp.eq(
@@ -87,6 +103,7 @@ public static Exp resize(BitPolicy policy, Exp byteSize, int resizeFlags, Exp bi
* {@code
* // Insert bytes into bin "a" and compare bit count
* Exp.eq(
@@ -108,6 +125,7 @@ public static Exp insert(BitPolicy policy, Exp byteOffset, Exp value, Exp bin) {
* {@code
* // Remove bytes from bin "a" and compare bit count
* Exp.eq(
@@ -130,6 +148,7 @@ public static Exp remove(BitPolicy policy, Exp byteOffset, Exp byteSize, Exp bin
* {@code
* // Set bytes in bin "a" and compare bit count
* Exp.eq(
@@ -311,6 +330,7 @@ public static Exp setInt(BitPolicy policy, Exp bitOffset, Exp bitSize, Exp value
* {@code
* // Bin "a" bits = [0b10000000]
* Exp.eq(
@@ -332,6 +352,7 @@ public static Exp get(Exp bitOffset, Exp bitSize, Exp bin) {
* {@code
* // Bin "a" bit count <= 2
* Exp.le(BitExp.count(Exp.val(0), Exp.val(5), Exp.blobBin("a")), Exp.val(2))
@@ -352,6 +373,7 @@ public static Exp count(Exp bitOffset, Exp bitSize, Exp bin) {
* {@code
* // lscan(a) == 5
* Exp.eq(BitExp.lscan(Exp.val(24), Exp.val(8), Exp.val(true), Exp.blobBin("a")), Exp.val(5))
@@ -378,6 +400,7 @@ public static Exp lscan(Exp bitOffset, Exp bitSize, Exp value, Exp bin) {
* {@code
* // rscan(a) == 7
* Exp.eq(BitExp.rscan(Exp.val(32), Exp.val(8), Exp.val(true), Exp.blobBin("a")), Exp.val(7))
@@ -403,6 +426,7 @@ public static Exp rscan(Exp bitOffset, Exp bitSize, Exp value, Exp bin) {
* {@code
* // getInt(a) == 16899
* Exp.eq(BitExp.getInt(Exp.val(8), Exp.val(16), false, Exp.blobBin("a")), Exp.val(16899))
diff --git a/client/src/com/aerospike/client/exp/CdtExp.java b/client/src/com/aerospike/client/exp/CdtExp.java
index b933391e6..23fe9d5e9 100644
--- a/client/src/com/aerospike/client/exp/CdtExp.java
+++ b/client/src/com/aerospike/client/exp/CdtExp.java
@@ -13,12 +13,30 @@
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
* License for the specific language governing permissions and limitations under
* the License.
-*/
+*/
package com.aerospike.client.exp;
import com.aerospike.client.cdt.CTX;
import com.aerospike.client.util.Packer;
+/**
+ * CDT select/modify expressions for use in filters and expressions (nested path select/apply).
+ * {@code
+ * CTX ctx1 = CTX.mapKey(Value.get("book"));
+ * CTX ctx2 = CTX.allChildrenWithFilter(Exp.le(MapExp.getByKey(MapReturnType.VALUE, Exp.Type.FLOAT, Exp.val("price"), Exp.mapLoopVar(LoopVarPart.VALUE)), Exp.val(10.0)));
+ * Exp selectExp = CdtExp.selectByPath(Exp.Type.LIST, Exp.SELECT_VALUE, Exp.mapBin("bin"), ctx1, ctx2);
+ * Policy policy = new Policy();
+ * policy.filterExp = Exp.build(selectExp);
+ * }
+ *
+ * @see Exp
+ * @see com.aerospike.client.cdt.CdtOperation
+ * @see CTX
+ * @see LoopVarPart
+ */
public class CdtExp {
/**
* The module identifier for CDT expressions.
diff --git a/client/src/com/aerospike/client/exp/Exp.java b/client/src/com/aerospike/client/exp/Exp.java
index 5b3439b03..ceacea999 100644
--- a/client/src/com/aerospike/client/exp/Exp.java
+++ b/client/src/com/aerospike/client/exp/Exp.java
@@ -23,7 +23,32 @@
import com.aerospike.client.util.Packer;
/**
- * Expression generator.
+ * Expression generator for filters, queries, and operate read/write.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Key key = new Key("ns", "set", "mykey");
+ *
+ * WritePolicy policy = new WritePolicy();
+ * policy.filterExp = Exp.build(Exp.eq(Exp.intBin("A"), Exp.val(1)));
+ * client.put(policy, key, new Bin("A", 3));
+ *
+ * Policy readPolicy = new Policy();
+ * readPolicy.filterExp = Exp.build(Exp.gt(Exp.intBin("score"), Exp.val(100)));
+ * Record rec = client.get(readPolicy, key);
+ *
+ * Expression exp = Exp.build(Exp.add(Exp.intBin("A"), Exp.val(4)));
+ * Record rec2 = client.operate(null, key, ExpOperation.read("EV", exp, ExpReadFlags.DEFAULT));
+ * }
+ *
+ * @see Expression
+ * @see ExpOperation
+ * @see ListExp
+ * @see MapExp
+ * @see CdtExp
+ * @see com.aerospike.client.policy.WritePolicy#filterExp
*/
public abstract class Exp {
/**
@@ -1228,7 +1253,7 @@ public static Exp hllLoopVar(LoopVarPart part) {
/**
* Create expression that references a built-in variable.
* Requires server version 8.1.1
- *
+ * {@code
* Exp.intLoopVar(LoopVarPart.MAP_KEY)
* }
@@ -1240,7 +1265,7 @@ public static Exp intLoopVar(LoopVarPart part) {
/**
* Create expression that references a built-in variable.
* Requires server version 8.1.1
- *
+ * {@code
* Exp.floatLoopVar(LoopVarPart.MAP_KEY)
* }
@@ -1252,7 +1277,7 @@ public static Exp floatLoopVar(LoopVarPart part) {
/**
* Create expression that references a built-in variable.
* Requires server version 8.1.1
- *
+ * {@code
* Exp.listLoopVar(LoopVarPart.MAP_KEY)
* }
@@ -1264,7 +1289,7 @@ public static Exp listLoopVar(LoopVarPart part) {
/**
* Create expression that references a built-in variable.
* Requires server version 8.1.1
- *
+ * {@code
* Exp.mapLoopVar(LoopVarPart.MAP_KEY)
* }
@@ -1276,7 +1301,7 @@ public static Exp mapLoopVar(LoopVarPart part) {
/**
* Create expression that references a built-in variable.
* Requires server version 8.1.1
- *
+ * {@code
* Exp.blobLoopVar(LoopVarPart.MAP_KEY)
* }
@@ -1288,7 +1313,7 @@ public static Exp blobLoopVar(LoopVarPart part) {
/**
* Create expression that references a built-in variable.
* Requires server version 8.1.1
- *
+ * {@code
* Exp.nilLoopVar(LoopVarPart.MAP_KEY)
* }
@@ -1300,7 +1325,7 @@ public static Exp nilLoopVar(LoopVarPart part) {
/**
* Create expression that references a built-in variable.
* Requires server version 8.1.1
- *
+ * {@code
* Exp.geoJsonLoopVar(LoopVarPart.MAP_KEY)
* }
diff --git a/client/src/com/aerospike/client/exp/ExpOperation.java b/client/src/com/aerospike/client/exp/ExpOperation.java
index 5633e2c49..47c70a3f1 100644
--- a/client/src/com/aerospike/client/exp/ExpOperation.java
+++ b/client/src/com/aerospike/client/exp/ExpOperation.java
@@ -21,7 +21,31 @@
import com.aerospike.client.util.Packer;
/**
- * Expression operations.
+ * Read and write operations that evaluate expressions on the server (server 5.6+).
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Key key = new Key("ns", "set", "mykey");
+ * client.put(null, key, new Bin("A", 1), new Bin("D", 2));
+ *
+ * Expression wexp = Exp.build(Exp.intBin("D"));
+ * Expression rexp = Exp.build(Exp.add(Exp.intBin("A"), Exp.val(4)));
+ * Record rec = client.operate(null, key,
+ * ExpOperation.write("D", wexp, ExpWriteFlags.DEFAULT),
+ * ExpOperation.read("EV", rexp, ExpReadFlags.DEFAULT));
+ * long ev = rec.getLong("EV");
+ *
+ * Expression writeExp = Exp.build(Exp.add(Exp.intBin("A"), Exp.val(10)));
+ * client.operate(null, key, ExpOperation.write("C", writeExp, ExpWriteFlags.DEFAULT));
+ * }
+ *
+ * @see Exp
+ * @see Expression
+ * @see ExpReadFlags
+ * @see ExpWriteFlags
+ * @see com.aerospike.client.AerospikeClient#operate
*/
public final class ExpOperation {
/**
diff --git a/client/src/com/aerospike/client/exp/ExpReadFlags.java b/client/src/com/aerospike/client/exp/ExpReadFlags.java
index d59449550..078341c85 100644
--- a/client/src/com/aerospike/client/exp/ExpReadFlags.java
+++ b/client/src/com/aerospike/client/exp/ExpReadFlags.java
@@ -17,16 +17,21 @@
package com.aerospike.client.exp;
/**
- * Expression read flags.
+ * Flags for {@link ExpOperation#read}; control behavior when expression evaluation fails (e.g. missing bin).
+ * {@code
+ * Record rec = client.operate(null, key, ExpOperation.read("EV", exp, ExpReadFlags.DEFAULT));
+ * Record rec2 = client.operate(null, key, ExpOperation.read("EV", exp, ExpReadFlags.EVAL_NO_FAIL));
+ * }
+ *
+ * @see ExpOperation#read
*/
public final class ExpReadFlags {
- /**
- * Default.
- */
+ /** Default: fail if expression cannot be evaluated (e.g. bin missing). */
public static final int DEFAULT = 0;
- /**
- * Ignore failures caused by the expression resolving to unknown or a non-bin type.
- */
+ /** Ignore failures when expression resolves to unknown or non-bin type; record still returned. */
public static final int EVAL_NO_FAIL = 16;
}
diff --git a/client/src/com/aerospike/client/exp/ExpWriteFlags.java b/client/src/com/aerospike/client/exp/ExpWriteFlags.java
index 2864a9738..571ce8bb7 100644
--- a/client/src/com/aerospike/client/exp/ExpWriteFlags.java
+++ b/client/src/com/aerospike/client/exp/ExpWriteFlags.java
@@ -17,11 +17,15 @@
package com.aerospike.client.exp;
/**
- * Expression write bit flags. Use BITWISE OR to combine flags. Example:
- *
- * {@code
+ * Flags for {@link ExpOperation#write}; combine with BITWISE OR. Control create/update and failure behavior.
+ * {@code
* int flags = ExpWriteFlags.CREATE_ONLY | ExpWriteFlags.POLICY_NO_FAIL;
+ * client.operate(null, key, ExpOperation.write("bin", exp, flags));
* }
+ *
+ * @see ExpOperation#write
*/
public final class ExpWriteFlags {
/**
diff --git a/client/src/com/aerospike/client/exp/Expression.java b/client/src/com/aerospike/client/exp/Expression.java
index aa3111a92..f2fe4370f 100644
--- a/client/src/com/aerospike/client/exp/Expression.java
+++ b/client/src/com/aerospike/client/exp/Expression.java
@@ -24,7 +24,23 @@
import com.aerospike.client.util.Packer;
/**
- * Packed expression byte instructions.
+ * Packed expression built from {@link Exp}; use in filter policies, query filters, and {@link ExpOperation}.
+ * {@code
+ * Expression exp = Exp.build(Exp.eq(Exp.intBin("A"), Exp.val(1)));
+ * WritePolicy policy = new WritePolicy();
+ * policy.filterExp = exp;
+ * client.put(policy, key, new Bin("A", 2));
+ *
+ * Expression readExp = Exp.build(Exp.add(Exp.intBin("A"), Exp.val(10)));
+ * Record rec = client.operate(null, key, ExpOperation.read("result", readExp, ExpReadFlags.DEFAULT));
+ * long result = rec.getLong("result");
+ * }
+ *
+ * @see Exp
+ * @see ExpOperation
*/
public final class Expression implements Serializable {
private static final long serialVersionUID = 1L;
diff --git a/client/src/com/aerospike/client/exp/HLLExp.java b/client/src/com/aerospike/client/exp/HLLExp.java
index 999256eb4..9faf0b7e6 100644
--- a/client/src/com/aerospike/client/exp/HLLExp.java
+++ b/client/src/com/aerospike/client/exp/HLLExp.java
@@ -20,12 +20,27 @@
import com.aerospike.client.util.Pack;
/**
- * HyperLogLog (HLL) expression generator. See {@link com.aerospike.client.exp.Exp}.
+ * HyperLogLog (HLL) expression generator for filters and operate; see {@link Exp}.
* {@code
+ * Expression exp = Exp.build(Exp.ge(HLLExp.count(Exp.hllBin("h")), Exp.val(10)));
+ * Policy policy = new Policy();
+ * policy.filterExp = exp;
+ * Record rec = client.get(policy, key);
+ *
+ * Expression countExp = Exp.build(HLLExp.count(Exp.hllBin("h")));
+ * Record r = client.operate(null, key, ExpOperation.read("cnt", countExp, ExpReadFlags.DEFAULT));
+ * long cnt = r.getLong("cnt");
+ * }
+ *
+ * @see Exp
+ * @see com.aerospike.client.operation.HLLOperation
+ * @see com.aerospike.client.operation.HLLPolicy
*/
public final class HLLExp {
private static final int MODULE = 2;
@@ -67,7 +82,7 @@ public static Exp init(HLLPolicy policy, Exp indexBitCount, Exp minHashBitCount,
/**
* Create expression that adds list values to a HLL set and returns HLL set.
* The function assumes HLL bin already exists.
- *
+ * {@code
* // Add values to HLL bin "a" and check count > 7
* Exp.gt(
@@ -87,7 +102,7 @@ public static Exp add(HLLPolicy policy, Exp list, Exp bin) {
/**
* Create expression that adds values to a HLL set and returns HLL set.
* If HLL bin does not exist, use indexBitCount to create HLL bin.
- *
+ * {@code
* // Add values to HLL bin "a" and check count > 7
* Exp.gt(
@@ -108,7 +123,7 @@ public static Exp add(HLLPolicy policy, Exp list, Exp indexBitCount, Exp bin) {
/**
* Create expression that adds values to a HLL set and returns HLL set. If HLL bin does not
* exist, use indexBitCount and minHashBitCount to create HLL set.
- *
+ * {@code
* // Add values to HLL bin "a" and check count > 7
* Exp.gt(
@@ -131,7 +146,7 @@ public static Exp add(HLLPolicy policy, Exp list, Exp indexBitCount, Exp minHash
/**
* Create expression that returns estimated number of elements in the HLL bin.
- *
+ * {@code
* // HLL bin "a" count > 7
* Exp.gt(HLLExp.getCount(Exp.hllBin("a")), Exp.val(7))
@@ -145,7 +160,7 @@ public static Exp getCount(Exp bin) {
/**
* Create expression that returns a HLL object that is the union of all specified HLL objects
* in the list with the HLL bin.
- *
+ * {@code
* // Union of HLL bins "a" and "b"
* HLLExp.getUnion(Exp.hllBin("a"), Exp.hllBin("b"))
@@ -162,7 +177,7 @@ public static Exp getUnion(Exp list, Exp bin) {
/**
* Create expression that returns estimated number of elements that would be contained by
* the union of these HLL objects.
- *
+ * {@code
* // Union count of HLL bins "a" and "b"
* HLLExp.getUnionCount(Exp.hllBin("a"), Exp.hllBin("b"))
@@ -179,7 +194,7 @@ public static Exp getUnionCount(Exp list, Exp bin) {
/**
* Create expression that returns estimated number of elements that would be contained by
* the intersection of these HLL objects.
- *
+ * {@code
* // Intersect count of HLL bins "a" and "b"
* HLLExp.getIntersectCount(Exp.hllBin("a"), Exp.hllBin("b"))
@@ -196,7 +211,7 @@ public static Exp getIntersectCount(Exp list, Exp bin) {
/**
* Create expression that returns estimated similarity of these HLL objects as a
* 64 bit float.
- *
+ * {@code
* // Similarity of HLL bins "a" and "b" >= 0.75
* Exp.ge(HLLExp.getSimilarity(Exp.hllBin("a"), Exp.hllBin("b")), Exp.val(0.75))
@@ -210,7 +225,7 @@ public static Exp getSimilarity(Exp list, Exp bin) {
/**
* Create expression that returns indexBitCount and minHashBitCount used to create HLL bin
* in a list of longs. list[0] is indexBitCount and list[1] is minHashBitCount.
- *
+ * {@code
* // Bin "a" indexBitCount < 10
* Exp.lt(
@@ -226,7 +241,7 @@ public static Exp describe(Exp bin) {
/**
* Create expression that returns one if HLL bin may contain all items in the list.
- *
+ * {@code
* // Bin "a" may contain value "x"
* ArrayList
- *
- *
- *
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Key key = new Key("ns", "set", "mykey");
+ *
+ * // Filter by list size (e.g. list at CTX listIndex 4 has size 6)
+ * Policy policy = new Policy();
+ * policy.filterExp = Exp.build(Exp.eq(ListExp.size(Exp.listBin("A"), CTX.listIndex(4)), Exp.val(6)));
+ * Record rec = client.get(policy, key);
+ *
+ * // Index: first (0), last (-1), range second+third (1, count 2), last three (-3, count 3), -5 count 4
+ * Exp byIndex0 = ListExp.getByIndex(ListReturnType.VALUE, Exp.Type.INT, Exp.val(0), Exp.listBin("bin"));
+ * Exp byIndexLast = ListExp.getByIndex(ListReturnType.VALUE, Exp.Type.INT, Exp.val(-1), Exp.listBin("bin"));
+ * Exp byIndexRange = ListExp.getByIndexRange(ListReturnType.VALUE, Exp.val(1), Exp.val(2), Exp.listBin("bin"));
+ * Exp lastThree = ListExp.getByIndexRange(ListReturnType.VALUE, Exp.val(-3), Exp.val(3), Exp.listBin("bin"));
+ * Exp rangeFromFifthToLast = ListExp.getByIndexRange(ListReturnType.VALUE, Exp.val(-5), Exp.val(4), Exp.listBin("bin"));
+ *
+ * // List modify (returns bin value)
+ * Expression exp = Exp.build(ListExp.getByIndex(ListReturnType.VALUE, Exp.Type.INT, Exp.val(0), Exp.listBin("bin")));
+ * Record r = client.operate(null, key, ExpOperation.read("first", exp, ExpReadFlags.DEFAULT));
+ *
+ * // Nested: size of last list (bin = [[7,9,5],[1,2,3],[6,5,4,1]] -> result 4)
+ * Exp sizeOfLastList = ListExp.size(Exp.listBin("bin"), CTX.listIndex(-1));
+ * }
+ *
+ * @see Exp
+ * @see MapExp
+ * @see com.aerospike.client.cdt.CTX
+ * @see com.aerospike.client.cdt.ListReturnType
*/
public final class ListExp {
private static final int MODULE = 0;
@@ -286,7 +298,7 @@ public static Exp removeByRankRange(int returnType, Exp rank, Exp count, Exp bin
/**
* Create expression that returns list size.
- *
+ * {@code
* // List bin "a" size > 7
* Exp.gt(ListExp.size(Exp.listBin("a")), Exp.val(7))
@@ -300,7 +312,7 @@ public static Exp size(Exp bin, CTX... ctx) {
/**
* Create expression that selects list items identified by value and returns selected
* data specified by returnType.
- *
+ * {@code
* // List bin "a" contains at least one item == "abc"
* ListExp.getByValue(ListReturnType.EXISTS, Exp.val("abc"), Exp.listBin("a"))
@@ -319,7 +331,7 @@ public static Exp getByValue(int returnType, Exp value, Exp bin, CTX... ctx) {
/**
* Create expression that selects list items identified by value range and returns selected data
* specified by returnType.
- *
+ * {@code
* // List bin "a" items >= 10 && items < 20
* ListExp.getByValueRange(ListReturnType.VALUE, Exp.val(10), Exp.val(20), Exp.listBin("a"))
@@ -388,7 +400,7 @@ public static Exp getByValueRelativeRankRange(int returnType, Exp value, Exp ran
/**
* Create expression that selects list item identified by index and returns
* selected data specified by returnType.
- *
+ * {@code
* // a[3] == 5
* Exp.eq(
@@ -428,7 +440,7 @@ public static Exp getByIndexRange(int returnType, Exp index, Exp count, Exp bin,
/**
* Create expression that selects list item identified by rank and returns selected
* data specified by returnType.
- *
+ * {@code
* // Player with lowest score.
* ListExp.getByRank(ListReturnType.VALUE, Type.STRING, Exp.val(0), Exp.listBin("a"))
diff --git a/client/src/com/aerospike/client/exp/LoopVarPart.java b/client/src/com/aerospike/client/exp/LoopVarPart.java
index bf0baa921..98a98a162 100644
--- a/client/src/com/aerospike/client/exp/LoopVarPart.java
+++ b/client/src/com/aerospike/client/exp/LoopVarPart.java
@@ -17,8 +17,19 @@
package com.aerospike.client.exp;
/**
- * Loop variable parts for expression loop variables.
- * Used to specify which part of a loop variable to access during iteration.
+ * Which part of a loop variable to use in iteration expressions (e.g. in {@link com.aerospike.client.cdt.CTX#allChildrenWithFilter(Exp)} and CDT apply).
+ * {@code
+ * CTX ctx = CTX.allChildrenWithFilter(Exp.eq(Exp.stringLoopVar(LoopVarPart.MAP_KEY), Exp.val("title")));
+ * CTX ctx2 = CTX.allChildrenWithFilter(Exp.le(MapExp.getByKey(MapReturnType.VALUE, Exp.Type.FLOAT, Exp.val("price"), Exp.mapLoopVar(LoopVarPart.VALUE)), Exp.val(10.0)));
+ * }
+ *
+ * @see Exp#mapLoopVar
+ * @see Exp#stringLoopVar
+ * @see com.aerospike.client.cdt.CTX#allChildrenWithFilter(Exp)
+ * @see com.aerospike.client.cdt.CdtOperation#modifyByPath
*/
public enum LoopVarPart {
/**
diff --git a/client/src/com/aerospike/client/exp/MapExp.java b/client/src/com/aerospike/client/exp/MapExp.java
index 3e400a057..9dfcd8382 100644
--- a/client/src/com/aerospike/client/exp/MapExp.java
+++ b/client/src/com/aerospike/client/exp/MapExp.java
@@ -23,58 +23,66 @@
import com.aerospike.client.util.Pack;
/**
- * Map expression generator. See {@link com.aerospike.client.exp.Exp}.
+ * Map expression generator for filters and operate; see {@link Exp}.
*
- *
- *
- *
- *
- *
- *
- *
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Key key = new Key("ns", "set", "mykey");
+ *
+ * // Filter by map bin (key types: String, Integer, byte[])
+ * java.util.Map
+ *
+ * @see Exp
+ * @see ListExp
+ * @see LoopVarPart
+ * @see com.aerospike.client.cdt.CTX
+ * @see com.aerospike.client.cdt.MapReturnType
*/
public final class MapExp {
private static final int MODULE = 0;
@@ -113,7 +121,7 @@ public final class MapExp {
/**
* Create expression that writes key/value item to a map bin. The 'bin' expression should either
* reference an existing map bin or be a expression that returns a map.
- *
+ * {@code
* // Add entry{11,22} to existing map bin.
* Expression e = Exp.build(MapExp.put(MapPolicy.Default, Exp.val(11), Exp.val(22), Exp.mapBin(binName)));
@@ -377,7 +385,7 @@ public static Exp removeByRankRange(int returnType, Exp rank, Exp count, Exp bin
/**
* Create expression that returns list size.
- *
+ * {@code
* // Map bin "a" size > 7
* Exp.gt(MapExp.size(Exp.mapBin("a")), Exp.val(7))
@@ -391,7 +399,7 @@ public static Exp size(Exp bin, CTX... ctx) {
/**
* Create expression that selects map item identified by key and returns selected data
* specified by returnType.
- *
+ * {@code
* // Map bin "a" contains key "B"
* MapExp.getByKey(MapReturnType.EXISTS, Exp.Type.BOOL, Exp.val("B"), Exp.mapBin("a"))
@@ -470,7 +478,7 @@ public static Exp getByKeyRelativeIndexRange(int returnType, Exp key, Exp index,
/**
* Create expression that selects map items identified by value and returns selected data
* specified by returnType.
- *
+ * {@code
* // Map bin "a" contains value "BBB"
* MapExp.getByValue(MapReturnType.EXISTS, Exp.val("BBB"), Exp.mapBin("a"))
diff --git a/client/src/com/aerospike/client/listener/AbortListener.java b/client/src/com/aerospike/client/listener/AbortListener.java
index 9ccabd7f2..20d39b84d 100644
--- a/client/src/com/aerospike/client/listener/AbortListener.java
+++ b/client/src/com/aerospike/client/listener/AbortListener.java
@@ -19,11 +19,29 @@
import com.aerospike.client.AbortStatus;
/**
- * Asynchronous result notifications for transaction aborts.
+ * Async callback for transaction abort; receives {@link com.aerospike.client.AbortStatus} on success.
+ * {@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ *
+ * client.abort(loop, new AbortListener() {
+ * public void onSuccess(AbortStatus status) { }
+ * }, txn);
+ * }
+ *
+ * @see com.aerospike.client.AbortStatus
+ * @see com.aerospike.client.IAerospikeClient#abort
+ * @see com.aerospike.client.Txn
*/
public interface AbortListener {
/**
- * This method is called when the abort succeeded or will succeed.
+ * Called when the abort completes successfully.
+ * @param status abort status (must not be null)
*/
void onSuccess(AbortStatus status);
}
diff --git a/client/src/com/aerospike/client/listener/BatchListListener.java b/client/src/com/aerospike/client/listener/BatchListListener.java
index a72e6746b..aad21ddf7 100644
--- a/client/src/com/aerospike/client/listener/BatchListListener.java
+++ b/client/src/com/aerospike/client/listener/BatchListListener.java
@@ -22,20 +22,35 @@
import com.aerospike.client.BatchRead;
/**
- * Asynchronous result notifications for batch get commands with variable bins per key.
- * The result is sent in a single list.
+ * Async callback for batch get with variable bins; receives a single list of {@link com.aerospike.client.BatchRead} results.
+ * {@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * BatchRead[] batchReads = new BatchRead[] { new BatchRead(new Key("ns", "set", "k1"), new String[] { "bin1" }) };
+ *
+ * client.get(loop, new BatchListListener() {
+ * public void onSuccess(List records) { }
+ * public void onFailure(AerospikeException e) { }
+ * }, new BatchPolicy(), batchReads);
+ * }
+ *
+ * @see com.aerospike.client.IAerospikeClient#get
*/
public interface BatchListListener {
/**
- * This method is called when the command completes successfully.
- *
- * @param records record instances, {@link com.aerospike.client.BatchRecord#record}
- * will be null if the key is not found
+ * Called when the batch get completes; list order matches input BatchRead array.
+ * @param records list of BatchRead; record is null when key not found
*/
public void onSuccess(List{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ *
+ * client.operate(loop, new BatchOperateListListener() {
+ * public void onSuccess(List records, boolean status) { }
+ * public void onFailure(AerospikeException e) { }
+ * }, new BatchPolicy(), batchRecordList);
+ * }
+ *
+ * @see com.aerospike.client.IAerospikeClient#operate(com.aerospike.client.async.EventLoop, BatchOperateListListener, com.aerospike.client.policy.BatchPolicy, java.util.List)
*/
public interface BatchOperateListListener {
/**
- * This method is called when the command completes successfully.
- *
- * @param records record instances, {@link com.aerospike.client.BatchRecord#record}
- * will be null if an error occurred for that key.
- * @param status true if all records returned success.
+ * Called when the batch operate completes; list order matches input.
+ * @param records list of BatchRecord; record is null when that key had an error
+ * @param status true if all records succeeded
*/
public void onSuccess(List{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * BatchRecord[] records = new BatchRecord[] { new BatchWrite(...) };
+ *
+ * client.operate(loop, new BatchRecordArrayListener() {
+ * public void onSuccess(BatchRecord[] records, boolean status) { }
+ * public void onFailure(BatchRecord[] records, AerospikeException e) { }
+ * }, new BatchPolicy(), records);
+ * }
+ *
+ * @see com.aerospike.client.BatchRecord
+ * @see com.aerospike.client.IAerospikeClient#operate(com.aerospike.client.async.EventLoop, BatchRecordArrayListener, com.aerospike.client.policy.BatchPolicy, com.aerospike.client.BatchRecord[])
*/
public interface BatchRecordArrayListener {
/**
- * This method is called when the command completes successfully.
- * The returned record array is in positional order with the original key array order.
- *
- * @param records record instances, always populated.
- * @param status true if all records returned success.
+ * Called when the batch operate completes; one entry per input record, in order.
+ * @param records batch records, always populated (must not be null)
+ * @param status true if all records succeeded
*/
public void onSuccess(BatchRecord[] records, boolean status);
/**
- * This method is called when one or more keys fail.
- *
- * @param records record instances, always populated. {@link com.aerospike.client.BatchRecord#resultCode}
- * indicates if an error occurred for each record instance.
- * @param ae error that occurred
+ * Called when the batch fails; records may still be populated with per-key results.
+ * @param records batch records (must not be null); check {@link com.aerospike.client.BatchRecord#resultCode}
+ * @param ae exception cause of failure wrapped into Aerospike exception
*/
public void onFailure(BatchRecord[] records, AerospikeException ae);
}
diff --git a/client/src/com/aerospike/client/listener/BatchRecordSequenceListener.java b/client/src/com/aerospike/client/listener/BatchRecordSequenceListener.java
index 44cfb4e43..1bbbc300c 100644
--- a/client/src/com/aerospike/client/listener/BatchRecordSequenceListener.java
+++ b/client/src/com/aerospike/client/listener/BatchRecordSequenceListener.java
@@ -20,26 +20,40 @@
import com.aerospike.client.BatchRecord;
/**
- * Asynchronous result notifications for batch operate commands.
- * The results are sent one record at a time.
+ * Async callback for batch operate; results delivered one {@link com.aerospike.client.BatchRecord} at a time via {@link #onRecord}, then {@link #onSuccess} or {@link #onFailure}.
+ * {@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * BatchRecord[] records = new BatchRecord[] { new BatchWrite(...) };
+ *
+ * client.operate(loop, new BatchRecordSequenceListener() {
+ * public void onRecord(BatchRecord record, int index) { }
+ * public void onSuccess() { }
+ * public void onFailure(AerospikeException e) { }
+ * }, new BatchPolicy(), records);
+ * }
+ *
+ * @see com.aerospike.client.IAerospikeClient#operate
*/
public interface BatchRecordSequenceListener {
/**
- * This method is called when a record is received from the server.
- * The receive sequence is not ordered.
- *
- * @param record record instance
- * @param index index offset into the original BatchRecord array.
+ * Called for each batch record when received; order is not guaranteed.
+ * @param record batch record (must not be null)
+ * @param index index into the original BatchRecord array
*/
public void onRecord(BatchRecord record, int index);
- /**
- * This method is called when the command completes successfully.
- */
+ /** Called when the batch operate completes successfully. */
public void onSuccess();
/**
- * This method is called when the command fails.
+ * Called when the batch operate fails.
+ * @param ae exception cause of failure wrapped into Aerospike exception
*/
public void onFailure(AerospikeException ae);
}
diff --git a/client/src/com/aerospike/client/listener/BatchSequenceListener.java b/client/src/com/aerospike/client/listener/BatchSequenceListener.java
index 401b617bc..e5387b961 100644
--- a/client/src/com/aerospike/client/listener/BatchSequenceListener.java
+++ b/client/src/com/aerospike/client/listener/BatchSequenceListener.java
@@ -20,26 +20,39 @@
import com.aerospike.client.BatchRead;
/**
- * Asynchronous result notifications for batch get commands with variable bins per key.
- * The results are sent one batch record at a time.
+ * Async callback for batch get with variable bins; results delivered one {@link com.aerospike.client.BatchRead} at a time via {@link #onRecord}, then {@link #onSuccess} or {@link #onFailure}.
+ * {@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * BatchRead[] batchReads = new BatchRead[] { new BatchRead(new Key("ns", "set", "k1"), new String[] { "bin1" }) };
+ *
+ * client.get(loop, new BatchSequenceListener() {
+ * public void onRecord(BatchRead record) { }
+ * public void onSuccess() { }
+ * public void onFailure(AerospikeException e) { }
+ * }, new BatchPolicy(), batchReads);
+ * }
+ *
+ * @see com.aerospike.client.IAerospikeClient#get
*/
public interface BatchSequenceListener {
/**
- * This method is called when an asynchronous batch record is received from the server.
- * The receive sequence is not ordered.
- *
- * @param record record instance, {@link com.aerospike.client.BatchRecord#record}
- * will be null if the key is not found
+ * Called for each batch read when received; order is not guaranteed.
+ * @param record batch read; {@link com.aerospike.client.BatchRead#record} is null if key not found
*/
public void onRecord(BatchRead record);
- /**
- * This method is called when the command completes successfully.
- */
+ /** Called when the batch get completes successfully. */
public void onSuccess();
/**
- * This method is called when the command fails.
+ * Called when the batch get fails.
+ * @param ae exception cause of failure wrapped into Aerospike exception
*/
public void onFailure(AerospikeException ae);
}
diff --git a/client/src/com/aerospike/client/listener/ClusterStatsListener.java b/client/src/com/aerospike/client/listener/ClusterStatsListener.java
index 45356638c..b590315e2 100644
--- a/client/src/com/aerospike/client/listener/ClusterStatsListener.java
+++ b/client/src/com/aerospike/client/listener/ClusterStatsListener.java
@@ -20,16 +20,35 @@
import com.aerospike.client.cluster.ClusterStats;
/**
- * Asynchronous result notifications for cluster statistics.
+ * Async callback for cluster statistics; receives {@link com.aerospike.client.cluster.ClusterStats} or exception.
+ * {@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ *
+ * client.getClusterStats(loop, new ClusterStatsListener() {
+ * public void onSuccess(ClusterStats stats) { }
+ * public void onFailure(AerospikeException e) { }
+ * });
+ * }
+ *
+ * @see com.aerospike.client.cluster.ClusterStats
+ * @see com.aerospike.client.IAerospikeClient#getClusterStats
*/
public interface ClusterStatsListener {
/**
- * This method is called when command completes successfully.
+ * Called when the cluster stats request completes successfully.
+ * @param stats cluster statistics (must not be null)
*/
public void onSuccess(ClusterStats stats);
/**
- * This method is called when command fails.
+ * Called when the cluster stats request fails.
+ * @param ae exception cause of failure wrapped into Aerospike exception
*/
public void onFailure(AerospikeException ae);
}
diff --git a/client/src/com/aerospike/client/listener/CommitListener.java b/client/src/com/aerospike/client/listener/CommitListener.java
index 358f89cde..724773666 100644
--- a/client/src/com/aerospike/client/listener/CommitListener.java
+++ b/client/src/com/aerospike/client/listener/CommitListener.java
@@ -20,16 +20,36 @@
import com.aerospike.client.CommitStatus;
/**
- * Asynchronous result notifications for transaction commits.
+ * Async callback for transaction commit; receives {@link com.aerospike.client.CommitStatus} or exception.
+ * {@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ *
+ * client.commit(loop, new CommitListener() {
+ * public void onSuccess(CommitStatus status) { }
+ * public void onFailure(AerospikeException.Commit e) { }
+ * }, new CommitPolicy(), txn);
+ * }
+ *
+ * @see com.aerospike.client.CommitStatus
+ * @see com.aerospike.client.IAerospikeClient#commit
+ * @see com.aerospike.client.Txn
*/
public interface CommitListener {
/**
- * This method is called when the records are verified and the commit succeeded or will succeed.
+ * Called when the commit completes (verified or will succeed).
+ * @param status commit status (must not be null)
*/
void onSuccess(CommitStatus status);
/**
- * This method is called when the commit fails.
+ * Called when the commit fails.
+ * @param ae commit exception cause of failure wrapped into Aerospike exception
*/
void onFailure(AerospikeException.Commit ae);
}
diff --git a/client/src/com/aerospike/client/listener/DeleteListener.java b/client/src/com/aerospike/client/listener/DeleteListener.java
index 1f345f94a..0ebe67fe2 100644
--- a/client/src/com/aerospike/client/listener/DeleteListener.java
+++ b/client/src/com/aerospike/client/listener/DeleteListener.java
@@ -20,19 +20,35 @@
import com.aerospike.client.Key;
/**
- * Asynchronous result notifications for delete commands.
+ * Async callback for delete; receives key, whether record existed, or exception.
+ * {@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ *
+ * client.delete(loop, new DeleteListener() {
+ * public void onSuccess(Key key, boolean existed) { }
+ * public void onFailure(AerospikeException e) { }
+ * }, new WritePolicy(), key);
+ * }
+ *
+ * @see com.aerospike.client.IAerospikeClient#delete
*/
public interface DeleteListener {
/**
- * This method is called when an asynchronous delete command completes successfully.
- *
- * @param key unique record identifier
- * @param existed whether record existed on server before deletion
+ * Called when the delete completes successfully.
+ * @param key record key (must not be null)
+ * @param existed true if the record existed before deletion
*/
public void onSuccess(Key key, boolean existed);
/**
- * This method is called when an asynchronous delete command fails.
+ * Called when the delete fails.
+ * @param ae exception cause of failure wrapped into Aerospike exception
*/
public void onFailure(AerospikeException ae);
}
diff --git a/client/src/com/aerospike/client/listener/ExecuteListener.java b/client/src/com/aerospike/client/listener/ExecuteListener.java
index 6eea971e6..9670cb0ed 100644
--- a/client/src/com/aerospike/client/listener/ExecuteListener.java
+++ b/client/src/com/aerospike/client/listener/ExecuteListener.java
@@ -20,19 +20,35 @@
import com.aerospike.client.Key;
/**
- * Asynchronous result notifications for execute commands.
+ * Async callback for execute (UDF); receives key, return value, or exception.
+ * {@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ *
+ * client.execute(loop, new ExecuteListener() {
+ * public void onSuccess(Key key, Object obj) { }
+ * public void onFailure(AerospikeException e) { }
+ * }, new Policy(), key, "module", "function", null);
+ * }
+ *
+ * @see com.aerospike.client.IAerospikeClient#execute
*/
public interface ExecuteListener {
/**
- * This method is called when an asynchronous execute command completes successfully.
- *
- * @param key unique record identifier
- * @param obj returned object
+ * Called when the execute completes successfully.
+ * @param key record key (must not be null)
+ * @param obj value returned by the UDF, or null
*/
public void onSuccess(Key key, Object obj);
/**
- * This method is called when an asynchronous execute command fails.
+ * Called when the execute fails.
+ * @param ae exception cause of failure wrapped into Aerospike exception
*/
public void onFailure(AerospikeException ae);
}
diff --git a/client/src/com/aerospike/client/listener/ExistsArrayListener.java b/client/src/com/aerospike/client/listener/ExistsArrayListener.java
index b5b3dc486..d83404d6f 100644
--- a/client/src/com/aerospike/client/listener/ExistsArrayListener.java
+++ b/client/src/com/aerospike/client/listener/ExistsArrayListener.java
@@ -20,23 +20,37 @@
import com.aerospike.client.Key;
/**
- * Asynchronous result notifications for batch exists commands.
- * The result is sent in a single array.
+ * Async callback for batch exists; receives keys and existence flags in one array (same order as input keys).
+ * {@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * Key[] keys = new Key[] { new Key("ns", "set", "k1") };
+ *
+ * client.exists(loop, new ExistsArrayListener() {
+ * public void onSuccess(Key[] keys, boolean[] exists) { }
+ * public void onFailure(AerospikeException e) { }
+ * }, new BatchPolicy(), keys);
+ * }
+ *
+ * @see com.aerospike.client.IAerospikeClient#exists(com.aerospike.client.async.EventLoop, ExistsArrayListener, com.aerospike.client.policy.BatchPolicy, com.aerospike.client.Key[])
+ * @see com.aerospike.client.AerospikeException.BatchExists
*/
public interface ExistsArrayListener {
/**
- * This method is called when the command completes successfully.
- * The returned boolean array is in positional order with the original key array order.
- *
- * @param keys unique record identifiers
- * @param exists whether keys exists on server
+ * Called when the batch exists completes; arrays are in same order as the key array.
+ * @param keys original keys (must not be null)
+ * @param exists existence per key (must not be null)
*/
public void onSuccess(Key[] keys, boolean[] exists);
/**
- * This method is called when the command fails. The AerospikeException is likely to be
- * {@link com.aerospike.client.AerospikeException.BatchExists} which contains results
- * for keys that did complete.
+ * Called when the batch fails; may be {@link com.aerospike.client.AerospikeException.BatchExists} with partial results.
+ * @param ae exception cause of failure wrapped into Aerospike exception
*/
public void onFailure(AerospikeException ae);
}
diff --git a/client/src/com/aerospike/client/listener/ExistsListener.java b/client/src/com/aerospike/client/listener/ExistsListener.java
index 81354007a..41486e24d 100644
--- a/client/src/com/aerospike/client/listener/ExistsListener.java
+++ b/client/src/com/aerospike/client/listener/ExistsListener.java
@@ -20,19 +20,36 @@
import com.aerospike.client.Key;
/**
- * Asynchronous result notifications for exists commands.
+ * Async callback for exists; receives key, existence flag, or exception.
+ * {@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ *
+ * client.exists(loop, new ExistsListener() {
+ * public void onSuccess(Key key, boolean exists) { }
+ * public void onFailure(AerospikeException e) { }
+ * }, new Policy(), key);
+ * }
+ *
+ * @see com.aerospike.client.IAerospikeClient#exists
+ * @see com.aerospike.client.IAerospikeClient#touched
*/
public interface ExistsListener {
/**
- * This method is called when an asynchronous exists command completes successfully.
- *
- * @param key unique record identifier
- * @param exists whether key exists on server
+ * Called when the exists check completes successfully.
+ * @param key record key (must not be null)
+ * @param exists true if the record exists on the server
*/
public void onSuccess(Key key, boolean exists);
/**
- * This method is called when an asynchronous exists command fails.
+ * Called when the exists check fails.
+ * @param ae exception cause of failure wrapped into Aerospike exception
*/
public void onFailure(AerospikeException ae);
}
diff --git a/client/src/com/aerospike/client/listener/ExistsSequenceListener.java b/client/src/com/aerospike/client/listener/ExistsSequenceListener.java
index ee54acbbc..92b81171c 100644
--- a/client/src/com/aerospike/client/listener/ExistsSequenceListener.java
+++ b/client/src/com/aerospike/client/listener/ExistsSequenceListener.java
@@ -20,26 +20,40 @@
import com.aerospike.client.Key;
/**
- * Asynchronous result notifications for batch exists commands.
- * The results are sent one record at a time.
+ * Async callback for batch exists; results delivered one key at a time via {@link #onExists}, then {@link #onSuccess} or {@link #onFailure}.
+ * {@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * Key[] keys = new Key[] { new Key("ns", "set", "k1") };
+ *
+ * client.exists(loop, new ExistsSequenceListener() {
+ * public void onExists(Key key, boolean exists) { }
+ * public void onSuccess() { }
+ * public void onFailure(AerospikeException e) { }
+ * }, new BatchPolicy(), keys);
+ * }
+ *
+ * @see com.aerospike.client.IAerospikeClient#exists
*/
public interface ExistsSequenceListener {
/**
- * This method is called when an asynchronous batch exists result is received from the server.
- * The receive sequence is not ordered.
- *
- * @param key unique record identifier
- * @param exists whether key exists on server
+ * Called for each key when its exists result is received; order is not guaranteed.
+ * @param key record key (must not be null)
+ * @param exists true if the record exists on the server
*/
public void onExists(Key key, boolean exists);
- /**
- * This method is called when the asynchronous batch exists command completes.
- */
+ /** Called when the batch exists completes successfully. */
public void onSuccess();
/**
- * This method is called when an asynchronous batch exists command fails.
+ * Called when the batch exists fails.
+ * @param ae exception cause of failure wrapped into Aerospike exception
*/
public void onFailure(AerospikeException ae);
}
diff --git a/client/src/com/aerospike/client/listener/IndexListener.java b/client/src/com/aerospike/client/listener/IndexListener.java
index c15ebb8eb..5bcea9d84 100644
--- a/client/src/com/aerospike/client/listener/IndexListener.java
+++ b/client/src/com/aerospike/client/listener/IndexListener.java
@@ -20,18 +20,39 @@
import com.aerospike.client.async.AsyncIndexTask;
/**
- * Asynchronous result notifications for create/drop index commands.
+ * Async callback for create/drop index; receives {@link com.aerospike.client.async.AsyncIndexTask} to poll status or exception.
+ * {@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ *
+ * client.createIndex(loop, new InfoPolicy(), "ns", "set", "idx1", "bin1", IndexType.STRING, new IndexListener() {
+ * public void onSuccess(AsyncIndexTask task) {
+ * task.queryStatus(loop, policy, node, new TaskStatusListener() { ... });
+ * }
+ * public void onFailure(AerospikeException e) { }
+ * });
+ * }
+ *
+ * @see com.aerospike.client.async.AsyncIndexTask
+ * @see TaskStatusListener
+ * @see com.aerospike.client.IAerospikeClient#createIndex
+ * @see com.aerospike.client.IAerospikeClient#dropIndex
*/
public interface IndexListener {
/**
- * This method is called when an asynchronous command completes successfully.
- *
- * @param indexTask task monitor that can be used to query for index command completion.
+ * Called when the create/drop index request is accepted; use the task to poll completion.
+ * @param indexTask task monitor for querying index status (must not be null)
*/
void onSuccess(AsyncIndexTask indexTask);
/**
- * This method is called when an asynchronous command fails.
+ * Called when the create/drop index request fails.
+ * @param ae exception cause of failure wrapped into Aerospike exception
*/
public void onFailure(AerospikeException ae);
}
diff --git a/client/src/com/aerospike/client/listener/InfoListener.java b/client/src/com/aerospike/client/listener/InfoListener.java
index f023b71cb..681fd3268 100644
--- a/client/src/com/aerospike/client/listener/InfoListener.java
+++ b/client/src/com/aerospike/client/listener/InfoListener.java
@@ -21,20 +21,35 @@
import com.aerospike.client.AerospikeException;
/**
- * Asynchronous info command result notification.
+ * Async callback for info command; receives a map of info key-value pairs or exception.
+ * {@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * Node node = client.getNodes()[0];
+ *
+ * client.info(loop, new InfoListener() {
+ * public void onSuccess(Map map) { }
+ * public void onFailure(AerospikeException e) { }
+ * }, new InfoPolicy(), node, "build");
+ * }
+ *
+ * @see com.aerospike.client.IAerospikeClient#info
*/
public interface InfoListener {
/**
- * This method is called when an asynchronous info command completes successfully.
- *
- * @param map map of info command keys and result values.
+ * Called when the info command completes successfully.
+ * @param map map of info keys to result values (must not be null)
*/
public void onSuccess(Map{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * Key[] keys = new Key[] { new Key("ns", "set", "k1") };
+ *
+ * client.get(loop, new RecordArrayListener() {
+ * public void onSuccess(Key[] keys, Record[] records) { }
+ * public void onFailure(AerospikeException e) { }
+ * }, new BatchPolicy(), keys);
+ * }
+ *
+ * @see com.aerospike.client.IAerospikeClient#get
+ * @see com.aerospike.client.AerospikeException.BatchRecords
*/
public interface RecordArrayListener {
/**
- * This method is called when the command completes successfully.
- * The returned record array is in positional order with the original key array order.
- *
- * @param keys unique record identifiers
- * @param records record instances, an instance will be null if the key is not found
+ * Called when the batch get completes; arrays are in same order as the key array.
+ * @param keys original keys (must not be null)
+ * @param records records; null at index i means key i was not found
*/
public void onSuccess(Key[] keys, Record[] records);
/**
- * This method is called when the command fails. The AerospikeException is likely to be
- * {@link com.aerospike.client.AerospikeException.BatchRecords} which contains results
- * for keys that did complete.
+ * Called when the batch fails; may be {@link com.aerospike.client.AerospikeException.BatchRecords} with partial results.
+ * @param ae exception cause of failure wrapped into Aerospike exception
*/
public void onFailure(AerospikeException ae);
}
diff --git a/client/src/com/aerospike/client/listener/RecordListener.java b/client/src/com/aerospike/client/listener/RecordListener.java
index d75f5904a..8246593e6 100644
--- a/client/src/com/aerospike/client/listener/RecordListener.java
+++ b/client/src/com/aerospike/client/listener/RecordListener.java
@@ -21,19 +21,38 @@
import com.aerospike.client.Record;
/**
- * Asynchronous result notifications for get or operate commands.
+ * Async callback for single-key get and operate; receives one record or failure.
+ * {@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ *
+ * client.get(loop, new Policy(), new RecordListener() {
+ * public void onSuccess(Key key, Record record) {
+ * if (record != null) { Object v = record.getValue("bin"); }
+ * }
+ * public void onFailure(AerospikeException e) { }
+ * }, key);
+ * }
+ *
+ * @see com.aerospike.client.IAerospikeClient#get
+ * @see com.aerospike.client.IAerospikeClient#operate
*/
public interface RecordListener {
/**
- * This method is called when an asynchronous get or operate command completes successfully.
- *
- * @param key unique record identifier
- * @param record record instance if found, otherwise null
+ * Called when the get or operate completes successfully.
+ * @param key record key (must not be null)
+ * @param record record if found, otherwise null
*/
public void onSuccess(Key key, Record record);
/**
- * This method is called when an asynchronous get or operate command fails.
+ * Called when the get or operate fails.
+ * @param ae exception cause of failure wrapped into Aerospike exception
*/
public void onFailure(AerospikeException ae);
}
diff --git a/client/src/com/aerospike/client/listener/RecordSequenceListener.java b/client/src/com/aerospike/client/listener/RecordSequenceListener.java
index ec56e342c..a48a196df 100644
--- a/client/src/com/aerospike/client/listener/RecordSequenceListener.java
+++ b/client/src/com/aerospike/client/listener/RecordSequenceListener.java
@@ -21,36 +21,46 @@
import com.aerospike.client.Record;
/**
- * Asynchronous result notifications for batch get and scan/query commands.
- * The results are sent one record at a time.
+ * Asynchronous callback for batch get and scan/query; results are delivered one record at a time via {@link #onRecord}, then {@link #onSuccess} or {@link #onFailure}.
+ * {@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * Statement stmt = new Statement();
+ * stmt.setNamespace("test");
+ * stmt.setSetName("set1");
+ * client.query(loop, new RecordSequenceListener() {
+ * public void onRecord(Key key, Record record) {
+ * if (record != null) { Object v = record.getValue("mybin"); }
+ * }
+ * public void onSuccess() { }
+ * public void onFailure(AerospikeException e) { }
+ * }, null, stmt);
+ * }
+ *
+ * @see #onSuccess
+ * @see #onFailure(AerospikeException)
+ * @see com.aerospike.client.AerospikeClient#query
+ * @see com.aerospike.client.AerospikeClient#get
*/
public interface RecordSequenceListener {
/**
- * This method is called when an asynchronous record is received from the server.
- * The receive sequence is not ordered.
- * {@code
+ * task.queryStatus(loop, new InfoPolicy(), node, new TaskStatusListener() {
+ * public void onSuccess(int status) {
+ * if (status == 100) { }
+ * }
+ * public void onFailure(AerospikeException e) { }
+ * });
+ * }
+ *
+ * @see com.aerospike.client.async.AsyncIndexTask#queryStatus
+ * @see IndexListener
+ * @see com.aerospike.client.task.Task
*/
public interface TaskStatusListener {
/**
- * This method is called when an asynchronous command completes successfully.
- *
- * @param status task status (see {@link com.aerospike.client.task.Task})
+ * Called when the asynchronous command completes successfully
+ * @param status task status see {@link com.aerospike.client.task.Task}
*/
void onSuccess(int status);
/**
- * This method is called when an asynchronous command fails.
+ * Called when the asynchronous command fails.
+ * @param ae exception cause of failure wrapped into Aerospike exception
*/
public void onFailure(AerospikeException ae);
}
diff --git a/client/src/com/aerospike/client/listener/WriteListener.java b/client/src/com/aerospike/client/listener/WriteListener.java
index 49b9cd09f..f487bedcb 100644
--- a/client/src/com/aerospike/client/listener/WriteListener.java
+++ b/client/src/com/aerospike/client/listener/WriteListener.java
@@ -20,18 +20,35 @@
import com.aerospike.client.Key;
/**
- * Asynchronous result notifications for put, append, prepend, add, delete and touch commands.
+ * Async callback for put, append, prepend, add, touch; receives key on success or exception on failure.
+ * {@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ *
+ * client.put(loop, new WriteListener() {
+ * public void onSuccess(Key key) { }
+ * public void onFailure(AerospikeException e) { }
+ * }, new WritePolicy(), key, new Bin("bin", "value"));
+ * }
+ *
+ * @see com.aerospike.client.IAerospikeClient#put
+ * @see com.aerospike.client.IAerospikeClient#delete
*/
public interface WriteListener {
/**
* This method is called when an asynchronous write command completes successfully.
- *
- * @param key unique record identifier
+ * @param key unique record identifier (must not be null)
*/
public void onSuccess(Key key);
/**
* This method is called when an asynchronous write command fails.
+ * @param ae exception cause of failure wrapped into Aerospike exception
*/
public void onFailure(AerospikeException ae);
}
diff --git a/client/src/com/aerospike/client/operation/BitOperation.java b/client/src/com/aerospike/client/operation/BitOperation.java
index 5eba701a5..a87d5f485 100644
--- a/client/src/com/aerospike/client/operation/BitOperation.java
+++ b/client/src/com/aerospike/client/operation/BitOperation.java
@@ -22,13 +22,29 @@
import com.aerospike.client.util.Packer;
/**
- * Bit operations. Create bit operations used by client operate command.
- * Offset orientation is left-to-right. Negative offsets are supported.
+ * Bit (byte[]) operations for the client operate command. Offset orientation is left-to-right, Negative offsets are supported.
* If the offset is negative, the offset starts backwards from end of the bitmap.
* If an offset is out of bounds, a parameter error will be returned.
* {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Key key = new Key("ns", "set", "mykey");
+ * client.operate(null, key,
+ * BitOperation.resize(BitPolicy.Default, "bits", 4, BitResizeFlags.DEFAULT),
+ * BitOperation.get("bits", 0, 4));
+ * Record rec = client.get(null, key);
+ * byte[] bits = rec.getBytes("bits");
+ * client.close();
+ * }
+ *
+ * @see BitPolicy
+ * @see BitResizeFlags
+ * @see BitWriteFlags
+ * @see BitOverflowAction
+ * @see com.aerospike.client.AerospikeClient#operate
+ * @see com.aerospike.client.exp.BitExp
*/
public final class BitOperation {
private static final int RESIZE = 0;
diff --git a/client/src/com/aerospike/client/operation/BitOverflowAction.java b/client/src/com/aerospike/client/operation/BitOverflowAction.java
index 1de69130b..e99d1c9c7 100644
--- a/client/src/com/aerospike/client/operation/BitOverflowAction.java
+++ b/client/src/com/aerospike/client/operation/BitOverflowAction.java
@@ -17,7 +17,11 @@
package com.aerospike.client.operation;
/**
- * Action to take when bitwise add/subtract results in overflow/underflow.
+ * Action when bit add/subtract overflows or underflows; used in {@link BitOperation} integer bit ops.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * BitPolicy policy = BitPolicy.Default;
+ * client.operate(null, key, BitOperation.resize(policy, "bits", 8, BitResizeFlags.DEFAULT));
+ *
+ * BitPolicy createOnly = new BitPolicy(BitWriteFlags.CREATE_ONLY);
+ * client.operate(null, key, BitOperation.set(createOnly, "bits", 0, new byte[] { 1, 2, 3 }));
+ * }
+ *
+ * @see BitOperation
+ * @see BitWriteFlags
*/
public final class BitPolicy {
- /**
- * Default byte[] with normal bin write semantics.
- */
+ /** Default policy with normal create/update semantics. */
public static final BitPolicy Default = new BitPolicy();
public final int flags;
diff --git a/client/src/com/aerospike/client/operation/BitResizeFlags.java b/client/src/com/aerospike/client/operation/BitResizeFlags.java
index 3e6231bef..7fbac8ab1 100644
--- a/client/src/com/aerospike/client/operation/BitResizeFlags.java
+++ b/client/src/com/aerospike/client/operation/BitResizeFlags.java
@@ -17,7 +17,11 @@
package com.aerospike.client.operation;
/**
- * Bitwise operation flags for resize.
+ * Flags for {@link BitOperation#resize}; control where bytes are added/removed and size direction.
+ * {@code
+ * Write flags for bit operations; combine with BITWISE OR and pass to {@link BitPolicy}.
+ * {@code
* int flags = BitWriteFlags.NO_FAIL | BitWriteFlags.PARTIAL;
+ * BitPolicy policy = new BitPolicy(flags);
+ * client.operate(null, key, BitOperation.set(policy, "bits", 0, value));
* }
+ *
+ * @see BitPolicy
+ * @see BitOperation
*/
public final class BitWriteFlags {
/**
diff --git a/client/src/com/aerospike/client/operation/HLLOperation.java b/client/src/com/aerospike/client/operation/HLLOperation.java
index a9acd2d85..afeb08bd0 100644
--- a/client/src/com/aerospike/client/operation/HLLOperation.java
+++ b/client/src/com/aerospike/client/operation/HLLOperation.java
@@ -24,10 +24,25 @@
import com.aerospike.client.util.Pack;
/**
- * HyperLogLog (HLL) operations.
+ * HyperLogLog (HLL) operations for the client operate command; init, add, count, union, similarity, etc.
* {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Key key = new Key("ns", "set", "mykey");
+ * client.operate(null, key,
+ * HLLOperation.init(HLLPolicy.Default, "hll", 14),
+ * HLLOperation.add(HLLPolicy.Default, "hll", listOfValues));
+ * Record rec = client.operate(null, key, HLLOperation.count("hll"));
+ * long count = rec.getLong("hll");
+ * client.close();
+ * }
+ *
+ * @see HLLPolicy
+ * @see HLLWriteFlags
+ * @see com.aerospike.client.AerospikeClient#operate
+ * @see com.aerospike.client.exp.HLLExp
*/
public final class HLLOperation {
private static final int INIT = 0;
diff --git a/client/src/com/aerospike/client/operation/HLLPolicy.java b/client/src/com/aerospike/client/operation/HLLPolicy.java
index 7100a6c4b..5d11b30ca 100644
--- a/client/src/com/aerospike/client/operation/HLLPolicy.java
+++ b/client/src/com/aerospike/client/operation/HLLPolicy.java
@@ -17,12 +17,25 @@
package com.aerospike.client.operation;
/**
- * HyperLogLog operation policy.
+ * Policy for HyperLogLog operations; holds {@link HLLWriteFlags} used by {@link HLLOperation}.
+ * {@code
+ * HLLPolicy policy = HLLPolicy.Default;
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * client.operate(null, key, HLLOperation.init(policy, "hll", 14));
+ * client.operate(null, key, HLLOperation.add(policy, "hll", valueList));
+ *
+ * HLLPolicy createOnly = new HLLPolicy(HLLWriteFlags.CREATE_ONLY);
+ * client.operate(null, key, HLLOperation.init(createOnly, "hll", 12));
+ * }
+ *
+ * @see HLLOperation
+ * @see HLLWriteFlags
*/
public final class HLLPolicy {
- /**
- * Default HLL bin write semantics.
- */
+ /** Default policy with normal create/update semantics. */
public static final HLLPolicy Default = new HLLPolicy();
public final int flags;
diff --git a/client/src/com/aerospike/client/operation/HLLWriteFlags.java b/client/src/com/aerospike/client/operation/HLLWriteFlags.java
index 171148ea7..eafa72f17 100644
--- a/client/src/com/aerospike/client/operation/HLLWriteFlags.java
+++ b/client/src/com/aerospike/client/operation/HLLWriteFlags.java
@@ -17,11 +17,18 @@
package com.aerospike.client.operation;
/**
- * HyperLogLog operation policy write bit flags. Use BITWISE OR to combine flags. Example:
- *
- * {@code
+ * Write flags for HyperLogLog operations; combine with BITWISE OR and pass to {@link HLLPolicy}.
+ *
*
* Default: null (create NettyTlsContext for each AerospikeClient instance when netty is used).
diff --git a/client/src/com/aerospike/client/policy/TxnRollPolicy.java b/client/src/com/aerospike/client/policy/TxnRollPolicy.java
index 9601e3d83..592e27944 100644
--- a/client/src/com/aerospike/client/policy/TxnRollPolicy.java
+++ b/client/src/com/aerospike/client/policy/TxnRollPolicy.java
@@ -23,8 +23,24 @@
import com.aerospike.client.configuration.serializers.dynamicconfig.DynamicTxnRollConfig;
/**
- * Transaction policy fields used to batch roll forward/backward records on
- * commit or abort. Used a placeholder for now as there are no additional fields beyond BatchPolicy.
+ * Policy for transaction roll forward/backward phase on commit or abort; extends {@link BatchPolicy} with no extra fields.
+ * {@code
* int flags = HLLWriteFlags.CREATE_ONLY | HLLWriteFlags.NO_FAIL;
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * HLLPolicy policy = new HLLPolicy(flags);
+ * client.operate(null, key, HLLOperation.init(policy, "hll", 14));
* }
+ *
+ * @see HLLPolicy
+ * @see HLLOperation
*/
public final class HLLWriteFlags {
/**
diff --git a/client/src/com/aerospike/client/policy/AdminPolicy.java b/client/src/com/aerospike/client/policy/AdminPolicy.java
index 9d43ed6ca..c51a58dbb 100644
--- a/client/src/com/aerospike/client/policy/AdminPolicy.java
+++ b/client/src/com/aerospike/client/policy/AdminPolicy.java
@@ -17,7 +17,21 @@
package com.aerospike.client.policy;
/**
- * Policy attributes used for user administration commands.
+ * Policy for admin commands (create/drop user/role, grant/revoke, etc.): socket timeout.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * AdminPolicy ap = new AdminPolicy();
+ * ap.timeout = 5000;
+ * client.createUser(ap, "jdoe", "secret", java.util.Collections.emptyList());
+ * }
+ *
+ * @see com.aerospike.client.AerospikeClient#createUser
+ * @see com.aerospike.client.AerospikeClient#createRole
*/
public final class AdminPolicy {
/**
diff --git a/client/src/com/aerospike/client/policy/AuthMode.java b/client/src/com/aerospike/client/policy/AuthMode.java
index 93a1e0ae8..fbd343da1 100644
--- a/client/src/com/aerospike/client/policy/AuthMode.java
+++ b/client/src/com/aerospike/client/policy/AuthMode.java
@@ -17,7 +17,9 @@
package com.aerospike.client.policy;
/**
- * Authentication mode.
+ * Authentication mode (internal, external, PKI). Set on {@link ClientPolicy#authMode} to match server configuration.
+ *
+ * @see ClientPolicy#authMode
*/
public enum AuthMode {
/**
diff --git a/client/src/com/aerospike/client/policy/BatchDeletePolicy.java b/client/src/com/aerospike/client/policy/BatchDeletePolicy.java
index 3953190dc..151d0f9df 100644
--- a/client/src/com/aerospike/client/policy/BatchDeletePolicy.java
+++ b/client/src/com/aerospike/client/policy/BatchDeletePolicy.java
@@ -24,7 +24,23 @@
import com.aerospike.client.exp.Expression;
/**
- * Policy attributes used in batch delete commands.
+ * Policy for batch delete: optional filter expression and commit level.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * BatchPolicy batchPolicy = new BatchPolicy();
+ * BatchDeletePolicy bdp = new BatchDeletePolicy();
+ * bdp.commitLevel = CommitLevel.COMMIT_MASTER;
+ * client.delete(batchPolicy, bdp, keys);
+ * }
+ *
+ * @see BatchPolicy
+ * @see com.aerospike.client.AerospikeClient#delete
+ * @see CommitLevel
*/
public final class BatchDeletePolicy {
/**
diff --git a/client/src/com/aerospike/client/policy/BatchPolicy.java b/client/src/com/aerospike/client/policy/BatchPolicy.java
index 1b8b32cc5..2291bfd19 100644
--- a/client/src/com/aerospike/client/policy/BatchPolicy.java
+++ b/client/src/com/aerospike/client/policy/BatchPolicy.java
@@ -26,7 +26,25 @@
import java.util.Objects;
/**
- * Batch parent policy.
+ * Policy for batch get, batch write, batch delete, and batch operate: concurrency, inline processing, and respond-all-keys.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * BatchPolicy policy = new BatchPolicy();
+ * policy.allowInline = true;
+ * policy.totalTimeout = 2000;
+ * Record[] records = client.get(policy, keys);
+ * }
+ *
+ * @see Policy
+ * @see BatchWritePolicy
+ * @see BatchDeletePolicy
+ * @see com.aerospike.client.AerospikeClient#get
+ * @see com.aerospike.client.AerospikeClient#operate
*/
public class BatchPolicy extends Policy {
/**
diff --git a/client/src/com/aerospike/client/policy/BatchReadPolicy.java b/client/src/com/aerospike/client/policy/BatchReadPolicy.java
index 88cd54e3d..b5469e02d 100644
--- a/client/src/com/aerospike/client/policy/BatchReadPolicy.java
+++ b/client/src/com/aerospike/client/policy/BatchReadPolicy.java
@@ -19,7 +19,24 @@
import com.aerospike.client.exp.Expression;
/**
- * Policy attributes used in batch read commands.
+ * Policy for batch read: optional filter expression, read mode (AP/SC), replica, and read-touch-TTL.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * BatchPolicy batchPolicy = new BatchPolicy();
+ * BatchReadPolicy brp = new BatchReadPolicy();
+ * brp.readModeAP = ReadModeAP.ONE;
+ * Record[] records = client.get(batchPolicy, keys);
+ * }
+ *
+ * @see BatchPolicy
+ * @see com.aerospike.client.AerospikeClient#get
+ * @see ReadModeAP
+ * @see ReadModeSC
*/
public final class BatchReadPolicy {
/**
diff --git a/client/src/com/aerospike/client/policy/BatchUDFPolicy.java b/client/src/com/aerospike/client/policy/BatchUDFPolicy.java
index 525468837..a9f2ce0a5 100644
--- a/client/src/com/aerospike/client/policy/BatchUDFPolicy.java
+++ b/client/src/com/aerospike/client/policy/BatchUDFPolicy.java
@@ -24,7 +24,23 @@
import com.aerospike.client.exp.Expression;
/**
- * Policy attributes used in batch UDF execute commands.
+ * Policy for batch UDF execute: optional filter expression and commit level.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * BatchPolicy batchPolicy = new BatchPolicy();
+ * BatchUDFPolicy budfp = new BatchUDFPolicy();
+ * budfp.commitLevel = CommitLevel.COMMIT_ALL;
+ * client.execute(batchPolicy, budfp, keys, "pkg", "func", Value.get("arg"));
+ * }
+ *
+ * @see BatchPolicy
+ * @see com.aerospike.client.AerospikeClient#execute
+ * @see CommitLevel
*/
public final class BatchUDFPolicy {
/**
diff --git a/client/src/com/aerospike/client/policy/BatchWritePolicy.java b/client/src/com/aerospike/client/policy/BatchWritePolicy.java
index d33c0b9d4..2dd22760c 100644
--- a/client/src/com/aerospike/client/policy/BatchWritePolicy.java
+++ b/client/src/com/aerospike/client/policy/BatchWritePolicy.java
@@ -24,7 +24,24 @@
import com.aerospike.client.exp.Expression;
/**
- * Policy attributes used in batch write commands.
+ * Policy for batch write and batch operate write operations: filter expression, record-exists action, generation, commit level, expiration.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * BatchPolicy batchPolicy = new BatchPolicy();
+ * BatchWritePolicy bwp = new BatchWritePolicy();
+ * bwp.recordExistsAction = RecordExistsAction.REPLACE;
+ * bwp.commitLevel = CommitLevel.COMMIT_MASTER;
+ * client.operate(batchPolicy, batchRecordList);
+ * }
+ *
+ * @see BatchPolicy
+ * @see com.aerospike.client.AerospikeClient#operate
+ * @see Policy#filterExp
*/
public final class BatchWritePolicy {
/**
diff --git a/client/src/com/aerospike/client/policy/ClientPolicy.java b/client/src/com/aerospike/client/policy/ClientPolicy.java
index e2a5027c6..2b386e590 100644
--- a/client/src/com/aerospike/client/policy/ClientPolicy.java
+++ b/client/src/com/aerospike/client/policy/ClientPolicy.java
@@ -33,7 +33,34 @@
import com.aerospike.client.util.Util;
/**
- * Container object for client policy Command.
+ * Client-level configuration: connection limits, timeouts, auth, default policies, and optional event loops for async.
+ * {@code
+ * ClientPolicy policy = new ClientPolicy();
+ * policy.user = "admin";
+ * policy.password = "secret";
+ * policy.timeout = 2000;
+ * IAerospikeClient client = new AerospikeClient(policy, "localhost", 3000);
+ * client.close();
+ * }
+ *
+ * @see com.aerospike.client.AerospikeClient
+ * @see Policy
+ * @see WritePolicy
+ * @see QueryPolicy
+ * @see ScanPolicy
+ * @see BatchPolicy
+ * @see BatchWritePolicy
+ * @see BatchDeletePolicy
+ * @see BatchUDFPolicy
+ * @see TxnVerifyPolicy
+ * @see TxnRollPolicy
+ * @see InfoPolicy
+ * @see TlsPolicy
*/
public class ClientPolicy {
/**
diff --git a/client/src/com/aerospike/client/policy/CommitLevel.java b/client/src/com/aerospike/client/policy/CommitLevel.java
index 72ffdc391..75e11adc2 100644
--- a/client/src/com/aerospike/client/policy/CommitLevel.java
+++ b/client/src/com/aerospike/client/policy/CommitLevel.java
@@ -17,7 +17,11 @@
package com.aerospike.client.policy;
/**
- * Desired consistency guarantee when committing a command on the server.
+ * Consistency guarantee when committing a write on the server (all replicas vs master only).
+ *
+ * @see WritePolicy#commitLevel
+ * @see BatchDeletePolicy#commitLevel
+ * @see BatchUDFPolicy#commitLevel
*/
public enum CommitLevel {
/**
diff --git a/client/src/com/aerospike/client/policy/GenerationPolicy.java b/client/src/com/aerospike/client/policy/GenerationPolicy.java
index c1ddf89a3..cd1633165 100644
--- a/client/src/com/aerospike/client/policy/GenerationPolicy.java
+++ b/client/src/com/aerospike/client/policy/GenerationPolicy.java
@@ -17,7 +17,9 @@
package com.aerospike.client.policy;
/**
- * How to handle record writes based on record generation.
+ * How to handle record writes based on record generation (optimistic concurrency).
+ *
+ * @see WritePolicy#generationPolicy
*/
public enum GenerationPolicy {
/**
diff --git a/client/src/com/aerospike/client/policy/InfoPolicy.java b/client/src/com/aerospike/client/policy/InfoPolicy.java
index 88dd409f3..8b3a56038 100644
--- a/client/src/com/aerospike/client/policy/InfoPolicy.java
+++ b/client/src/com/aerospike/client/policy/InfoPolicy.java
@@ -17,7 +17,20 @@
package com.aerospike.client.policy;
/**
- * Policy attributes used for info commands.
+ * Policy for info protocol requests to a node; currently supports socket timeout.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * InfoPolicy policy = new InfoPolicy();
+ * policy.timeout = 2000;
+ * String build = Info.request(policy, client.getNodes()[0], "build");
+ * }
+ *
+ * @see com.aerospike.client.Info#request
*/
public final class InfoPolicy {
/**
diff --git a/client/src/com/aerospike/client/policy/Policy.java b/client/src/com/aerospike/client/policy/Policy.java
index d8be235d2..1367bc792 100644
--- a/client/src/com/aerospike/client/policy/Policy.java
+++ b/client/src/com/aerospike/client/policy/Policy.java
@@ -27,7 +27,24 @@
import com.aerospike.client.exp.Expression;
/**
- * Command policy attributes used in all database commands.
+ * Base policy for all database commands: timeouts, retries, replica selection, optional expression filter and transaction.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Policy p = new Policy();
+ * p.filterExp = Exp.build(Exp.eq(Exp.intBin("a"), Exp.val(11)));
+ * client.get(p, key);
+ * }
+ *
+ * @see WritePolicy
+ * @see QueryPolicy
+ * @see ScanPolicy
+ * @see BatchPolicy
+ * @see com.aerospike.client.Txn
*/
public class Policy {
/**
@@ -65,11 +82,7 @@ public class Policy {
* command is ignored.
* Example:{@code
- * Policy p = new Policy();
- * p.filterExp = Exp.build(Exp.eq(Exp.intBin("a"), Exp.val(11)));
- * }
+ * See class-level example for {@link com.aerospike.client.exp.Exp#build} usage.
*/
public Expression filterExp;
diff --git a/client/src/com/aerospike/client/policy/QueryDuration.java b/client/src/com/aerospike/client/policy/QueryDuration.java
index 9c41ac218..2233a18f3 100644
--- a/client/src/com/aerospike/client/policy/QueryDuration.java
+++ b/client/src/com/aerospike/client/policy/QueryDuration.java
@@ -17,8 +17,9 @@
package com.aerospike.client.policy;
/**
- * Expected query duration. The server treats the query in different ways depending on the expected duration.
- * This enum is ignored for aggregation queries, background queries and server versions < 6.0.
+ * Expected query duration (LONG or SHORT); server optimizes accordingly. Ignored for aggregation, background queries, and server versions before 6.0.
+ *
+ * @see QueryPolicy#expectedDuration
*/
public enum QueryDuration {
/**
diff --git a/client/src/com/aerospike/client/policy/QueryPolicy.java b/client/src/com/aerospike/client/policy/QueryPolicy.java
index 1bacb8e57..ad4798d58 100644
--- a/client/src/com/aerospike/client/policy/QueryPolicy.java
+++ b/client/src/com/aerospike/client/policy/QueryPolicy.java
@@ -23,10 +23,24 @@
import com.aerospike.client.configuration.serializers.dynamicconfig.DynamicQueryConfig;
/**
- * Container object for policy attributes used in query operations.
+ * Policy for query and scan operations: expected duration, max records, concurrency, record queue size, and include-bin-data.
* {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * QueryPolicy policy = new QueryPolicy();
+ * policy.expectedDuration = QueryDuration.SHORT;
+ * policy.includeBinData = true;
+ * RecordSet rs = client.query(policy, stmt);
+ * rs.close();
+ * }
+ *
+ * @see Policy
+ * @see com.aerospike.client.query.Statement
+ * @see com.aerospike.client.AerospikeClient#query
*/
public class QueryPolicy extends Policy {
/**
diff --git a/client/src/com/aerospike/client/policy/ReadModeAP.java b/client/src/com/aerospike/client/policy/ReadModeAP.java
index ac4edbdaa..a9bce7375 100644
--- a/client/src/com/aerospike/client/policy/ReadModeAP.java
+++ b/client/src/com/aerospike/client/policy/ReadModeAP.java
@@ -17,10 +17,10 @@
package com.aerospike.client.policy;
/**
- * Read policy for AP (availability) namespaces.
- * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * ScanPolicy policy = new ScanPolicy();
+ * policy.maxRecords = 1000;
+ * policy.includeBinData = true;
+ * client.scanAll(policy, "test", "set1", (key, record) -> { }, "mybin");
+ * }
+ *
+ * @deprecated Use {@link QueryPolicy} with {@link com.aerospike.client.AerospikeClient#query} or {@link com.aerospike.client.AerospikeClient#queryPartitions} and a {@link com.aerospike.client.query.Statement} with namespace and set name (no filter).
+ *
+ * @see QueryPolicy
+ * @see com.aerospike.client.AerospikeClient#query
*/
@Deprecated
public final class ScanPolicy extends Policy {
diff --git a/client/src/com/aerospike/client/policy/TCPKeepAlive.java b/client/src/com/aerospike/client/policy/TCPKeepAlive.java
index c282d58f8..7f0f8d56b 100644
--- a/client/src/com/aerospike/client/policy/TCPKeepAlive.java
+++ b/client/src/com/aerospike/client/policy/TCPKeepAlive.java
@@ -18,6 +18,16 @@
/**
* TCP keep-alive policy. This configuration only referenced when using native Netty epoll library.
+ * {@code
+ * TCPKeepAlive keepAlive = new TCPKeepAlive(60, 10, 3);
+ * ClientPolicy cp = new ClientPolicy();
+ * cp.keepAlive = keepAlive;
+ * IAerospikeClient client = new AerospikeClient(cp, "localhost", 3000);
+ * }
+ *
+ * @see ClientPolicy#keepAlive
*/
public final class TCPKeepAlive {
/**
diff --git a/client/src/com/aerospike/client/policy/TlsPolicy.java b/client/src/com/aerospike/client/policy/TlsPolicy.java
index ff4448d1d..8162b16e7 100644
--- a/client/src/com/aerospike/client/policy/TlsPolicy.java
+++ b/client/src/com/aerospike/client/policy/TlsPolicy.java
@@ -23,8 +23,23 @@
import com.aerospike.client.async.NettyTlsContext;
/**
- * TLS connection policy. Secure TLS connections are supported for
- * synchronous commands and netty backed asynchronous commands.
+ * TLS connection policy for secure connections; supported for sync and Netty-backed async commands.
+ * {@code
+ * TlsPolicy tp = new TlsPolicy();
+ * tp.protocols = new String[] {"TLSv1.2"};
+ * ClientPolicy cp = new ClientPolicy();
+ * cp.tlsPolicy = tp;
+ * IAerospikeClient client = new AerospikeClient(cp, "localhost", 4333);
+ * client.close();
+ * }
+ *
+ * @see ClientPolicy#tlsPolicy
+ * @see com.aerospike.client.AerospikeClient
*/
public final class TlsPolicy {
/**
@@ -49,8 +64,8 @@ public final class TlsPolicy {
* ClientPolicy cp = new ClientPolicy();
* cp.tlsPolicy = tp;
*
- * AerospikeClient cluster1 = new AerospikeClient(cp, "host1", 3000);
- * AerospikeClient cluster2 = new AerospikeClient(cp, "host2", 3000);
+ * IAerospikeClient cluster1 = new AerospikeClient(cp, "host1", 3000);
+ * IAerospikeClient cluster2 = new AerospikeClient(cp, "host2", 3000);
* }{@code
+ * TxnRollPolicy trp = new TxnRollPolicy();
+ * trp.totalTimeout = 15000;
+ * ClientPolicy cp = new ClientPolicy();
+ * cp.txnRollPolicyDefault = trp;
+ * IAerospikeClient client = new AerospikeClient(cp, "localhost", 3000);
+ * }
+ *
+ * @see BatchPolicy
+ * @see ClientPolicy#txnRollPolicyDefault
+ * @see com.aerospike.client.AerospikeClient#commit
+ * @see com.aerospike.client.AerospikeClient#abort
*/
public class TxnRollPolicy extends BatchPolicy {
/**
diff --git a/client/src/com/aerospike/client/policy/TxnVerifyPolicy.java b/client/src/com/aerospike/client/policy/TxnVerifyPolicy.java
index cafda0fdd..4915d7f53 100644
--- a/client/src/com/aerospike/client/policy/TxnVerifyPolicy.java
+++ b/client/src/com/aerospike/client/policy/TxnVerifyPolicy.java
@@ -23,8 +23,23 @@
import com.aerospike.client.configuration.serializers.dynamicconfig.DynamicTxnVerifyConfig;
/**
- * Transaction policy fields used to batch verify record versions on commit.
- * Used a placeholder for now as there are no additional fields beyond BatchPolicy.
+ * Policy for transaction verify phase (batch read of record versions before commit); extends {@link BatchPolicy} with no extra fields.
+ * {@code
+ * TxnVerifyPolicy tvp = new TxnVerifyPolicy();
+ * tvp.socketTimeout = 5000;
+ * ClientPolicy cp = new ClientPolicy();
+ * cp.txnVerifyPolicyDefault = tvp;
+ * IAerospikeClient client = new AerospikeClient(cp, "localhost", 3000);
+ * }
+ *
+ * @see BatchPolicy
+ * @see ClientPolicy#txnVerifyPolicyDefault
+ * @see com.aerospike.client.AerospikeClient#commit
*/
public class TxnVerifyPolicy extends BatchPolicy {
/**
diff --git a/client/src/com/aerospike/client/policy/WritePolicy.java b/client/src/com/aerospike/client/policy/WritePolicy.java
index cbc1d460d..8a9bb880a 100644
--- a/client/src/com/aerospike/client/policy/WritePolicy.java
+++ b/client/src/com/aerospike/client/policy/WritePolicy.java
@@ -25,8 +25,25 @@
import com.aerospike.client.configuration.serializers.dynamicconfig.DynamicWriteConfig;
/**
- * Container object for policy attributes used in write operations.
- * This object is passed into methods where database writes can occur.
+ * Policy for write operations: record-exists action, generation policy, commit level, expiration, and related options.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * WritePolicy wp = new WritePolicy();
+ * wp.recordExistsAction = RecordExistsAction.REPLACE;
+ * wp.expiration = 3600;
+ * client.put(wp, key, new Bin("name", "Alice"));
+ * }
+ *
+ * @see Policy
+ * @see RecordExistsAction
+ * @see GenerationPolicy
+ * @see com.aerospike.client.AerospikeClient#put
+ * @see com.aerospike.client.AerospikeClient#operate
*/
public final class WritePolicy extends Policy {
/**
diff --git a/client/src/com/aerospike/client/query/Filter.java b/client/src/com/aerospike/client/query/Filter.java
index 77e7da056..f5fe0944f 100644
--- a/client/src/com/aerospike/client/query/Filter.java
+++ b/client/src/com/aerospike/client/query/Filter.java
@@ -26,9 +26,28 @@
import com.aerospike.client.util.Pack;
/**
- * Query filter definition.
+ * Query filter definition; exactly one filter per {@link Statement}, on a bin that has a secondary index.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Statement stmt = new Statement();
+ * stmt.setNamespace("test");
+ * stmt.setSetName("users");
+ * stmt.setFilter(Filter.equal("status", "active"));
+ * RecordSet rs = client.query(null, stmt);
+ * try {
+ * while (rs.next()) { KeyRecord kr = rs.getKeyRecord(); }
+ * } finally { rs.close(); }
+ * client.close();
+ * }
*
- * Currently, only one filter is allowed in a Statement, and must be on bin which has a secondary index defined.
+ * @see Statement
+ * @see Statement#setFilter
+ * @see IndexType
+ * @see IndexCollectionType
+ * @see com.aerospike.client.cdt.CTX
*/
public final class Filter {
/**
diff --git a/client/src/com/aerospike/client/query/IndexCollectionType.java b/client/src/com/aerospike/client/query/IndexCollectionType.java
index c5fee4fbc..0521f9dac 100644
--- a/client/src/com/aerospike/client/query/IndexCollectionType.java
+++ b/client/src/com/aerospike/client/query/IndexCollectionType.java
@@ -17,7 +17,13 @@
package com.aerospike.client.query;
/**
- * Secondary index collection type.
+ * Whether the secondary index is on a scalar bin, list elements, or map keys/values; used with {@link IndexType} when creating an index and in {@link Filter}.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * RecordSet rs = client.query(null, stmt);
+ * try {
+ * while (rs.next()) {
+ * KeyRecord kr = rs.getKeyRecord();
+ * if (kr.record != null) { Object v = kr.record.getValue("mybin"); }
+ * }
+ * } finally { rs.close(); }
+ * client.close();
+ * }
+ *
+ * @see RecordSet
+ * @see com.aerospike.client.Key
+ * @see com.aerospike.client.Record
*/
public final class KeyRecord {
/**
diff --git a/client/src/com/aerospike/client/query/PartitionFilter.java b/client/src/com/aerospike/client/query/PartitionFilter.java
index e37e393a7..8f760a8b1 100644
--- a/client/src/com/aerospike/client/query/PartitionFilter.java
+++ b/client/src/com/aerospike/client/query/PartitionFilter.java
@@ -29,6 +29,22 @@
* after the last record read (in digest order) in each partition in the previous scan/query.
* To reset the cursor of an existing PartitionFilter instance, call
* {@link #setPartitions(PartitionStatus[])} with a null argument.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Statement stmt = new Statement();
+ * stmt.setNamespace("test");
+ * stmt.setSetName("set1");
+ * PartitionFilter filter = PartitionFilter.range(0, 100);
+ * RecordSet rs = client.queryPartitions(null, stmt, filter);
+ * try {
+ * while (rs.next()) { KeyRecord kr = rs.getKeyRecord(); }
+ * } finally { rs.close(); }
+ * client.close();
+ * }
+ *
+ * @see com.aerospike.client.AerospikeClient#queryPartitions
+ * @see Statement
*/
public final class PartitionFilter implements Serializable {
private static final long serialVersionUID = 4L;
diff --git a/client/src/com/aerospike/client/query/QueryListener.java b/client/src/com/aerospike/client/query/QueryListener.java
index b8db35b72..9da4c88ad 100644
--- a/client/src/com/aerospike/client/query/QueryListener.java
+++ b/client/src/com/aerospike/client/query/QueryListener.java
@@ -21,22 +21,34 @@
import com.aerospike.client.Record;
/**
- * Result notification for sync query command.
- * The results are sent one record at a time.
+ * Callback for each record in a synchronous secondary-index query; results are streamed one record at a time.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Statement stmt = new Statement();
+ * stmt.setNamespace("test");
+ * stmt.setSetName("set1");
+ * stmt.setFilter(Filter.equal("status", "active"));
+ * client.query(null, stmt, (key, record) -> {
+ * if (record != null) { Object val = record.getValue("mybin"); }
+ * });
+ * client.close();
+ * }
+ *
+ * @see RecordSet
+ * @see Statement
+ * @see Filter
+ * @see com.aerospike.client.AerospikeClient#query(com.aerospike.client.policy.QueryPolicy, Statement, QueryListener)
+ * @see com.aerospike.client.AerospikeException.QueryTerminated
*/
public interface QueryListener {
/**
- * This method is called when a record is received from the server.
- * The receive sequence is not ordered.
- * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Statement stmt = new Statement();
+ * stmt.setNamespace("test");
+ * stmt.setSetName("set1");
+ * stmt.setFilter(Filter.equal("bin1", 1));
+ * RecordSet rs = client.query(null, stmt);
+ * try {
+ * while (rs.next()) {
+ * KeyRecord kr = rs.getKeyRecord();
+ * if (kr.record != null) { Object v = kr.record.getValue("mybin"); }
+ * }
+ * } finally {
+ * rs.close();
+ * }
+ * client.close();
+ * }
+ *
+ * @see KeyRecord
+ * @see ResultSet
+ * @see QueryListener
+ * @see Statement
+ * @see com.aerospike.client.AerospikeClient#query
*/
public class RecordSet implements Iterable{@code
+ * Regex bit flags for expression and filter regex; combine with BITWISE OR.
+ * {@code
* int flags = RegexFlag.ICASE | RegexFlag.NEWLINE;
* }
+ *
+ * @see com.aerospike.client.exp.Exp#regexCompare
+ * @see Filter
*/
public final class RegexFlag {
/**
diff --git a/client/src/com/aerospike/client/query/ResultSet.java b/client/src/com/aerospike/client/query/ResultSet.java
index b8d1b5ace..ac8239211 100644
--- a/client/src/com/aerospike/client/query/ResultSet.java
+++ b/client/src/com/aerospike/client/query/ResultSet.java
@@ -25,11 +25,33 @@
import com.aerospike.client.Log;
/**
- * This class manages result retrieval from queries.
- * Multiple threads will retrieve results from the server nodes and put these results on the queue.
- * The single user thread consumes these results from the queue.
+ * Iterable set of aggregation UDF results; call {@link #next()} then {@link #getObject()} (or iterate) and always {@link #close()} when done.
+ * {@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Statement stmt = new Statement();
+ * stmt.setNamespace("test");
+ * stmt.setSetName("set1");
+ * stmt.setFilter(Filter.equal("bin1", 1));
+ * ResultSet rs = client.queryAggregate(null, stmt);
+ * try {
+ * while (rs.next()) {
+ * Object obj = rs.getObject();
+ * }
+ * } finally {
+ * rs.close();
+ * }
+ * client.close();
+ * }
+ *
+ * @see RecordSet
+ * @see Statement
+ * @see com.aerospike.client.AerospikeClient#queryAggregate
*/
public class ResultSet implements Iterable