Add javadocs (mostly) (#210)

Also clarify an exception and remove a dead file.

Author: chuck-dbos

transact/src/main/java/dev/dbos/transact/context/DBOSContextHolder.java

@@ -1,7 +1,6 @@
 package dev.dbos.transact.context;
 
 public class DBOSContextHolder {
-  // CB: I think this default ctor business will bite us.
   private static final ThreadLocal<DBOSContext> contextHolder =
       ThreadLocal.withInitial(DBOSContext::new);
 

transact/src/main/java/dev/dbos/transact/context/WorkflowInfo.java

@@ -1,3 +1,12 @@
 package dev.dbos.transact.context;
 
+/**
+ * Contains identifying information about the parent of a workflow.
+ *
+ * <p>If provided, this record encapsulates the parent's workflow id and the calling step number
+ * that started the workflow.
+ *
+ * @param workflowId The unique id for the parent workflow.
+ * @param functionId The step number within the parent workflow that created the child.
+ */
 public record WorkflowInfo(String workflowId, int functionId) {}

transact/src/main/java/dev/dbos/transact/database/ExternalState.java

@@ -4,6 +4,26 @@
 import java.math.BigInteger;
 import java.util.Objects;
 
+/**
+ * Represents a piece of state associated with an external service such as an event dispatcher.
+ *
+ * <p>This record models a key/value entry stored by the DBOS system database on behalf of an
+ * external service It includes identifying information (service name, fully qualified workflow
+ * name, key within), a value, and optional metadata for versioning the update.
+ *
+ * <p>The canonical constructor enforces that {@code service}, {@code workflowName}, and {@code key}
+ * are non-null.
+ *
+ * @param service The name of the external service that owns or stores the state.
+ * @param workflowName The fully qualified function name of the workflow that this state belongs to.
+ * @param key The key under which the external state is stored, allowing multiple values per service
+ *     and workflow combination.
+ * @param value The current value associated with the key.
+ * @param updateTime The timestamp of the last update, represented as a decimal (e.g., UNIX epoch
+ *     seconds), or {@code null} if unused.
+ * @param updateSeq A monotonic sequence number for updates, used to detect the latest version, or
+ *     {@code null} if not applicable.
+ */
 public record ExternalState(
     String service,
     String workflowName,
@@ -18,18 +38,40 @@ public record ExternalState(
     Objects.requireNonNull(key, "key must not be null");
   }
 
+  /**
+   * Create an external state
+   *
+   * @param service service storing the state
+   * @param workflowName fully qualified name of the workflow storine for which the state applies
+   * @param key key allowing multiple values to be stored per service per workflow
+   */
   public ExternalState(String service, String workflowName, String key) {
     this(service, workflowName, key, null, null, null);
   }
 
+  /**
+   * Create an {@code ExternalState} like this one, but with a new value
+   *
+   * @param value
+   */
   public ExternalState withValue(String value) {
     return new ExternalState(service, workflowName, key, value, updateTime, updateSeq);
   }
 
+  /**
+   * Create an {@code ExternalState} like this one, but with a new update time
+   *
+   * @param updateTime update time to use, as a decimal number of seconds since the Unix epoch
+   */
   public ExternalState withUpdateTime(BigDecimal updateTime) {
     return new ExternalState(service, workflowName, key, value, updateTime, updateSeq);
   }
 
+  /**
+   * Create an {@code ExternalState} like this one, but with a new sequence number
+   *
+   * @param updateSeq sequence number to use
+   */
   public ExternalState withUpdateSeq(BigInteger updateSeq) {
     return new ExternalState(service, workflowName, key, value, updateTime, updateSeq);
   }

transact/src/main/java/dev/dbos/transact/database/UpdateWorkflowOptions.java

@@ -1,5 +1,12 @@
 package dev.dbos.transact.exceptions;
 
+/**
+ * {@code DBOSAwaitedWorkflowCancelledException} is thrown by DBOS when a call requests the return
+ * value of a workflow that was cancelled.
+ *
+ * <p>Calls such as {@code DBOS.getResult} and {@code WorkflowHandle.getResult} may throw this
+ * exception.
+ */
 public class DBOSAwaitedWorkflowCancelledException extends RuntimeException {
   private String workflowId;
 
@@ -8,6 +15,7 @@ public DBOSAwaitedWorkflowCancelledException(String workflowId) {
     this.workflowId = workflowId;
   }
 
+  /** The workflow ID of the awaited, cancelled workflow */
   public String workflowId() {
     return workflowId;
   }

transact/src/main/java/dev/dbos/transact/exceptions/DBOSAwaitedWorkflowCancelledException.java

@@ -1,5 +1,16 @@
 package dev.dbos.transact.exceptions;
 
+/**
+ * {@code DBOSConflictingWorkflowException} is thrown by DBOS when an attempt is made to start a
+ * workflow, a workflow with that ID that already exists, and the existing workflow is incompatible
+ * with the attempted workflow initiation.
+ *
+ * <p>{@code DBOSConflictingWorkflowException} generally indicates a programmer error, such as
+ * attempting to invoke two entirely different workflow functions with the same workflow ID.
+ *
+ * <p>Direct workflow invocation, workflow enqueue, and {@code DBOS.startWorkflow} may throw this
+ * exception.
+ */
 public class DBOSConflictingWorkflowException extends RuntimeException {
   private final String workflowId;
 
@@ -8,6 +19,7 @@ public DBOSConflictingWorkflowException(String workflowId, String msg) {
     this.workflowId = workflowId;
   }
 
+  /** The workflow ID that already exists, with a conflicting invocation */
   public String workflowId() {
     return this.workflowId;
   }

transact/src/main/java/dev/dbos/transact/exceptions/DBOSConflictingWorkflowException.java

@@ -1,5 +1,9 @@
 package dev.dbos.transact.exceptions;
 
+/**
+ * {@code DBOSMaxRecoveryAttemptsExceededException} is thrown when workflow recovery is attempted,
+ * but the maximum number of recovery attempts have already been made.
+ */
 public class DBOSMaxRecoveryAttemptsExceededException extends RuntimeException {
 
   private String workflowId;
@@ -12,10 +16,14 @@ public DBOSMaxRecoveryAttemptsExceededException(String workflowId, int maxRetrie
             workflowId, maxRetries));
   }
 
+  /**
+   * The ID of the workflow for which a maximum number of recovery attempts have already been made
+   */
   public String workflowId() {
     return workflowId;
   }
 
+  /** The number of retries allowed */
   public int maxRetries() {
     return maxRetries;
   }

transact/src/main/java/dev/dbos/transact/exceptions/DBOSMaxRecoveryAttemptsExceededException.java

@@ -1,5 +1,12 @@
 package dev.dbos.transact.exceptions;
 
+/**
+ * {@code DBOSNonExistentWorkflowException} is thrown by DBOS functions such as `send` or
+ * `executeWorkflowById` that require a workflow to exist prior to invocation.
+ *
+ * <p>Unless the workflow ID was taken from the user, receipt of this error generally indicates a
+ * programmer error.
+ */
 public class DBOSNonExistentWorkflowException extends RuntimeException {
   private String workflowId;
 
@@ -8,6 +15,7 @@ public DBOSNonExistentWorkflowException(String workflowId) {
     this.workflowId = workflowId;
   }
 
+  /** ID of the workflow that was targeted, but did not exist */
   public String workflowId() {
     return workflowId;
   }

transact/src/main/java/dev/dbos/transact/exceptions/DBOSNonExistentWorkflowException.java

@@ -1,5 +1,10 @@
 package dev.dbos.transact.exceptions;
 
+/**
+ * {@code DBOSQueueDuplicatedException} is thrown when an attempt is made to enqueue a workflow into
+ * a queue with deduplication. DBOSQueueDuplicatedException is thrown to indicate that a queued
+ * workflow with this `deduplicationId` already exists.
+ */
 public class DBOSQueueDuplicatedException extends RuntimeException {
   private final String workflowId;
   private final String queueName;
@@ -15,14 +20,20 @@ public DBOSQueueDuplicatedException(String workflowId, String queueName, String
     this.deduplicationId = deduplicationId;
   }
 
+  /** ID of the workflow for which enqueue was attempted (This is not the existing workflow ID) */
   public String workflowId() {
     return workflowId;
   }
 
+  /** The name of the queue into which enqueueing was attempted */
   public String queueName() {
     return queueName;
   }
 
+  /**
+   * The deduplication ID within the queue; a workflow with this deduplication ID was already
+   * enqueued.
+   */
   public String deduplicationId() {
     return deduplicationId;
   }

transact/src/main/java/dev/dbos/transact/exceptions/DBOSQueueDuplicatedException.java

@@ -2,6 +2,11 @@
 
 import java.sql.SQLException;
 
+/**
+ * This exception is thrown by DBOS when the system database cannot be reached, despite numerous
+ * retries. Handling this exception is unlikely to end well. A new execution should be started once
+ * system database connectivity is restored.
+ */
 public class DBOSSystemDatabaseException extends RuntimeException {
   Throwable underlyingException;
 
@@ -14,6 +19,7 @@ public DBOSSystemDatabaseException(Throwable e) {
     this.underlyingException = e;
   }
 
+  /** A recent exception received from the system database connection */
   public Throwable databaseException() {
     return underlyingException;
   }