CLIENT-4159: enriched doc

client/src/com/aerospike/client/AbortStatus.java

@@ -17,14 +17,38 @@
 package com.aerospike.client;
 
 /**
- * Transaction abort status code.
+ * Transaction abort result returned by {@link com.aerospike.client.AerospikeClient#abort}. OK and ALREADY_ABORTED indicate success; abandoned statuses mean the server will complete asynchronously.
+ *
+ * <p><b>Example:</b>
+ * <p>Abort a transaction and check the returned status.</p>
+ * <pre>{@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();
+ * }
+ * }</pre>
+ *
+ * @see CommitStatus
+ * @see CommitError
+ * @see com.aerospike.client.AerospikeClient#abort
  */
 public enum AbortStatus {
 	OK("Abort succeeded"),
 	ALREADY_ABORTED("Already aborted"),
 	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) {

client/src/com/aerospike/client/AerospikeException.java

@@ -23,7 +23,37 @@
 import java.util.List;
 
 /**
- * Aerospike exceptions that can be thrown from the client.
+ * Base exception for client errors; holds result code, node, policy, optional sub-exceptions, and in-doubt flag.
+ * <p>
+ * 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.
+ *
+ * <p><b>Example:</b>
+ * <p>Catch an exception, get result code and message, and check in-doubt for writes.</p>
+ * <pre>{@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
+ *   }
+ * }
+ * }</pre>
+ *
+ * @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,15 +151,19 @@ 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();
 		return (message != null)? message : ResultCode.getResultString(resultCode);
 	}
 
 	/**
-	 * 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).
+	 * <p>
+	 * 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.
+	 * <p>
+	 * Catch when calling {@link com.aerospike.client.AerospikeClient#commit}; then call {@link com.aerospike.client.AerospikeClient#abort} if appropriate.
+	 *
+	 * <p><b>Example:</b>
+	 * <p>Catch commit failure, read error and abort the transaction.</p>
+	 * <pre>{@code
+	 * try {
+	 *   client.commit(txn);
+	 * } catch (AerospikeException.Commit e) {
+	 *   CommitError err = e.error;
+	 *   client.abort(txn);
+	 * }
+	 * }</pre>
+	 *
+	 * @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) {

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}.
+ * <p>
+ * 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}.
+ * <pre>{@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();
+ * }</pre>
+ *
+ * @see BatchRecord
+ * @see com.aerospike.client.AerospikeClient#operate
+ * @see com.aerospike.client.AerospikeClient#delete
  */
 public final class BatchDelete extends BatchRecord {
 	/**

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).
+ * <p>
+ * 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()}.
+ * <pre>{@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();
+ * }</pre>
+ *
+ * @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 {
 	/**