Java 1.1 documentation by devhawk · Pull Request #626 · dbos-inc/dbos-docs

devhawk · 2026-09-23T00:05:32Z

Documentation for DBOS Transact Java 1.1 (java#452–#548, plus java#551).

Merge order: after dbos-inc/dbos-transact-java#551 merges and 1.1.0 is published to Maven Central. These pages describe #551's behaviour: priorityEnabled is deprecated and ignored, negative priorities and half-set rate limits are rejected, and isSerializationFailure is not deprecated. The dependency snippets pin 1.1.0.

Upgrade guide

New Upgrading to v1.1 section in java/upgrading.md:

Rolling upgrade:
- every deployment gets a new computed version, because the hash now includes the app name;
- 1.1 is a required waypoint for the debouncer;
- migrate applications before clients;
- 1.0 executors stop waking event and stream waiters in other processes once the notification triggers are dropped.
Behaviour changes:
- the schema must be at version 111 or later when migration is off, and DBOSClient checks this at construction;
- the Java CLI is removed in favour of dbosctl;
- recovery re-enqueues work, and launch skips self-recovery under Conductor or Cloud;
- version-less enqueue now goes to the latest version;
- queue configuration is validated on both registration and update, and negative priorities are rejected;
- an invalid app name fails launch under Conductor or Cloud;
- the client's useListenNotify default, and readStream on an unknown workflow ID;
- DBOSSystemDatabaseException;
- send inherits the workflow's serialization, and scheduled runs always use the app serializer;
- reading payload-table rows written by Python 3.0 and TypeScript 5.0.
Migration sections for moving to database-backed queues and off legacy partitioned queues.
Deprecations table matching every @Deprecated(since = "1.1") in the SDK.

Reference and tutorials

Queues:
- database-backed queues registered after launch;
- QueueName, and why new StartWorkflowOptions("q") sets a workflow ID rather than a queue;
- per-partition limits, rewritten to mirror the TypeScript tutorial;
- the validation rules;
- the in-memory Queue API, partitionQueue and priorityEnabled marked deprecated;
- priority fixed: every queue dequeues by priority, the range starts at 0, and unassigned workflows get 0.
Shared system databases:
- a Java tab on the cross-language page;
- named clients, EnqueueOptions.withApplicationName, dbos.enqueueWorkflow / enqueuePortableWorkflow, and renameApplication;
- owner fields and filters, and the new exception types.
Config: withNotificationCoalesceInterval, withDatabasePollingConcurrency and DBOS__VMID, plus launch-time recovery behaviour.
Other:
- schedule-name filters;
- the 1.1 debouncer options;
- DEFAULT serialization semantics;
- the event_dispatch_kv plugin API deprecated.
Version pins: updated from 0.8.0 / 0.9.0 to 1.1.0.
prompting.md:
- the queue section rewritten to cover the same ground as the TypeScript prompt;
- the non-existent DBOSConfig methods and the stale Scheduled import removed;
- the record listings synced with the reference.

Pre-existing fixes along the way

The Java tabs of the Temporal migration guide called DBOS methods statically, cast Optional results, and used StepOptions methods that don't exist.
DBOS.registerQueue and similar calls written as if static are now dbos..

Verification

Every API name, signature, default and behaviour claim was checked against java origin/main plus #551. All relative links and anchors in the changed files resolve. The full Docusaurus build was not run locally.

🤖 Generated with Claude Code

Copilot

Copilot review overview

🟡 Changes recommended

Unresolved critical and moderate documentation inaccuracies could cause incorrect queue ownership, ordering, validation, and API usage.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 1 · 5

Open (6)

Assign externally enqueued work to the data-processing application · New
Describe version hashes using method metadata and bytecode · New
Qualify FIFO ordering by workflow priority · New
Require both compared limits to be configured · New
Apply concurrency comparisons only to configured limits · New
Require both limits before applying the comparison rule · New

What changed in this PR

Updates DBOS Transact Java documentation for v1.1, including migration guidance, queue behavior, shared databases, serialization, and API changes.

Changes:

Adds v1.1 upgrade, migration, recovery, and deprecation guidance.
Documents database-backed queues, priorities, ownership, and partition limits.
Updates API references, examples, and dependency versions to 1.1.0.

File	Description
`docs/java/upgrading.md`	Adds Java 1.1 upgrade guidance.
`docs/java/tutorials/upgrading-workflows.md`	Updates application versioning details.
`docs/java/tutorials/spring-boot-integration.md`	Updates lifecycle-based queue registration.
`docs/java/tutorials/scheduled-workflows.md`	Documents ownership and serialization.
`docs/java/tutorials/queue-tutorial.md`	Reworks queue and partition guidance.
`docs/java/tutorials/kotlin.md`	Updates the dependency version.
`docs/java/reference/workflows-steps.md`	Documents queue names and priorities.
`docs/java/reference/queues.md`	Expands queue APIs and validation rules.
`docs/java/reference/plugins.md`	Documents plugin API deprecations.
`docs/java/reference/methods.md`	Adds v1.1 APIs, filters, and exceptions.
`docs/java/reference/lifecycle.md`	Updates lifecycle and configuration guidance.
`docs/java/reference/client.md`	Documents client ownership and management APIs.
`docs/java/prompting.md`	Synchronizes prompting guidance with v1.1.
`docs/java/programming-guide.md`	Updates setup and queue examples.
`docs/java/integrating-dbos.md`	Corrects lifecycle and initialization guidance.
`docs/explanations/sharing-a-system-database.md`	Adds Java shared-database examples.
`docs/explanations/portable-workflows.md`	Updates Java serialization behavior.
`docs/explanations/migrating-from-temporal.md`	Corrects Java API examples.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Move the Java queue docs to database-backed queues registered after launch, with QueueName and the per-partition limits (java#485, #527, #531, #533); mark the in-memory Queue API and partitionQueue deprecated. Document the notification-coalescing and polling-concurrency config (java#470), DBOS__VMID, and launch-time recovery by re-enqueue, skipped under Conductor or DBOS Cloud (java#526, #548). Bump dependency pins to 1.1.0, and fix the Java tabs of the Temporal migration guide, which called DBOS methods statically and cast Optional results.

Document application names and cross-application enqueue (java#471, #476, #478): the named DBOSClient constructors, EnqueueOptions withApplicationName, DBOS.enqueueWorkflow/enqueuePortableWorkflow, renameApplication, the owner fields and filters, and a Java tab on the sharing page. Also: client schema validation (java#511), version-less enqueue (java#452), send inheriting the workflow's serialization and scheduled runs using the app serializer (java#525), schedule-name filters (java#508), the 1.1 debouncer options (java#546), the new exception types, QueueName overloads, and the deprecated external-state API (java#486).

Add an Upgrading to v1.1 section: rolling-upgrade notes (new computed versions, the debouncer waypoint, apps before clients), the behavior changes, new features, moving to database-backed and per-partition queues, and the full list of 1.1 deprecations. Note the Java CLI's removal in favour of dbosctl. Bring prompting.md up to 1.1: version pins, the queue section, client constructors, and the real DBOSConfig options.

Call DBOS instance methods rather than statics: - step-tutorial.md: dbos.runStep, with a DBOS field and constructor - portable-workflows.md: dbos.send, dbos.setEvent Move to the top-level dev.dbos.transact.EnqueueOptions that replaces the now-deprecated DBOSClient.EnqueueOptions. Its constructors take the queue as a QueueName and fix the target: new EnqueueOptions(workflowName, [className, [instanceName,]] QueueName.of(queue)) There is no withClassName or withInstanceName. enqueuePortableWorkflow is gone for the new type: portable enqueue is enqueueWorkflow(options, positionalArgs, namedArgs) with withSerialization(PORTABLE), and named arguments need PORTABLE. The timeout is a Timeout, with withNoTimeout(); inside a workflow an unset timeout inherits the caller's. - client.md, methods.md: enqueueWorkflow overloads, EnqueueOptions constructors and timeout forms; enqueuePortableWorkflow deprecated (client) or removed (DBOS). - upgrading.md: deprecations row for DBOSClient.EnqueueOptions and its overloads. - Every EnqueueOptions sample, and prompting.md's EnqueueOptions section. Also fixes errors that predate this branch: - portable-workflows.md's Java client sample had wrong import paths and called client.enqueue, which doesn't exist. - migrating-from-temporal.md passed the class name as the workflow name. - workflow-classes.md described EnqueueOptions.withInstanceName. - spring-boot-integration.md cited StartWorkflowOptions.withInstanceName, which has never existed. Includes two edits Harry made in these files: the recv check in migrating-from-temporal.md, and dropping the Java-1.1 parenthetical about send serialization in portable-workflows.md. Describes the API on the shared-enqueue-options branch of dbos-transact-java, which has not merged yet.

The Java 1.0 docs described dbos.forkFromFailure and ForkFromFailureOptions as public API, but no public method has ever existed on DBOS or DBOSClient. java#425 added fork from failure only behind Conductor's fork_from_failure message, as the Python, TypeScript and Go SDKs have it. Remove the methods-reference sections, the workflow-management tutorial section, and the ForkFromFailureOptions entries in the QueueName and deprecated-overload lists. The Conductor API, MCP and audit-log pages, which describe the Conductor feature, stay.

- upgrading.md: java#562 marked the seven-argument QueueOptions constructor forRemoval, so every 1.1 deprecation is now removed in 2.0. - client.md, prompting.md: an unset withAppVersion leaves the workflow version-less, and only the owning application's latest registered version dequeues it (the java#562 javadoc fix). - queues.md: add Queue.queueName(), new in java#555.

- Describe the computed app version accurately (workflow method name, signature, and bytecode, not source) and present it as a fallback to an explicit withAppVersion. - dbos.registerQueue: the queue is owned and polled by this application. - widget-store: set the workflow ID with withWorkflowId, like the other samples.

- Queue ordering is by priority, then FIFO within a priority. - Concurrency limits are compared only when both are set. - The DBOSClient enqueue example names the owning application, so the workflow isn't left for any application to dequeue.

…lass names - Upgrading: general rollout guidance (don't skip minor releases, deploy as a new application version, migrate before clients) in its own section, and the v1.1 section trimmed to changes that need action, queue migrations, and deprecations. Release-note material moves to the release notes. - Warnings about workflows stranded on a deleted or newly partitioned queue say how to move them with resumeWorkflow(id, queueName). - EnqueueOptions: DBOS doesn't search classes for a workflow; pass the class name for a Java workflow. - lifecycle: withAppVersion listed next to withAppName.

…ference

Copilot

Copilot review overview

🟡 Changes recommended

The upgrade guide omits several promised operationally significant 1.1 behavior changes and a rolling-upgrade notification caveat.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 2

Open (2)

Document notification caveat for mixed-version rolling upgrades · New
Fix typo in “methods” · New

Resolved since last review (6)

Assign externally enqueued work to the data-processing application
Require both limits before applying the comparison rule
Apply concurrency comparisons only to configured limits
Require both compared limits to be configured
Qualify FIFO ordering by workflow priority
Describe version hashes using method metadata and bytecode

- Upgrade guide: 1.1 is required before 1.2 (debouncing and workflow input/output storage), replacing the general don't-skip rule; a patching caveat on versioning; DBOSClient workflows without a version now go to the latest version; how to fix an invalid application name; record constructors that only affect test code; no admin-server note. - resumeWorkflow: describe that it re-enqueues (on the internal queue by default), works on ENQUEUED workflows, and keeps the application version. - EnqueueOptions examples and wording use fully qualified class names.

…le; event waits during a 1.0 rollout - Replace "deploy each upgrade as a new application version" with what actually changes: a computed version changes with the DBOS version; a set version or patching doesn't. - 1.1 is required before 1.2 or later, not just 1.2. - Warn that events set by 1.0 executors reach 1.1 getEvent waiters only at the 60s re-check, and how to avoid it during the rollout.

kraftp · 2026-09-24T21:49:54Z

+
+Follow these steps for every DBOS upgrade.
+
+- **A DBOS upgrade changes a computed application version.**


We can honestly drop this entirely, more detail than it's worth, and we don't recommend auto-computed versions in prod anyways

kraftp reviewed Sep 23, 2026

View reviewed changes

Comment thread docs/java/upgrading.md Outdated

devhawk requested review from kraftp and maxdml and a balanced review from Copilot and removed request for maxdml September 23, 2026 00:19

Copilot started reviewing on behalf of devhawk September 23, 2026 00:20 View session

Copilot AI reviewed Sep 23, 2026

View reviewed changes

devhawk added 3 commits September 23, 2026 13:33

devhawk force-pushed the java-1.1 branch from cba78bd to c49339c Compare September 23, 2026 20:35

devhawk added 6 commits September 23, 2026 17:17

Java docs: address Copilot review on queues

c679193

- Queue ordering is by priority, then FIFO within a priority. - Concurrency limits are compared only when both are set. - The DBOSClient enqueue example names the owning application, so the workflow isn't left for any application to dequeue.

Merge branch 'main' into java-1.1

9c667c4

devhawk mentioned this pull request Sep 24, 2026

Dequeuing a workflow enqueued without a class name throws NullPointerException dbos-inc/dbos-transact-java#565

Closed

devhawk added 4 commits September 24, 2026 13:22

Java docs: application naming rule and ownership in the DBOSConfig re…

abd0774

…ference

Java upgrade guide: adopt unowned rows before sharing a system database

8e6d1ea

Java docs: show registerQueue in the deprecated in-memory queue example

9f70138

devhawk requested review from maxdml and qianl15 and a balanced review from Copilot September 24, 2026 20:45

Copilot started reviewing on behalf of devhawk September 24, 2026 20:45 View session

Copilot AI reviewed Sep 24, 2026

View reviewed changes

Comment thread docs/java/upgrading.md Outdated

Comment thread docs/java/upgrading.md Outdated

kraftp reviewed Sep 24, 2026

View reviewed changes

Comment thread docs/java/upgrading.md Outdated

kraftp reviewed Sep 24, 2026

View reviewed changes

Comment thread docs/java/upgrading.md Outdated

kraftp reviewed Sep 24, 2026

View reviewed changes

kraftp approved these changes Sep 24, 2026

View reviewed changes

Java upgrade guide: drop the computed-version note

7ed4ac6

devhawk merged commit edaf636 into main Sep 24, 2026
1 check passed

devhawk deleted the java-1.1 branch September 24, 2026 22:01

Navigation Menu

Repository navigation

Java 1.1 documentation - #626

Java 1.1 documentation#626
devhawk merged 16 commits into
mainfrom
java-1.1

devhawk commented Sep 23, 2026

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kraftp Sep 24, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		Follow these steps for every DBOS upgrade.

		- A DBOS upgrade changes a computed application version.

Conversation

devhawk commented Sep 23, 2026

Upgrade guide

Reference and tutorials

Pre-existing fixes along the way

Verification

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kraftp Sep 24, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants