flydocs-examples

flydocs Java SDK — Examples

Runnable reactive examples mirroring the Python SDK's example set one-to-one. Each example is a single self-contained class; shared schemas + rules live in ExampleHelpers.

#	Class	Mirrors	What it shows
1	FirstExtractionExample	01_first_extraction.py	Smallest reactive extraction; hand-written DocumentTypeSpec; try-with-resources on the client.
2	TypedSchemaAndRulesExample	02_typed_schema_and_rules.py	Realistic invoice schema + two business rules + opt-in judge + ruleEngine stages.
3	AsyncJobWithWaitExample	03_async_job_with_wait.py	Submit + waitForCompletion + getResult as a single chained Mono pipeline.
4	WebhookReceiverApplication	04_webhook_receiver_fastapi.py	Spring Boot starter + @FlydocsWebhook resolver injecting a verified EventEnvelope.
5	ErrorHandlingExample	05_error_handling.py	Typed FlydocsHttpException / FlydocsTimeoutException; sync→async fallback on timeout.
6	SyncFacadeExample	06_sync_facade.py	The blocking FlydocsClient facade for non-reactive callers.

Plus ExampleHelpers — the examples_helpers.py analogue (shared invoice schema + rules + base-URL resolution).

Running

Spin up a local flydocs first:

task docker:up:test     # serves http://localhost:8080 backed by the mock LLM

Then run any example. The plain extractor / async / sync ones take a PDF path as -Dexec.args:

mvn -pl flydocs-examples compile exec:java \
  -Dexec.mainClass=com.firefly.flydocs.examples.FirstExtractionExample \
  -Dexec.args="path/to/invoice.pdf"

mvn -pl flydocs-examples compile exec:java \
  -Dexec.mainClass=com.firefly.flydocs.examples.TypedSchemaAndRulesExample \
  -Dexec.args="path/to/invoice.pdf"

mvn -pl flydocs-examples compile exec:java \
  -Dexec.mainClass=com.firefly.flydocs.examples.AsyncJobWithWaitExample \
  -Dexec.args="path/to/document.pdf"

mvn -pl flydocs-examples compile exec:java \
  -Dexec.mainClass=com.firefly.flydocs.examples.ErrorHandlingExample \
  -Dexec.args="path/to/invoice.pdf"

mvn -pl flydocs-examples compile exec:java \
  -Dexec.mainClass=com.firefly.flydocs.examples.SyncFacadeExample \
  -Dexec.args="path/to/invoice.pdf"

The webhook receiver is a Spring Boot app — run it with spring-boot:run:

FLYDOCS_BASE_URL=http://localhost:8080 \
FLYDOCS_WEBHOOK_SECRET=super-secret \
  mvn -pl flydocs-examples spring-boot:run \
    -Dspring-boot.run.mainClass=com.firefly.flydocs.examples.WebhookReceiverApplication

Then POST a flydocs-signed envelope to http://localhost:8080/flydocs/webhook with the X-Flydocs-Signature header set to sha256=<hex>. The starter's @FlydocsWebhook resolver verifies and deserialises the payload into an EventEnvelope automatically.

Configuration

Every example reads FLYDOCS_BASE_URL from the environment; if unset it defaults to http://localhost:8080. Point at any flydocs deployment to run against real infrastructure.

The mock LLM that task docker:up:test brings up accepts any document and returns a fixed schema-compatible response, so the examples work end-to-end without an Anthropic / OpenAI key.

Not deployed

flydocs-examples carries <maven.deploy.skip>true</maven.deploy.skip> so the module is compile-checked in CI but never published to GitHub Packages.