docs: add java sdk documentation#381
Merged
Merged
Conversation
📝 WalkthroughWalkthroughAdds Java as a supported SDK across docs navigation, architecture pages, guides, API reference, and runnable examples. Also updates cross-SDK comparison/FAQ content and increases the docs build Node heap limit. ChangesDocs Build Configuration
Java Docs Platform and Navigation
Java Documentation Content
Estimated code review effort: 4 (Complex) | ~60 minutes Possibly related PRs
Suggested labels: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 19
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/content/docs/java/api-reference/context.mdx`:
- Around line 6-25: The handler docs currently say it receives “exactly one
argument,” which conflicts with `@TaskHandler` methods that also accept injected
`@Resource(...)` parameters. Reword the opening of the `Resources.use` section
to distinguish the required payload argument from optional injected resources,
and keep the later note about `@Resource("smtp")`/the generated companion
aligned with that description. Update the wording near the handler example so
readers understand the payload is always the first argument while resources are
resolved separately by `Resources.use` or parameter injection.
In `@docs/content/docs/java/api-reference/resources.mdx`:
- Around line 31-34: The ResourceContext description in the Java resources docs
needs to mention the pooled-resource exception, because pooled factories are not
governed by the same-or-longer-lived rule. Update the wording around
ResourceContext, scope(), and use(name) to either narrow the general rule or add
a pooled-specific note stating that pooled factories may only depend on WORKER
resources, while non-pooled factories keep the existing lifetime restriction.
In `@docs/content/docs/java/getting-started/capabilities.mdx`:
- Line 57: The KEDA table link in the capabilities docs points to a page that
does not exist in the Java docs tree, so update the link target in the
capabilities entry to an existing autoscaling guide or add the missing KEDA page
first. Locate the markdown row in the capabilities document and fix the href
used for the KEDA label so it resolves correctly.
In `@docs/content/docs/java/getting-started/concepts.mdx`:
- Around line 12-17: Make the job lifecycle terminology consistent between the
diagram and the surrounding prose in the concepts document. Update the text
around the lifecycle description to match the state sequence shown in the
diagram, or adjust the diagram labels in the affected flow so both references
use the same states; use the lifecycle content near the diagram and the
enqueue/getResult examples as the anchors when editing.
In `@docs/content/docs/java/getting-started/installation.mdx`:
- Around line 68-70: The `taskito.native.workdir` example is shown as an empty
value, which makes the documented flag look incomplete; update the installation
docs text so the `taskito.native.workdir` example uses a concrete placeholder
path or is explicitly marked as truncated. Keep the surrounding explanation tied
to the `-Dtaskito.native.lib` and `-Dtaskito.native.workdir` options so readers
can copy the example as-is.
In `@docs/content/docs/java/guides/core/execution-model.mdx`:
- Around line 51-54: The KEDA reference in the execution model text points to a
non-existent destination, so update the link used in the surrounding prose about
queue-depth scaling and KEDA to the existing autoscaling guide. Keep the change
localized to the markdown content in this section and ensure the updated link
target matches the autoscaling page that already covers KEDA, preserving the
rest of the sentence and related references like mesh(options).
In `@docs/content/docs/java/guides/core/predicates.mdx`:
- Around line 57-58: The predicates table entry conflates defer(delay) and
deferUntil(instant), and the wording “scheduled after delay” only applies to
defer(delay). Split the combined row in the predicates guide table and update
the deferUntil(instant) description in the relevant table cell to reflect
absolute-time scheduling, keeping the surrounding Job id presence/exception
behavior unchanged.
In `@docs/content/docs/java/guides/operations/dashboard.mdx`:
- Around line 57-60: Add a warning in the dashboard auth docs near the token
bootstrap explanation that `/?token=<token>` can leak via browser history,
referrers, and proxy/access logs; note that this flow should be used only over
HTTPS with log redaction, or recommend replacing it with a non-URL bootstrap if
available. Keep the update centered on the existing `taskito_token`/shared-token
description so readers see the risk immediately.
In `@docs/content/docs/java/guides/operations/testing.mdx`:
- Around line 46-52: The latch example in the task setup uses an undefined
identifier in the Taskito worker chain, so update the
`taskito.worker().handle(...)` snippet to reference the actual task name as a
quoted string or the correct defined symbol instead of `echo`. Keep the rest of
the `Worker` and `CountDownLatch done` example unchanged so the `handle` call
compiles as shown.
In `@docs/content/docs/java/guides/reliability/guarantees.mdx`:
- Around line 6-9: The reliability guarantee wording in the guarantees doc is
too strong and should be narrowed to match at-least-once delivery semantics.
Update the text in the guarantees section to say that every enqueued job is
attempted at least once, and adjust the surrounding explanation in the
guarantees content to reflect that retries may be exhausted or jobs may
dead-letter without completing. Keep the guidance in the same place and align
the wording with the existing Taskito guarantee description.
In `@docs/content/docs/java/guides/reliability/retries.mdx`:
- Around line 34-39: The retry logging example in the Java guide uses an invalid
logger call in the worker setup chain. Update the EventName.RETRY handler inside
the worker() example to use Java string concatenation for the retry message,
matching the rest of the guide’s logging style, so the snippet compiles cleanly
and stays consistent with the other Java examples.
In `@docs/content/docs/java/guides/resources/proxies.mdx`:
- Around line 16-17: The proxy key lookup in the Proxies example should be
guarded because System.getenv("TASKITO_PROXY_KEY") may return null before the
SDK can report a clear configuration problem. Update the sample around the
Proxies initialization to explicitly handle the missing-key case before creating
the byte[] key, and keep the logic centered on the TASKITO_PROXY_KEY lookup so
readers can see how to fail fast with a clear configuration error instead of a
null dereference.
In `@docs/content/docs/java/guides/workflows/gates.mdx`:
- Around line 64-70: The gate example uses an undefined runId in the
approve/reject snippets, making the sample inconsistent with the earlier
run.runId() usage. Update the example around worker.approveGate and
worker.rejectGate to reference the same run identifier from the preceding run
variable (or otherwise define the variable before use) so the sample is
self-contained and consistent.
In `@docs/content/docs/java/guides/workflows/saga.mdx`:
- Around line 20-25: The saga examples use orderId in
Workflow.named(...).step(...) and Step.of(...) without defining where it comes
from, so make both snippets self-contained by adding the workflow input
declaration or showing how orderId is supplied before the WorkflowRun
submission. Update the Java guide examples around the checkout workflow so the
reserve, charge, and ship steps clearly reference a declared orderId value.
In `@docs/content/docs/java/more/examples/benchmark.mdx`:
- Around line 28-65: The benchmark example in the Taskito builder setup is using
a fixed sqlite filename, which lets old jobs leak into later runs. Update the
benchmark snippet to create a per-invocation database path under the temp
directory before calling Taskito.builder().sqlite(...).open(), and use that
unique path for the whole run. Keep the rest of the benchmark flow the same, but
ensure the database is isolated so stats().completed and the latency sample only
reflect the current execution.
In `@docs/content/docs/java/more/examples/notifications.mdx`:
- Around line 121-124: The worker example is incomplete because the lambda
handlers in Worker/taskito.worker reference emailProvider, smsProvider, and
buildAndFanOutDigests() without any definitions in the page. Add the missing
helper or bean definitions near the notifications example, or update the .handle
calls to invoke concrete methods that are already defined in this doc so the
sample is runnable as written.
In `@docs/content/docs/java/more/examples/predicate-gated-jobs.mdx`:
- Around line 26-34: The sample in Policies and App uses unresolved dependencies
(`usage`, `flags`, and `isBusinessHours()`), so readers cannot copy it into a
project as written. Add the missing scaffolding or initialization for those
dependencies in the sample, or clearly mark the affected blocks as pseudocode,
and make sure the `Policies` and `App` examples are self-contained enough to
compile or intentionally non-compilable.
In `@docs/content/docs/resources/comparison.mdx`:
- Line 6: Update the Java variant in the comparison TL;DR so it uses a
consistent, non-contradictory description; the `SdkSwap` in the comparison.mdx
content currently maps `java` to “a brokered task queue,” which conflicts with
“without the broker.” Adjust the `SdkSwap` usage to match the surrounding Python
and Node phrasing by changing the Java value to a simple “a task queue,” keeping
the sentence coherent.
In `@docs/content/docs/resources/faq.mdx`:
- Around line 184-198: The Java FAQ example in the `SdkOnly` block uses `urls`
after it has only been introduced as the `.handle(fetchUrls, urls -> ...)`
lambda parameter, so the later `queue.enqueue(fetchUrls, urls)` is referencing
an out-of-scope variable. Update this snippet by declaring the input payload
before the `try` block (or otherwise binding it in scope) and then pass that
variable into both `queue.enqueue(...)` and any related calls; while you are
there, consider replacing the raw `queue.getResult(id, List.class)` usage with a
typed reference consistent with `Task<List<String>> fetchUrls`.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 7b9b06d4-4e7b-48d4-8960-b8142d62ac05
📒 Files selected for processing (107)
.github/workflows/docs.ymldocs/app/components/diagrams/arch-stack.tsxdocs/app/components/diagrams/worker-fork.tsxdocs/app/components/landing/scenario-finder.tsxdocs/app/lib/sdk-registry.tsdocs/content/docs/architecture/resources.mdxdocs/content/docs/architecture/serialization.mdxdocs/content/docs/architecture/worker-pool.mdxdocs/content/docs/java/api-reference/cli.mdxdocs/content/docs/java/api-reference/context.mdxdocs/content/docs/java/api-reference/errors.mdxdocs/content/docs/java/api-reference/index.mdxdocs/content/docs/java/api-reference/meta.jsondocs/content/docs/java/api-reference/queue.mdxdocs/content/docs/java/api-reference/resources.mdxdocs/content/docs/java/api-reference/result.mdxdocs/content/docs/java/api-reference/serializers.mdxdocs/content/docs/java/api-reference/task.mdxdocs/content/docs/java/api-reference/worker.mdxdocs/content/docs/java/api-reference/workflows.mdxdocs/content/docs/java/getting-started/capabilities.mdxdocs/content/docs/java/getting-started/concepts.mdxdocs/content/docs/java/getting-started/installation.mdxdocs/content/docs/java/getting-started/meta.jsondocs/content/docs/java/getting-started/quickstart.mdxdocs/content/docs/java/guides/core/cancellation.mdxdocs/content/docs/java/guides/core/enqueue-options.mdxdocs/content/docs/java/guides/core/execution-model.mdxdocs/content/docs/java/guides/core/index.mdxdocs/content/docs/java/guides/core/meta.jsondocs/content/docs/java/guides/core/predicates.mdxdocs/content/docs/java/guides/core/queues.mdxdocs/content/docs/java/guides/core/scheduling.mdxdocs/content/docs/java/guides/core/streaming.mdxdocs/content/docs/java/guides/core/tasks.mdxdocs/content/docs/java/guides/core/workers.mdxdocs/content/docs/java/guides/extensibility/events.mdxdocs/content/docs/java/guides/extensibility/index.mdxdocs/content/docs/java/guides/extensibility/meta.jsondocs/content/docs/java/guides/extensibility/middleware.mdxdocs/content/docs/java/guides/extensibility/serializers.mdxdocs/content/docs/java/guides/extensibility/webhooks.mdxdocs/content/docs/java/guides/index.mdxdocs/content/docs/java/guides/integrations/index.mdxdocs/content/docs/java/guides/integrations/meta.jsondocs/content/docs/java/guides/integrations/micrometer.mdxdocs/content/docs/java/guides/integrations/sentry.mdxdocs/content/docs/java/guides/integrations/spring.mdxdocs/content/docs/java/guides/meta.jsondocs/content/docs/java/guides/observability/index.mdxdocs/content/docs/java/guides/observability/logging.mdxdocs/content/docs/java/guides/observability/meta.jsondocs/content/docs/java/guides/observability/monitoring.mdxdocs/content/docs/java/guides/operations/autoscaling.mdxdocs/content/docs/java/guides/operations/backends.mdxdocs/content/docs/java/guides/operations/cli.mdxdocs/content/docs/java/guides/operations/dashboard.mdxdocs/content/docs/java/guides/operations/deployment.mdxdocs/content/docs/java/guides/operations/graalvm.mdxdocs/content/docs/java/guides/operations/index.mdxdocs/content/docs/java/guides/operations/inspection.mdxdocs/content/docs/java/guides/operations/mesh.mdxdocs/content/docs/java/guides/operations/meta.jsondocs/content/docs/java/guides/operations/security.mdxdocs/content/docs/java/guides/operations/testing.mdxdocs/content/docs/java/guides/operations/troubleshooting.mdxdocs/content/docs/java/guides/reliability/concurrency.mdxdocs/content/docs/java/guides/reliability/dead-letter.mdxdocs/content/docs/java/guides/reliability/error-handling.mdxdocs/content/docs/java/guides/reliability/guarantees.mdxdocs/content/docs/java/guides/reliability/idempotency.mdxdocs/content/docs/java/guides/reliability/index.mdxdocs/content/docs/java/guides/reliability/locks.mdxdocs/content/docs/java/guides/reliability/meta.jsondocs/content/docs/java/guides/reliability/rate-limiting.mdxdocs/content/docs/java/guides/reliability/retries.mdxdocs/content/docs/java/guides/reliability/timeouts.mdxdocs/content/docs/java/guides/resources/dependency-injection.mdxdocs/content/docs/java/guides/resources/index.mdxdocs/content/docs/java/guides/resources/interception.mdxdocs/content/docs/java/guides/resources/meta.jsondocs/content/docs/java/guides/resources/proxies.mdxdocs/content/docs/java/guides/workflows/analysis.mdxdocs/content/docs/java/guides/workflows/caching.mdxdocs/content/docs/java/guides/workflows/canvas.mdxdocs/content/docs/java/guides/workflows/conditions.mdxdocs/content/docs/java/guides/workflows/fan-out.mdxdocs/content/docs/java/guides/workflows/gates.mdxdocs/content/docs/java/guides/workflows/index.mdxdocs/content/docs/java/guides/workflows/meta.jsondocs/content/docs/java/guides/workflows/saga.mdxdocs/content/docs/java/guides/workflows/sub-workflows.mdxdocs/content/docs/java/meta.jsondocs/content/docs/java/more/examples/benchmark.mdxdocs/content/docs/java/more/examples/bulk-emails.mdxdocs/content/docs/java/more/examples/data-pipeline.mdxdocs/content/docs/java/more/examples/index.mdxdocs/content/docs/java/more/examples/meta.jsondocs/content/docs/java/more/examples/notifications.mdxdocs/content/docs/java/more/examples/predicate-gated-jobs.mdxdocs/content/docs/java/more/examples/saga-checkout.mdxdocs/content/docs/java/more/examples/spring-service.mdxdocs/content/docs/java/more/examples/web-scraper.mdxdocs/content/docs/java/more/examples/workflows.mdxdocs/content/docs/java/more/meta.jsondocs/content/docs/resources/comparison.mdxdocs/content/docs/resources/faq.mdx
There was a problem hiding this comment.
🧹 Nitpick comments (1)
docs/app/components/ui/site-nav.tsx (1)
70-151: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick winListbox lacks arrow-key roving focus; add keyboard support to match the declared ARIA pattern.
role="listbox"/role="option"implies the WAI-ARIA Listbox pattern, which expects arrow keys (and typically Home/End) to move focus among options with a single tab stop, not per-option<button>tabbing. Currently every option is independently focusable via Tab and there's noArrowUp/ArrowDownhandling, and Escape doesn't return focus to the trigger button. A similar arrow-key pattern already exists for tabs indocs/app/components/mdx/sdk.tsx'sonKeyDown, so a consistent implementation here is straightforward.♿ Sketch of arrow-key + focus-return handling
function onKeyDown(event: KeyboardEvent) { if (event.key === "Escape") { setOpen(false); + triggerRef.current?.focus(); } }Consider wiring
ArrowDown/ArrowUpon the menu container to move focus between.sdk-dd-optbuttons (roving tabindex orfocus()calls), consistent with the existing tab-navigation pattern inmdx/sdk.tsx.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/app/components/ui/site-nav.tsx` around lines 70 - 151, The SDK picker in SdkSelect declares a listbox/option pattern but still allows each .sdk-dd-opt button to be tabbed separately and has no arrow-key navigation. Update SdkSelect to use roving focus or a single tab stop with ArrowUp/ArrowDown (and Home/End if appropriate) moving focus among options, matching the keyboard pattern already used in docs/app/components/mdx/sdk.tsx. Also make Escape close the menu and return focus to the trigger button so the interaction matches the declared ARIA behavior.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@docs/app/components/ui/site-nav.tsx`:
- Around line 70-151: The SDK picker in SdkSelect declares a listbox/option
pattern but still allows each .sdk-dd-opt button to be tabbed separately and has
no arrow-key navigation. Update SdkSelect to use roving focus or a single tab
stop with ArrowUp/ArrowDown (and Home/End if appropriate) moving focus among
options, matching the keyboard pattern already used in
docs/app/components/mdx/sdk.tsx. Also make Escape close the menu and return
focus to the trigger button so the interaction matches the declared ARIA
behavior.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 6d64379d-c71a-4834-9050-5d4d4012bbfe
📒 Files selected for processing (6)
docs/app/components/docs/sidebar.tsxdocs/app/components/landing/hero.tsxdocs/app/components/ui/site-nav.tsxdocs/app/lib/highlight-lite.tsdocs/app/lib/landing-content.tsdocs/app/styles/docs.css
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds the full Java SDK section to the docs site — 93 pages mirroring the existing per-SDK structure, every API detail derived from the Java source (never invented; honest adaptations where the surface differs, e.g. no circuit breakers, no per-task rate limit, static workflow analysis).
org.byteveda:taskito, Java 17, annotation processor, bundled native library), quickstart, concepts, capabilities; tasks/workers/queues/enqueue-options/scheduling/execution-model/cancellation/streaming/predicates.maxRetries0), timeouts (no thread interrupt), error hierarchy, DLQ, idempotency, guarantees, concurrency, rate limiting (gate-based), locks (no auto-extend); resources with all five scopes incl. pooled, interception, signed proxies + sessions.taskito-testin-memory backend), inspection, mesh, autoscaling (in-process pool + Scaler/KEDA endpoint), GraalVM native-image, security, deployment (native loader, FFM fast path), troubleshooting; middleware/serializers/events/webhooks; Spring Boot 3 starter, Micrometer, Sentry.Structural parity pass
Closed the remaining page-inventory gaps against the shared per-SDK structure. Ten new pages, each verified against the Java source before writing — features the Java surface does not expose (structured notes,
dependsOn-on-enqueue, dashboard SSO / task-overrides, idempotent auto-derive) were deliberately not documented rather than invented.overview(the five-layer model —Taskito→DefaultTaskito→CoreFacade→QueueBackend→JniQueueBackend, plus theQueueper-named-queue handle vs. theTaskitoclient);canvas(link/chain/group/chord);saga(Step.compensate,WorkflowState/NodeStatuscompensation states);batching(Batcher<T>+enqueueMany/enqueueAll, disambiguated fromWorker.Builder.batchSize);testing(InMemoryTaskito/InMemoryQueueBackend, workflows unsupported, periodic registered-but-inert).core/batching(producerBatchervs. dequeuebatchSize);resources/configuration(programmatic scope +PoolConfigtuning);resources/observability(resourceMetrics()/ResourceStat);resources/testing(same-API stub registration + register-once constraint);workflows/building(fullStep.Builderknob table +NodeStatuslifecycle diagram).Nav wired via the four affected
meta.jsonfiles. Queue reference kept as a single page (the flat layout already carries the full surface); a directory split was deferred as it would duplicate the worker/webhooks guides.Site wiring
sdk-registry.ts: java registered (label Java, binding JNI) — switcher/nav/boot derive from it.SdkSwap/SdkOnlysite (serialization, worker-pool, resources architecture, FAQ, comparison, arch/worker diagrams); scenario-finder maps guides to the active SDK generically.NODE_OPTIONS=--max-old-space-size=8192— three SDK trees prerender in one pass and the default heap OOMs.Test plan
pnpm typecheck,pnpm lintpnpm build— java routes prerendered underbuild/client/java/**(all 10 new pages included)Summary by CodeRabbit