java docs & nullability annotations for QueueOptions (#407)

Also adds java/dbos-toolbox to test_demo_apps

Author: devhawk

.github/workflows/test_demo_apps.yml

@@ -54,6 +54,8 @@ jobs:
         include:
           - app: java/dbos-starter
             build_file: app/build.gradle.kts
+          - app: java/dbos-toolbox
+            build_file: app/build.gradle.kts
           - app: java/widget-store
             build_file: build.gradle.kts
           - app: kotlin/dbos-starter

transact/src/main/java/dev/dbos/transact/workflow/QueueOptions.java

@@ -4,6 +4,7 @@
 import java.util.Optional;
 import java.util.concurrent.TimeUnit;
 
+import org.jspecify.annotations.NonNull;
 import org.jspecify.annotations.Nullable;
 
 /**
@@ -17,15 +18,32 @@
  * <p>The non-nullable queue properties ({@code priorityEnabled}, {@code partitionQueue}, {@code
  * pollingInterval}) use {@link Optional} — {@link Optional#empty()} means use the default on
  * creation or leave unchanged on update; a present value sets the column.
+ *
+ * @param concurrency max concurrent executions of this queue across all workers; {@link
+ *     Field#absent()} means no limit on creation or leave unchanged on update; {@code
+ *     Field.of(null)} clears the column
+ * @param workerConcurrency max concurrent executions of this queue per worker process; {@link
+ *     Field#absent()} means no limit on creation or leave unchanged on update; {@code
+ *     Field.of(null)} clears the column
+ * @param rateLimitMax maximum number of starts allowed in each rate-limit window; must be paired
+ *     with {@code rateLimitPeriod}; {@link Field#absent()} means no rate limit or leave unchanged
+ * @param rateLimitPeriod duration of the rolling rate-limit window; must be paired with {@code
+ *     rateLimitMax}; {@link Field#absent()} means no rate limit or leave unchanged
+ * @param priorityEnabled whether priority-based ordering is enabled for this queue; {@link
+ *     Optional#empty()} means use the default on creation or leave unchanged on update
+ * @param partitionQueue whether to partition queue entries by workflow class so each class gets its
+ *     own concurrency slot; {@link Optional#empty()} means use the default or leave unchanged
+ * @param pollingInterval how often workers poll the database for new queue entries; {@link
+ *     Optional#empty()} means use the default or leave unchanged
  */
 public record QueueOptions(
-    Field<Integer> concurrency,
-    Field<Integer> workerConcurrency,
-    Field<Integer> rateLimitMax,
-    Field<Duration> rateLimitPeriod,
-    Optional<Boolean> priorityEnabled,
-    Optional<Boolean> partitionQueue,
-    Optional<Duration> pollingInterval) {
+    @NonNull Field<Integer> concurrency,
+    @NonNull Field<Integer> workerConcurrency,
+    @NonNull Field<Integer> rateLimitMax,
+    @NonNull Field<Duration> rateLimitPeriod,
+    @NonNull Optional<Boolean> priorityEnabled,
+    @NonNull Optional<Boolean> partitionQueue,
+    @NonNull Optional<Duration> pollingInterval) {
 
   private static final QueueOptions EMPTY =
       new QueueOptions(
@@ -37,10 +55,12 @@ public record QueueOptions(
           Optional.empty(),
           Optional.empty());
 
-  public static QueueOptions empty() {
+  /** Returns the shared all-absent instance; no queue property will be set or changed. */
+  public static @NonNull QueueOptions empty() {
     return EMPTY;
   }
 
+  /** Returns {@code true} if all fields are absent — no property will be set or changed. */
   public boolean isEmpty() {
     return !concurrency.isPresent()
         && !workerConcurrency.isPresent()
@@ -53,37 +73,82 @@ public boolean isEmpty() {
 
   // ── Static factories ──────────────────────────────────────────────────────
 
-  public static QueueOptions setConcurrency(@Nullable Integer value) {
+  /**
+   * Creates options that set only {@code concurrency}; all other fields are absent.
+   *
+   * @param value the concurrency limit, or {@code null} to clear the column
+   */
+  public static @NonNull QueueOptions setConcurrency(@Nullable Integer value) {
     return EMPTY.withConcurrency(Field.of(value));
   }
 
-  public static QueueOptions setWorkerConcurrency(@Nullable Integer value) {
+  /**
+   * Creates options that set only {@code workerConcurrency}; all other fields are absent.
+   *
+   * @param value the per-worker concurrency limit, or {@code null} to clear the column
+   */
+  public static @NonNull QueueOptions setWorkerConcurrency(@Nullable Integer value) {
     return EMPTY.withWorkerConcurrency(Field.of(value));
   }
 
-  public static QueueOptions setRateLimit(@Nullable Integer max, @Nullable Duration period) {
+  /**
+   * Creates options that set only the rate limit; all other fields are absent.
+   *
+   * @param max max starts per window, or {@code null} to clear
+   * @param period length of the rolling window, or {@code null} to clear
+   */
+  public static @NonNull QueueOptions setRateLimit(
+      @Nullable Integer max, @Nullable Duration period) {
     return EMPTY.withRateLimitMax(Field.of(max)).withRateLimitPeriod(Field.of(period));
   }
 
-  public static QueueOptions setRateLimit(int limit, long period, TimeUnit unit) {
+  /**
+   * Creates options that set only the rate limit; all other fields are absent.
+   *
+   * @param limit max starts per window
+   * @param period length of the rolling window
+   * @param unit time unit for {@code period}
+   */
+  public static @NonNull QueueOptions setRateLimit(int limit, long period, @NonNull TimeUnit unit) {
     return setRateLimit(limit, Duration.of(period, unit.toChronoUnit()));
   }
 
-  public static QueueOptions setPriorityEnabled(boolean value) {
+  /**
+   * Creates options that set only {@code priorityEnabled}; all other fields are absent.
+   *
+   * @param value {@code true} to enable priority ordering, {@code false} to disable
+   */
+  public static @NonNull QueueOptions setPriorityEnabled(boolean value) {
     return EMPTY.withPriorityEnabled(Optional.of(value));
   }
 
-  public static QueueOptions setPartitionQueue(boolean value) {
+  /**
+   * Creates options that set only {@code partitionQueue}; all other fields are absent.
+   *
+   * @param value {@code true} to enable per-class queue partitioning, {@code false} to disable
+   */
+  public static @NonNull QueueOptions setPartitionQueue(boolean value) {
     return EMPTY.withPartitionQueue(Optional.of(value));
   }
 
-  public static QueueOptions setPollingInterval(Duration value) {
+  /**
+   * Creates options that set only {@code pollingInterval}; all other fields are absent.
+   *
+   * @param value the interval at which workers poll for new queue entries
+   */
+  public static @NonNull QueueOptions setPollingInterval(@NonNull Duration value) {
     return EMPTY.withPollingInterval(Optional.of(value));
   }
 
   // ── Builders for chaining ─────────────────────────────────────────────────
 
-  public QueueOptions withConcurrency(Field<Integer> concurrency) {
+  /**
+   * Returns a copy of these options with {@code concurrency} replaced.
+   *
+   * @param concurrency the new value; use {@link Field#absent()} to leave unchanged, or {@code
+   *     Field.of(null)} to clear the column
+   */
+  public @NonNull QueueOptions withConcurrency(@NonNull Field<Integer> concurrency) {
     return new QueueOptions(
         concurrency,
         workerConcurrency,
@@ -94,7 +159,13 @@ public QueueOptions withConcurrency(Field<Integer> concurrency) {
         pollingInterval);
   }
 
-  public QueueOptions withWorkerConcurrency(Field<Integer> workerConcurrency) {
+  /**
+   * Returns a copy of these options with {@code workerConcurrency} replaced.
+   *
+   * @param workerConcurrency the new value; use {@link Field#absent()} to leave unchanged, or
+   *     {@code Field.of(null)} to clear the column
+   */
+  public @NonNull QueueOptions withWorkerConcurrency(@NonNull Field<Integer> workerConcurrency) {
     return new QueueOptions(
         concurrency,
         workerConcurrency,
@@ -105,7 +176,13 @@ public QueueOptions withWorkerConcurrency(Field<Integer> workerConcurrency) {
         pollingInterval);
   }
 
-  public QueueOptions withRateLimitMax(Field<Integer> rateLimitMax) {
+  /**
+   * Returns a copy of these options with {@code rateLimitMax} replaced.
+   *
+   * @param rateLimitMax the new value; use {@link Field#absent()} to leave unchanged, or {@code
+   *     Field.of(null)} to clear the column
+   */
+  public @NonNull QueueOptions withRateLimitMax(@NonNull Field<Integer> rateLimitMax) {
     return new QueueOptions(
         concurrency,
         workerConcurrency,
@@ -116,7 +193,13 @@ public QueueOptions withRateLimitMax(Field<Integer> rateLimitMax) {
         pollingInterval);
   }
 
-  public QueueOptions withRateLimitPeriod(Field<Duration> rateLimitPeriod) {
+  /**
+   * Returns a copy of these options with {@code rateLimitPeriod} replaced.
+   *
+   * @param rateLimitPeriod the new value; use {@link Field#absent()} to leave unchanged, or {@code
+   *     Field.of(null)} to clear the column
+   */
+  public @NonNull QueueOptions withRateLimitPeriod(@NonNull Field<Duration> rateLimitPeriod) {
     return new QueueOptions(
         concurrency,
         workerConcurrency,
@@ -127,7 +210,12 @@ public QueueOptions withRateLimitPeriod(Field<Duration> rateLimitPeriod) {
         pollingInterval);
   }
 
-  public QueueOptions withPriorityEnabled(Optional<Boolean> priorityEnabled) {
+  /**
+   * Returns a copy of these options with {@code priorityEnabled} replaced.
+   *
+   * @param priorityEnabled the new value; use {@link Optional#empty()} to leave unchanged
+   */
+  public @NonNull QueueOptions withPriorityEnabled(@NonNull Optional<Boolean> priorityEnabled) {
     return new QueueOptions(
         concurrency,
         workerConcurrency,
@@ -138,7 +226,12 @@ public QueueOptions withPriorityEnabled(Optional<Boolean> priorityEnabled) {
         pollingInterval);
   }
 
-  public QueueOptions withPartitionQueue(Optional<Boolean> partitionQueue) {
+  /**
+   * Returns a copy of these options with {@code partitionQueue} replaced.
+   *
+   * @param partitionQueue the new value; use {@link Optional#empty()} to leave unchanged
+   */
+  public @NonNull QueueOptions withPartitionQueue(@NonNull Optional<Boolean> partitionQueue) {
     return new QueueOptions(
         concurrency,
         workerConcurrency,
@@ -149,7 +242,12 @@ public QueueOptions withPartitionQueue(Optional<Boolean> partitionQueue) {
         pollingInterval);
   }
 
-  public QueueOptions withPollingInterval(Optional<Duration> pollingInterval) {
+  /**
+   * Returns a copy of these options with {@code pollingInterval} replaced.
+   *
+   * @param pollingInterval the new value; use {@link Optional#empty()} to leave unchanged
+   */
+  public @NonNull QueueOptions withPollingInterval(@NonNull Optional<Duration> pollingInterval) {
     return new QueueOptions(
         concurrency,
         workerConcurrency,
@@ -162,31 +260,69 @@ public QueueOptions withPollingInterval(Optional<Duration> pollingInterval) {
 
   // ── Convenience chaining methods ──────────────────────────────────────────
 
-  public QueueOptions andConcurrency(@Nullable Integer value) {
+  /**
+   * Returns a copy of these options with {@code concurrency} set to the given value.
+   *
+   * @param value the concurrency limit, or {@code null} to clear the column
+   */
+  public @NonNull QueueOptions andConcurrency(@Nullable Integer value) {
     return withConcurrency(Field.of(value));
   }
 
-  public QueueOptions andWorkerConcurrency(@Nullable Integer value) {
+  /**
+   * Returns a copy of these options with {@code workerConcurrency} set to the given value.
+   *
+   * @param value the per-worker concurrency limit, or {@code null} to clear the column
+   */
+  public @NonNull QueueOptions andWorkerConcurrency(@Nullable Integer value) {
     return withWorkerConcurrency(Field.of(value));
   }
 
-  public QueueOptions andRateLimit(@Nullable Integer max, @Nullable Duration period) {
+  /**
+   * Returns a copy of these options with the rate limit set.
+   *
+   * @param max max starts per window, or {@code null} to clear
+   * @param period length of the rolling window, or {@code null} to clear
+   */
+  public @NonNull QueueOptions andRateLimit(@Nullable Integer max, @Nullable Duration period) {
     return withRateLimitMax(Field.of(max)).withRateLimitPeriod(Field.of(period));
   }
 
-  public QueueOptions andRateLimit(int max, long period, TimeUnit unit) {
+  /**
+   * Returns a copy of these options with the rate limit set.
+   *
+   * @param max max starts per window
+   * @param period length of the rolling window
+   * @param unit time unit for {@code period}
+   */
+  public @NonNull QueueOptions andRateLimit(int max, long period, @NonNull TimeUnit unit) {
     return andRateLimit(max, Duration.of(period, unit.toChronoUnit()));
   }
 
-  public QueueOptions andPriorityEnabled(boolean value) {
+  /**
+   * Returns a copy of these options with {@code priorityEnabled} set to the given value.
+   *
+   * @param value {@code true} to enable priority ordering, {@code false} to disable
+   */
+  public @NonNull QueueOptions andPriorityEnabled(boolean value) {
     return withPriorityEnabled(Optional.of(value));
   }
 
-  public QueueOptions andPartitionQueue(boolean value) {
+  /**
+   * Returns a copy of these options with {@code partitionQueue} set to the given value.
+   *
+   * @param value {@code true} to enable per-class queue partitioning, {@code false} to disable
+   */
+  public @NonNull QueueOptions andPartitionQueue(boolean value) {
     return withPartitionQueue(Optional.of(value));
   }
 
-  public QueueOptions andPollingInterval(Duration value) {
+  /**
+   * Returns a copy of these options with {@code pollingInterval} set to the given value.
+   *
+   * @param value the interval at which workers poll for new queue entries
+   */
+  public @NonNull QueueOptions andPollingInterval(@NonNull Duration value) {
     return withPollingInterval(Optional.of(value));
   }
 }