Java 1.2 documentation

docs/explanations/migrating-from-temporal.md

@@ -831,7 +831,7 @@ Learn more in the [queues tutorial](../golang/tutorials/queue-tutorial.md).
 
 ```java
 // Register a queue with concurrency limits (after dbos.launch())
-dbos.registerQueue("order-processing", QueueOptions.setConcurrency(10));
+dbos.registerQueue("order-processing", new QueueOptions().withConcurrency(10));
 
 // Enqueue a workflow
 WorkflowHandle<String, Exception> handle = dbos.startWorkflow(

docs/java/integrating-dbos.md

@@ -13,7 +13,7 @@ Add DBOS to your application by including it in your build configuration.
 <TabItem value="gradle" label="Gradle">
 ```groovy
 dependencies {
-    implementation 'dev.dbos:transact:1.1.0'
+    implementation 'dev.dbos:transact:1.2.0'
 }
 ```
 </TabItem>
@@ -23,7 +23,7 @@ dependencies {
     <dependency>
         <groupId>dev.dbos</groupId>
         <artifactId>transact</artifactId>
-        <version>1.1.0</version>
+        <version>1.2.0</version>
     </dependency>
 </dependencies>
 ```

docs/java/programming-guide.md

@@ -25,7 +25,7 @@ Then, install DBOS (plus Logback for logging) by adding the following to your `a
 
 ```kotlin
 dependencies {
-  implementation("dev.dbos:transact:1.1.0")
+  implementation("dev.dbos:transact:1.2.0")
   implementation("org.slf4j:slf4j-simple:2.0.17") // needed to see DBOS log messages
   implementation("io.javalin:javalin:7.0.1") // needed for creating HTTP endpoint later in the guide
 
@@ -120,7 +120,7 @@ Now, build and run this code with:
 Your program should print output like:
 
 ```shell
-[main] INFO dev.dbos.transact.DBOS - Launching DBOS v1.1.0
+[main] INFO dev.dbos.transact.DBOS - Launching DBOS v1.2.0
 [main] INFO dev.dbos.transact.execution.DBOSExecutor - DBOS Executor starting
 [main] INFO dev.dbos.transact.execution.DBOSExecutor - System Database: jdbc:postgresql://localhost:5432/dbos_java_starter
 [main] INFO dev.dbos.transact.execution.DBOSExecutor - System Database User name: postgres
@@ -312,7 +312,7 @@ public class App {
       config.events.serverStarting(() -> {
         dbos.launch();
         // Queues are stored in the system database, so register them after launch
-        dbos.registerQueue("example-queue", QueueOptions.empty());
+        dbos.registerQueue("example-queue", new QueueOptions());
       });
       config.events.serverStopping(dbos::shutdown);
       config.routes.get("/", ctx -> {

docs/java/reference/client.md

@@ -113,8 +113,8 @@ The workflow name and queue must not be null or empty.
 - **`withAppVersion(String appVersion)`**: The version of your application that should process this workflow.
 If left undefined, the workflow is enqueued without a version and is only dequeued by an executor running the owning application's latest registered version, which sets the version when it first dequeues it.
 - **`withTimeout(Duration timeout)`**, **`withTimeout(long value, TimeUnit unit)`**:  Set an explicit timeout for the enqueued workflow. When the timeout expires, the workflow and all its children are cancelled. The timeout does not begin until the workflow is dequeued and starts execution.
-- **`withTimeout(Timeout timeout)`**, **`withNoTimeout()`**: Set the timeout as a [`Timeout`](./methods.md#timeout): explicit, none, or inherit. Inside a workflow, [`dbos.enqueueWorkflow`](./methods.md#enqueueworkflow) resolves it as `startWorkflow` does, so an unset timeout inherits the enqueuing workflow's and `withNoTimeout()` declines it. From a client there is nothing to inherit, so an unset or inherited timeout means no timeout.
-- **`withDeadline(Instant deadline)`**:  Set a deadline for the enqueued workflow. If the workflow is executing when the deadline arrives, the workflow and all its children are cancelled.
+- **`withTimeout(Timeout timeout)`**, **`withNoTimeout()`**: Set the timeout as a [`Timeout`](./methods.md#timeout): explicit, none, or inherit. [`dbos.enqueueWorkflow`](./methods.md#enqueueworkflow) resolves it as `startWorkflow` does: an unset timeout takes the bound of an enclosing [`WorkflowOptions`](./workflows-steps.md#workflowoptions) block if there is one, and otherwise, inside a workflow, inherits the enqueuing workflow's deadline. `withNoTimeout()` declines both. From a client there is nothing to inherit, so an unset or inherited timeout means no timeout.
+- **`withDeadline(Instant deadline)`** *(deprecated since 1.2)*: Use `withTimeout` instead; no other DBOS SDK lets a caller set a deadline. Set a deadline for the enqueued workflow. If the workflow is executing when the deadline arrives, the workflow and all its children are cancelled.
 
 :::info
 An explicit timeout and a deadline cannot both be set.
@@ -567,13 +567,13 @@ Create a `DebouncerClient` for the named workflow. Similar to [`dbos.debouncer()
 - **`withClassName(String className)`**: The fully-qualified Java class name of the workflow implementation. **Required** — must be set before calling `debounce`.
 - **`withInstanceName(String instanceName)`**: The DBOS instance name of the target workflow implementation.
 - **`withDebounceTimeout(Duration debounceTimeout)`**: Set an absolute cap on how long the debouncer may keep absorbing calls for a single key.
-- **`withQueue(QueueName queue)`** / **`withQueue(String queueName)`**: Enqueue the user workflow on the specified queue when the debounce period elapses. `withQueue(Queue queue)` is *(deprecated since 1.1)*.
-- **`withTimeout(Duration timeout)`**: Set a timeout for the user workflow.
+- **`withQueue(QueueName queue)`** / **`withQueue(String queueName)`**: The queue the user workflow waits and runs on. Without one, it uses the DBOS internal queue. `withQueue(Queue queue)` is *(deprecated since 1.1)*.
+- **`withTimeout(Duration timeout)`**: Set a timeout for the user workflow, timed from when it is dequeued. A zero or negative timeout throws `IllegalArgumentException` when set.
 - **`withAppVersion(String appVersion)`**: Target a specific application version.
-- **`withPriority(Integer priority)`**: Set the priority for the user workflow. A priority requires a queue: if a priority is set without `withQueue`, `debounce` throws `IllegalArgumentException`.
+- **`withPriority(Integer priority)`**: Set the priority for the user workflow. A negative priority throws `IllegalArgumentException` when set. A priority requires a queue: if a priority is set without `withQueue`, `debounce` throws `IllegalArgumentException`.
 - **`withAttributes(Map<String, Object> attributes)`**: Attach custom JSON-serializable key-value metadata to the user workflow.
 - **`withSerialization(SerializationStrategy serialization)`**: The [serialization strategy](./methods.md#serialization-strategy) for the user workflow's arguments. It should match the strategy the workflow is registered with.
-- **`withDeduplicationId(String deduplicationId)`** *(deprecated since 1.1)*: Set a deduplication ID forwarded to the user workflow. This will be ignored from the next release, where the debouncer sets the deduplication ID itself, and removed in 2.0.
+- **`withDeduplicationId(String deduplicationId)`** *(deprecated since 1.1)*: Ignored since 1.2. The debounced workflow holds its debounce key as its deduplication ID.
 
 ### DebouncerClient.debounce
 

docs/java/reference/methods.md

@@ -317,7 +317,11 @@ public record WorkflowStatus(
     // The name of the schedule that started this workflow, if any
     String scheduleName,
     // The application that owns this workflow, or null if no application owns it
-    String applicationName
+    String applicationName,
+    // Whether this is a debounced workflow, whose deduplication ID is its debounce key
+    Boolean isDebounced,
+    // The latest a debounced workflow's start may be pushed back to, or null for no cap
+    Instant debounceDeadline
 )
 ```
 
@@ -517,6 +521,14 @@ ListWorkflowsInput withWasForkedFrom(Boolean wasForkedFrom)
 
 Filter to workflows from which another workflow was forked.
 
+#### withIsFork
+
+```java
+ListWorkflowsInput withIsFork(Boolean isFork)
+```
+
+Filter to workflows that are forks of another workflow (`true`), or that are not (`false`).
+
 #### withHasParent
 
 ```java
@@ -929,10 +941,13 @@ Obtain a `Debouncer` via `dbos.debouncer()`:
 `Debouncer<R>` is an immutable builder. Configure it with the following methods before calling `debounce`:
 
 - **`withDebounceTimeout(Duration debounceTimeout)`**: Set an absolute cap on how long the debouncer may keep absorbing calls for a single key. After this duration elapses from the first call, the user workflow starts regardless of further incoming calls.
-- **`withQueue(QueueName queue)`** / **`withQueue(String queueName)`**: Enqueue the user workflow on the specified queue when the debounce period elapses instead of starting it directly. `withQueue(Queue queue)` is *(deprecated since 1.1)*.
+- **`withQueue(QueueName queue)`** / **`withQueue(String queueName)`**: The queue the user workflow waits and runs on. Without one, it uses the DBOS internal queue. The queue can't be [partitioned](../tutorials/queue-tutorial.md#partitioning-queues): a debounced workflow has no partition key, and partitioned queues don't support deduplication IDs. `withQueue(Queue queue)` is *(deprecated since 1.1)*.
 - **`withAppVersion(String appVersion)`**: Target a specific application version for the user workflow.
-- **`withPriority(Integer priority)`**: Set the priority for the user workflow. A priority requires a queue: if a priority is set without `withQueue`, `debounce` throws `IllegalArgumentException`.
-- **`withDeduplicationId(String deduplicationId)`** *(deprecated since 1.1)*: Set a deduplication ID forwarded to the user workflow. This will be ignored from the next release, where the debouncer sets the deduplication ID itself, and removed in 2.0.
+- **`withPriority(Integer priority)`**: Set the priority for the user workflow. A negative priority throws `IllegalArgumentException` when set. A priority requires a queue: if a priority is set without `withQueue`, `debounce` throws `IllegalArgumentException`.
+- **`withTimeout(Duration timeout)`**: Set a timeout for every user workflow this debouncer starts, timed from when that workflow is dequeued. It takes precedence over a timeout set with [`WorkflowOptions`](./workflows-steps.md#workflowoptions) around the `debounce` call, which applies when this isn't set. A zero or negative timeout throws `IllegalArgumentException` when set.
+- **`withDeduplicationId(String deduplicationId)`** *(deprecated since 1.1)*: Ignored since 1.2. The debounced workflow holds its debounce key as its deduplication ID.
+
+The user workflow never inherits the calling workflow's timeout or deadline, and a deadline set with `WorkflowOptions` around the call is ignored, because the workflow may start long after the call.
 
 ### debouncer.debounce
 
@@ -947,7 +962,11 @@ Obtain a `Debouncer` via `dbos.debouncer()`:
 Submit a workflow for execution but delay it by `debouncePeriod`. Returns a handle to the workflow.
 The workflow may be debounced again, which further delays its execution (up to `debounceTimeout`).
 When the workflow eventually executes, it uses the **last** set of inputs passed into `debounce`.
-After the workflow begins execution, the next call to `debounce` starts the debouncing process again for a new workflow execution.
+Once the delay expires and the workflow becomes `ENQUEUED`, the next call to `debounce` starts the debouncing process again for a new workflow execution, even if the first workflow is still waiting on a busy queue.
+
+The first call on a key enqueues the user workflow itself in the `DELAYED` state on its queue, with `workflowName-debounceKey` as its [deduplication ID](../tutorials/queue-tutorial.md#deduplication).
+Each later call on the key resets its start to `debouncePeriod` after that call, never past the debounce timeout, and replaces its arguments.
+When the delay expires, the workflow becomes `ENQUEUED`, releases the key, and runs like any other queued workflow.
 
 **Parameters:**
 - **debounceKey**: A key used to group workflow executions that will be debounced together. For example, if the debounce key is set to customer ID, each customer's workflows are debounced separately.
@@ -1043,13 +1062,15 @@ import dev.dbos.transact.workflow.Timeout;
 
 - **`Timeout.of(Duration duration)`** — Set an explicit timeout of the given duration.
 - **`Timeout.of(long value, TimeUnit unit)`** — Set an explicit timeout.
-- **`Timeout.none()`** — Opt out of any inherited timeout. The workflow will run without a timeout regardless of what the calling context specifies.
-- **`Timeout.inherit()`** — Explicitly inherit the timeout from the calling context (the default behavior when no timeout is set).
+- **`Timeout.none()`** — Run without a timeout, and don't inherit the calling workflow's deadline. A deadline set on the same options still applies.
+- **`Timeout.inherit()`** — Bound the workflow by the calling workflow's deadline, if any (the default behavior when no timeout is set). Outside a workflow, this means no timeout.
+
+A child workflow inherits its parent's deadline, not its timeout: a queued child doesn't start a fresh copy of the parent's timeout when it is dequeued.
 
 **Example:**
 
 ```java
-// Detach a child workflow from the parent's timeout
+// Detach a child workflow from the parent's deadline
 dbos.startWorkflow(() -> proxy.longRunningChild(),
     new StartWorkflowOptions().withTimeout(Timeout.none()));
 ```

docs/java/reference/plugins.md

@@ -180,8 +180,8 @@ ExternalState upsertExternalState(ExternalState state)
 ```
 
 :::warning Deprecated
-`upsertExternalState`, `getExternalState`, and `ExternalState` are *(deprecated since 1.1)* and will be removed in DBOS Java 2.0.
-The system database table behind them, `event_dispatch_kv`, is being retired: it holds dispatch bookkeeping for in-memory event receivers that the other DBOS SDKs have removed or never implemented, and a shared system database migration will drop it sometime after Java 2.0.
+`upsertExternalState`, `getExternalState`, and `ExternalState` are *(deprecated since 1.1)* and will be removed in a future release.
+The system database table behind them, `event_dispatch_kv`, is being retired: it holds dispatch bookkeeping for in-memory event receivers that the other DBOS SDKs have removed or never implemented, and a shared system database migration will drop it sometime after the Java API is removed.
 Store integration state in your own table instead.
 :::