Source: https://fireflyframework.org/frameworks/java/
Language: en

jafly, the Java framework by Firefly

# The layers between Spring Boot and your business rules.

jafly provides command and query buses, saga and TCC engines, event publishing, service clients, policy-based security, and observability as reactive modules you add to Spring Boot.

[Read the documentation](https://fireflyframework.github.io/fireflyframework-jafly/) [View the source](https://github.com/fireflyframework/fireflyframework-jafly)

1. 01 Security and identity
2. 02 Business operations
3. 03 External services
4. 04 Event-driven integration
5. 05 Domain and data
6. 06 Business coordination
7. 07 Service operations
8. 08 Team-wide architecture

Java 25 · Spring Boot 4.1.1 · WebFlux · Reactor

Native stack and framework

## What jafly adds to Spring Boot and WebFlux.

Requests stay on Spring Boot and WebFlux. jafly adds modules and the bridges between them, and your team picks the adapters.

### Security and identity

Services ask a policy port whether a Firefly principal may act. Your configured adapter answers.

With Spring Boot and WebFlux alone, your team builds

The glue between Spring Security principals, method permissions, and policy providers.

jafly provides

Principal and policy ports, a JWT resource server, method security, and policy adapters.

How it works

The resource server maps a JWT to a Firefly principal and asks `PolicyDecisionPort` to allow or deny the requested URL. `@Secure` guards methods.

The embedded policy adapter is the default. The opt-in header bridge rewrites identity headers on authenticated requests. Don’t trust client-sent identity headers on permit-all paths: they pass through unchanged.

[`ResourceServerAutoConfiguration` filter chain](https://github.com/fireflyframework/fireflyframework-jafly/blob/9ff674ce8e2b60b4366abe2cd730536134fc8802/src/main/java/org/fireflyframework/security/rs/ResourceServerAutoConfiguration.java#L164-L196) [`PolicyAuthorizationManager`](https://github.com/fireflyframework/fireflyframework-jafly/blob/d20f7d203e41ed702cd80ec2cd2209c1245e2a5c/src/main/java/org/fireflyframework/security/webflux/authz/PolicyAuthorizationManager.java#L43-L56) [`OpaPolicyDecisionAdapter`](https://github.com/fireflyframework/fireflyframework-jafly/blob/25e569b4c681852497a1d514fae2d03eb54566a1/src/main/java/org/fireflyframework/security/adapter/opa/OpaPolicyDecisionAdapter.java#L53-L78) [`SecureMethodAuthorizationManager`](https://github.com/fireflyframework/fireflyframework-jafly/blob/c66bd770283dd7d7471fe8065bb29a7c46ad01c8/src/main/java/org/fireflyframework/security/method/SecureMethodAuthorizationManager.java#L56-L67) [`PrincipalHeaderBridgeWebFilter`](https://github.com/fireflyframework/fireflyframework-jafly/blob/d20f7d203e41ed702cd80ec2cd2209c1245e2a5c/src/main/java/org/fireflyframework/security/webflux/bridge/PrincipalHeaderBridgeWebFilter.java#L58-L90) [`WebFluxBridgeAutoConfiguration`](https://github.com/fireflyframework/fireflyframework-jafly/blob/d20f7d203e41ed702cd80ec2cd2209c1245e2a5c/src/main/java/org/fireflyframework/security/webflux/bridge/WebFluxBridgeAutoConfiguration.java#L30-L55)

[See the implementation](https://github.com/fireflyframework/fireflyframework-jafly/blob/9ff674ce8e2b60b4366abe2cd730536134fc8802/src/main/java/org/fireflyframework/security/rs/ResourceServerAutoConfiguration.java#L85-L119)

### Business operations

A handled command can publish its events and clear cached queries through jafly’s bridges.

With Spring Boot and WebFlux alone, your team builds

Command and query handlers that call validation, authorization, events, and caches themselves.

jafly provides

Command and query buses, a query cache, and bridges to EDA.

How it works

`CqrsEdaAutoConfiguration` adds the event bridge when an `EventPublisherFactory` exists, and the cache bridge when a query cache does.

Annotation validation runs only when a Jakarta `Validator` bean exists.

[`CqrsEdaAutoConfiguration`](https://github.com/fireflyframework/fireflyframework-jafly/blob/358c2401d9357189b765a863adb434ff3e6f3fcb/src/main/java/org/fireflyframework/cqrs/config/CqrsEdaAutoConfiguration.java#L53-L83) [`EdaCommandEventPublisher`](https://github.com/fireflyframework/fireflyframework-jafly/blob/358c2401d9357189b765a863adb434ff3e6f3fcb/src/main/java/org/fireflyframework/cqrs/event/EdaCommandEventPublisher.java#L50-L80) [`DefaultCommandBus` event publishing](https://github.com/fireflyframework/fireflyframework-jafly/blob/358c2401d9357189b765a863adb434ff3e6f3fcb/src/main/java/org/fireflyframework/cqrs/command/DefaultCommandBus.java#L340-L356)

[See the implementation](https://github.com/fireflyframework/fireflyframework-jafly/blob/358c2401d9357189b765a863adb434ff3e6f3fcb/src/main/java/org/fireflyframework/cqrs/command/DefaultCommandBus.java#L222-L264)

### External services

Teams call other services through the REST, SOAP, and gRPC builders on `ServiceClient`.

With Spring Boot and WebFlux alone, your team builds

Client wrappers with retry and failure conventions you define per protocol.

jafly provides

Protocol builders with error mapping and configurable retry and circuit-breaker policies.

How it works

`ServiceClient` builds REST, SOAP, and gRPC clients. REST calls retry with backoff inside a per-service circuit breaker.

REST policies don’t extend to SOAP or gRPC. REST clients retry up to three times by default. Call `noRetry()` on a request that isn’t safe to repeat.

[`RestServiceClientImpl`](https://github.com/fireflyframework/fireflyframework-jafly/blob/7456cf32b70ee67350f0e4fb0b526a93eeac8b1b/src/main/java/org/fireflyframework/client/impl/RestServiceClientImpl.java#L510-L552) [`ServiceClientAutoConfiguration`](https://github.com/fireflyframework/fireflyframework-jafly/blob/7456cf32b70ee67350f0e4fb0b526a93eeac8b1b/src/main/java/org/fireflyframework/client/config/ServiceClientAutoConfiguration.java#L98-L154) [`GraphQLClientHelper`](https://github.com/fireflyframework/fireflyframework-jafly/blob/7456cf32b70ee67350f0e4fb0b526a93eeac8b1b/src/main/java/org/fireflyframework/client/graphql/GraphQLClientHelper.java#L221-L243)

[See the implementation](https://github.com/fireflyframework/fireflyframework-jafly/blob/7456cf32b70ee67350f0e4fb0b526a93eeac8b1b/src/main/java/org/fireflyframework/client/ServiceClient.java#L70-L109)

### Event-driven integration

Modules publish through the event core’s API, and the deployment picks Spring events, Kafka, RabbitMQ, or PostgreSQL.

With Spring Boot and WebFlux alone, your team builds

Envelopes, listeners, and failure handling per broker, and the code that picks a transport.

jafly provides

Event contracts with selectable transports for publishing and consuming.

How it works

`EventPublisherFactory` selects a publisher by type and connection. The PostgreSQL consumer listens for notifications and polls as a fallback.

The PostgreSQL publisher writes on its own connection, outside your business transaction.

[`EventPublisherFactory` auto-selection](https://github.com/fireflyframework/fireflyframework-jafly/blob/b97ff7ab2eb003acbb7c7fbc00e5940bae7fb462/src/main/java/org/fireflyframework/eda/publisher/EventPublisherFactory.java#L258-L283) [`PostgresEventPublisher`](https://github.com/fireflyframework/fireflyframework-jafly/blob/8f54eeaedc6d3a991af018da904f37e603488db1/src/main/java/org/fireflyframework/eda/publisher/postgres/PostgresEventPublisher.java#L119-L140) [`PostgresEventConsumer`](https://github.com/fireflyframework/fireflyframework-jafly/blob/8f54eeaedc6d3a991af018da904f37e603488db1/src/main/java/org/fireflyframework/eda/consumer/postgres/PostgresEventConsumer.java#L266-L298) [`EdaOrchestrationEventPublisher`](https://github.com/fireflyframework/fireflyframework-jafly/blob/5ed9d67c2a2ecf62c6cb7a9ab9e34ee11fb4a126/src/main/java/org/fireflyframework/orchestration/core/event/EdaOrchestrationEventPublisher.java#L77-L106)

[See the implementation](https://github.com/fireflyframework/fireflyframework-jafly/blob/b97ff7ab2eb003acbb7c7fbc00e5940bae7fb462/src/main/java/org/fireflyframework/eda/publisher/EventPublisherFactory.java#L63-L102)

### Domain and data

Queries share filter and paging helpers. A service that needs event history adds the event-sourcing module.

With Spring Boot and WebFlux alone, your team builds

Repository, filtering, aggregate, and event-history conventions, built on Spring Data.

jafly provides

R2DBC filtering and pagination helpers. An optional module adds event sourcing with snapshots and projections.

How it works

`FilterUtils` turns a filter DTO into a paged PostgreSQL query. `R2dbcEventStore` appends after an expected-version check and writes a configured outbox in the same transaction.

Event sourcing applies only where you choose it. Other table writes need explicit transaction wiring, and version checks don’t make processing exactly once.

[`R2dbcEventStore` append](https://github.com/fireflyframework/fireflyframework-jafly/blob/a249a11d8e204b0b42229ae8e8688180317424e5/src/main/java/org/fireflyframework/eventsourcing/store/r2dbc/R2dbcEventStore.java#L113-L149) [`R2dbcEventStore` outbox write](https://github.com/fireflyframework/fireflyframework-jafly/blob/a249a11d8e204b0b42229ae8e8688180317424e5/src/main/java/org/fireflyframework/eventsourcing/store/r2dbc/R2dbcEventStore.java#L573-L591) [`EventSourcingPublisher`](https://github.com/fireflyframework/fireflyframework-jafly/blob/a249a11d8e204b0b42229ae8e8688180317424e5/src/main/java/org/fireflyframework/eventsourcing/publisher/EventSourcingPublisher.java#L65-L90) [`EventOutboxService`](https://github.com/fireflyframework/fireflyframework-jafly/blob/a249a11d8e204b0b42229ae8e8688180317424e5/src/main/java/org/fireflyframework/eventsourcing/outbox/EventOutboxService.java#L164-L211)

[See the implementation](https://github.com/fireflyframework/fireflyframework-jafly/blob/a6c43f35b0453661b400218c1b77ab68359d2b87/src/main/java/org/fireflyframework/core/filters/FilterUtils.java#L100-L160)

### Business coordination

A saga’s steps declare their dependencies and compensations, and the saga result carries an execution report.

With Spring Boot and WebFlux alone, your team builds

Step dependencies, recovery state, and compensating actions, assembled around service calls.

jafly provides

Coordination engines with execution reports and bridges to the event and telemetry modules.

How it works

After compensation, `SagaEngine` sends failed steps to a dead-letter store, in memory unless you supply one, and records the final state.

Lifecycle events need an EDA publisher and are off by default. A failed state write is logged and skipped. Test restart recovery before you rely on it.

[`SagaCompensator`](https://github.com/fireflyframework/fireflyframework-jafly/blob/5ed9d67c2a2ecf62c6cb7a9ab9e34ee11fb4a126/src/main/java/org/fireflyframework/orchestration/saga/compensation/SagaCompensator.java#L84-L111) [`OrchestrationAutoConfiguration` event bridge](https://github.com/fireflyframework/fireflyframework-jafly/blob/5ed9d67c2a2ecf62c6cb7a9ab9e34ee11fb4a126/src/main/java/org/fireflyframework/orchestration/config/OrchestrationAutoConfiguration.java#L139-L172) [`OrchestrationTracingAutoConfiguration`](https://github.com/fireflyframework/fireflyframework-jafly/blob/5ed9d67c2a2ecf62c6cb7a9ab9e34ee11fb4a126/src/main/java/org/fireflyframework/orchestration/config/OrchestrationTracingAutoConfiguration.java#L35-L47)

[See the implementation](https://github.com/fireflyframework/fireflyframework-jafly/blob/5ed9d67c2a2ecf62c6cb7a9ab9e34ee11fb4a126/src/main/java/org/fireflyframework/orchestration/saga/engine/SagaEngine.java#L174-L200)

### Service operations

Every metric in a service’s registry carries application and environment tags.

With Spring Boot and WebFlux alone, your team builds

Metric tags, health checks, and management endpoints, set up per service.

jafly provides

An observability module that tags and correlates the telemetry you configure.

How it works

A `WebClient` customizer forwards `X-Transaction-Id`. The command bus records metrics, and orchestration traces each run when an observation registry exists.

`X-Transaction-Id` correlates calls and starts no distributed transaction. Check trace propagation on the service client: it builds its own `WebClient`.

[`FireflyMeterRegistryCustomizer`](https://github.com/fireflyframework/fireflyframework-jafly/blob/9411475fd29bc7331ef572aee779106fbcbf871e/src/main/java/org/fireflyframework/observability/metrics/FireflyMeterRegistryCustomizer.java#L22-L28) [`TracingWebClientCustomizer`](https://github.com/fireflyframework/fireflyframework-jafly/blob/9411475fd29bc7331ef572aee779106fbcbf871e/src/main/java/org/fireflyframework/observability/tracing/TracingWebClientCustomizer.java#L12-L42) [`DefaultCommandBus` metrics](https://github.com/fireflyframework/fireflyframework-jafly/blob/358c2401d9357189b765a863adb434ff3e6f3fcb/src/main/java/org/fireflyframework/cqrs/command/DefaultCommandBus.java#L180-L209) [`OrchestrationTracingAutoConfiguration`](https://github.com/fireflyframework/fireflyframework-jafly/blob/5ed9d67c2a2ecf62c6cb7a9ab9e34ee11fb4a126/src/main/java/org/fireflyframework/orchestration/config/OrchestrationTracingAutoConfiguration.java#L35-L47)

[See the implementation](https://github.com/fireflyframework/fireflyframework-jafly/blob/9411475fd29bc7331ef572aee779106fbcbf871e/src/main/java/org/fireflyframework/observability/FireflyObservabilityAutoConfiguration.java#L34-L83)

### Team-wide architecture

Platform teams pin module versions in one BOM, and starters pull in the modules for a service layer.

With Spring Boot and WebFlux alone, your team builds

Dependency version alignment, service-layer bundles, and shared wiring.

jafly provides

A parent POM, a BOM, and starters that bring in a service layer’s modules.

How it works

The domain starter bundles CQRS, orchestration, the client, and EDA.

Starters leave each module’s activation defaults as they are. Your service’s tests should cover the set it uses.

[BOM security modules](https://github.com/fireflyframework/fireflyframework-jafly/blob/8448f7e2e97b81a613cfcaed83f0f668d50074cf/pom.xml#L238-L257) [Domain starter POM](https://github.com/fireflyframework/fireflyframework-jafly/blob/184e76fd7c3dc16d498c35876455043ede5a3ad1/pom.xml#L110-L135) [Application starter security](https://github.com/fireflyframework/fireflyframework-jafly/blob/ac381ac5015b7973eaa5f9c2a6e738b5f5bd65d4/pom.xml#L46-L77) [Application starter modules](https://github.com/fireflyframework/fireflyframework-jafly/blob/ac381ac5015b7973eaa5f9c2a6e738b5f5bd65d4/pom.xml#L103-L140) [Parent POM versions](https://github.com/fireflyframework/fireflyframework-jafly/blob/2a5704f784bf588807f5e97de363877de98e3355/pom.xml#L37-L58)

[See the implementation](https://github.com/fireflyframework/fireflyframework-jafly/blob/8448f7e2e97b81a613cfcaed83f0f668d50074cf/pom.xml#L79-L155)

Already in the native stack

Spring provides dependency injection, WebFlux request validation, reactive method authorization, and data access. A team with established Spring conventions may already have a command coordinator.

Your team still owns

Business rules, permission decisions, trusted actor and tenant context, compensating actions, and consumer idempotency. The command bus doesn’t make a command transactional or exactly once.

Request path

## How a command moves through jafly.

Your handler makes the business decision. Annotations on the command handler and the query handlers decide which events go out and which ones clear the query cache.

### A business command, its events, and the query cache

1. Your service sends a command through the command bus.
2. The bus validates the command and runs its `authorize()` check.
3. A `@PublishDomainEvent` handler’s result goes to the CQRS and EDA bridge.
4. `EventPublisherFactory` picks the first available transport in its `AUTO` order.
5. The cache bridge clears the whole query cache when a query handler’s `@InvalidateCacheOn` lists the event’s type.

A command still succeeds if its event fails to publish. The cache bridge listens for Spring application events, and broker events reach it only if you connect them.

[CQRS and EDA bridge configuration](https://github.com/fireflyframework/fireflyframework-jafly/blob/358c2401d9357189b765a863adb434ff3e6f3fcb/src/main/java/org/fireflyframework/cqrs/config/CqrsEdaAutoConfiguration.java#L53-L83)

Capabilities

## Pick the modules your service needs.

jafly / Conceptual architecture

HTTP endpoints call command handlers, which can use reactive transactions.

1. [01Idempotent HTTP requests](https://fireflyframework.org/frameworks/java/#java-capability-0)
2. [02Commands and queries](https://fireflyframework.org/frameworks/java/#java-capability-1)
3. [03Sagas with compensation](https://fireflyframework.org/frameworks/java/#java-capability-2)
4. [04Try, confirm, cancel](https://fireflyframework.org/frameworks/java/#java-capability-3)
5. [05Reactive data access](https://fireflyframework.org/frameworks/java/#java-capability-4)
6. [06Metrics, tracing, and health](https://fireflyframework.org/frameworks/java/#java-capability-5)

Amber: Firefly modules · Ivory lines: APIs · Amber lines: events

### Idempotent HTTP requests

When a controller request repeats its `X-Idempotency-Key` header, the web module returns the stored response instead of calling the handler again.

[See the source](https://github.com/fireflyframework/fireflyframework-jafly/blob/98def5274991f5fe54f345af8207c5b70046e299/src/main/java/org/fireflyframework/web/idempotency/config/IdempotencyAutoConfiguration.java#L109-L164)

### Commands and queries

Writes and reads go to separate buses and handlers. The query bus can answer a repeated query from a configured cache.

[See the source](https://github.com/fireflyframework/fireflyframework-jafly/blob/358c2401d9357189b765a863adb434ff3e6f3fcb/src/main/java/org/fireflyframework/cqrs/command/DefaultCommandBus.java#L132-L185)

### Sagas with compensation

Saga steps declare their dependencies and a compensation method. When a step fails, `SagaEngine` compensates the completed steps, in reverse order by default.

[See the source](https://github.com/fireflyframework/fireflyframework-jafly/blob/5ed9d67c2a2ecf62c6cb7a9ab9e34ee11fb4a126/src/main/java/org/fireflyframework/orchestration/saga/engine/SagaEngine.java#L111-L185)

### Try, confirm, cancel

`TccEngine` runs a try phase, then confirms or cancels. It records the outcome as confirmed, canceled, or failed.

[See the source](https://github.com/fireflyframework/fireflyframework-jafly/blob/5ed9d67c2a2ecf62c6cb7a9ab9e34ee11fb4a126/src/main/java/org/fireflyframework/orchestration/tcc/engine/TccEngine.java#L102-L165)

### Reactive data access

The R2DBC module bundles Spring Data R2DBC with the PostgreSQL driver. `R2dbcMetrics` times and counts the queries your repositories wrap.

[See the source](https://github.com/fireflyframework/fireflyframework-jafly/blob/a6c43f35b0453661b400218c1b77ab68359d2b87/src/main/java/org/fireflyframework/core/observability/R2dbcObservabilityAutoConfiguration.java#L35-L56)

### Metrics, tracing, and health

The observability module adds application and environment tags, a tracing helper, and a health-to-metrics bridge. A `firefly.observability` property switches each off.

[See the source](https://github.com/fireflyframework/fireflyframework-jafly/blob/9411475fd29bc7331ef572aee779106fbcbf871e/src/main/java/org/fireflyframework/observability/FireflyObservabilityAutoConfiguration.java#L32-L83)

### The Java modules behind each feature.

#### Orchestration

The saga, TCC, and workflow engines all live in this module. They share its execution context, retry policies, persistence, and recovery.

[Read the module guide](https://fireflyframework.github.io/fireflyframework-jafly/modules/orchestration/)

#### Events

The event core has a single publisher and listener API, with in-process Spring events built in. Kafka, RabbitMQ, and PostgreSQL are separate adapter modules.

[Read the module guide](https://fireflyframework.github.io/fireflyframework-jafly/modules/eda/)

#### Security core

This module evaluates `@Secure` rules and runs the embedded policy decision point. A missing principal or a policy error denies access.

[Read the module guide](https://fireflyframework.github.io/fireflyframework-jafly/modules/security-core/)

#### R2DBC

Flyway comes bundled for schema migrations, and the health indicator probes the database with `SELECT 1`.

[Read the module guide](https://fireflyframework.github.io/fireflyframework-jafly/modules/r2dbc/)

#### Service clients

Outbound calls can find services through Eureka, Consul, Kubernetes, or a static list. The module also has OAuth2, API-key, and certificate-pinning helpers.

[Read the module guide](https://fireflyframework.github.io/fireflyframework-jafly/modules/client/)

#### Observability

Micrometer’s Observation API is the base, with OpenTelemetry as the default tracing bridge. The Logback configuration writes JSON logs with trace ids.

[Read the module guide](https://fireflyframework.github.io/fireflyframework-jafly/modules/observability/)

Code

## Read a saga from the loan application.

`RegisterApplicationSaga` sends its steps’ commands through the command bus. If a later step fails, `removeLoanApplication` deletes the application the root step created.

### Walk through Lumen Lending

1. #### Open the workspace

   Lumen Lending has three tiers: an experience API, a domain service, and the core system of record.
2. #### Start the saga

   `LoanOriginationService` builds the step inputs and runs the saga by name through `SagaEngine`.

   [See the source](https://github.com/fireflyframework/fireflyframework-java-book/blob/4ba0eb53ecced41ffa7e8d2bed948dfd7f5b40ec/samples/lumen-lending/domain-lending-loan-origination/src/main/java/com/firefly/lumen/domain/service/LoanOriginationService.java#L46-L57)
3. #### Check the compensation

   `RegisterApplicationSagaCompensationTest` fails the offer step and checks that the new application is removed.

   [See the source](https://github.com/fireflyframework/fireflyframework-java-book/blob/4ba0eb53ecced41ffa7e8d2bed948dfd7f5b40ec/samples/lumen-lending/domain-lending-loan-origination/src/test/java/com/firefly/lumen/domain/saga/RegisterApplicationSagaCompensationTest.java#L44-L64)

RegisterApplicationSaga.java

```java
    @SagaStep(id = STEP_REGISTER_LOAN_APPLICATION, compensate = COMPENSATE_REMOVE_LOAN_APPLICATION)
    @StepEvent(type = EVENT_LOAN_APPLICATION_REGISTERED)
    public Mono<UUID> registerLoanApplication(RegisterLoanApplicationCommand command, ExecutionContext ctx) {
        return commandBus.send(command)
                .doOnNext(loanApplicationId -> ctx.putVariable(CTX_LOAN_APPLICATION_ID, loanApplicationId));
    }

    /** Compensation for the root step: delete the application created above. */
    public Mono<Void> removeLoanApplication(UUID loanApplicationId) {
        return client.removeLoanApplication(loanApplicationId);
    }

    // ---------------------------------------------------------------------
    // Dependent step: attach the applicant party (after the root step).
    // ---------------------------------------------------------------------

    @SagaStep(id = STEP_REGISTER_APPLICANT,
            compensate = COMPENSATE_REMOVE_APPLICANT,
            dependsOn = STEP_REGISTER_LOAN_APPLICATION)
    @StepEvent(type = EVENT_APPLICANT_REGISTERED)
    public Mono<UUID> registerApplicant(RegisterApplicantCommand command, ExecutionContext ctx) {
        UUID loanApplicationId = ctx.getVariableAs(CTX_LOAN_APPLICATION_ID, UUID.class);
        return commandBus.send(command.withLoanApplicationId(loanApplicationId));
    }
```

[View the full file](https://github.com/fireflyframework/fireflyframework-java-book/blob/4ba0eb53ecced41ffa7e8d2bed948dfd7f5b40ec/samples/lumen-lending/domain-lending-loan-origination/src/main/java/com/firefly/lumen/domain/saga/RegisterApplicationSaga.java#L80-L103)

### Validation and authorization before the handler

A failed check ends the chain before your handler runs. jafly runs validation before authorization, and each command defines its own checks.

DefaultCommandBus.java · lines 244–262

```java
                    return validationService.validateCommand(command)
                            .then(Mono.defer(() -> {
                                // Step 4: Authorize command with context (if authorization is enabled)
                                if (authorizationService != null) {
                                    return authorizationService.authorizeCommand(command, context);
                                } else {
                                    return Mono.empty(); // Skip authorization
                                }
                            }))
                            .then(Mono.defer(() -> {
                                // Step 5: Execute handler with context
                                try {
                                    return handler.handle(command, context);
                                } catch (Exception e) {
                                    return Mono.error(CommandProcessingException.forCommandFailure(
                                        command, handler, Duration.between(startTime, Instant.now()), e
                                    ));
                                }
                            }))
```

[View the full file](https://github.com/fireflyframework/fireflyframework-jafly/blob/358c2401d9357189b765a863adb434ff3e6f3fcb/src/main/java/org/fireflyframework/cqrs/command/DefaultCommandBus.java#L244-L262)

Releases and setup

## Install jafly and follow the book.

Register a handler for the commands you send. Override `authorize()` on any command that needs a permission check, because the default allows it.

The cited modules publish v26.07.06, with tests for command authorization, saga compensation, and filtering. The parent pins Spring Boot 3.5.10.

Orchestration state is in memory unless you configure Redis, a cache, or event sourcing. Compensation is not an atomic rollback of external systems.

[Read the documentation](https://fireflyframework.github.io/fireflyframework-jafly/) [View releases](https://github.com/fireflyframework/fireflyframework-jafly/releases)

### Choose the release’s Java toolchain

jafly’s current train uses Java 25. Older parents may include a Java 21 source-build profile; check the requirements of the release you use.

[Read the cited parent profile](https://github.com/fireflyframework/fireflyframework-jafly/blob/2a5704f784bf588807f5e97de363877de98e3355/pom.xml#L715-L725)

Front cover of jafly by example

### jafly by example

From Spring Boot to a connected enterprise architecture

The book builds Lumen Lending, a personal-loan origination service, through reactive APIs, domain modeling, orchestration, and infrastructure. Its code listings come from the sample, which CI builds and tests.

[Read the manuscript](https://github.com/fireflyframework/fireflyframework-java-book/tree/books-2026.10.08/manuscript)
- [English PDF](https://github.com/fireflyframework/fireflyframework-java-book/releases/download/books-2026.10.08/firefly-java-by-example.pdf)
- [English EPUB](https://github.com/fireflyframework/fireflyframework-java-book/releases/download/books-2026.10.08/firefly-java-by-example.epub)
- [Spanish PDF](https://github.com/fireflyframework/fireflyframework-java-book/releases/download/books-2026.10.08/firefly-java-by-example-es.pdf)
- [Spanish EPUB](https://github.com/fireflyframework/fireflyframework-java-book/releases/download/books-2026.10.08/firefly-java-by-example-es.epub)

October 2026 edition

Related

## The catalog, the sample, and the CLI.

### Module catalog

Every jafly component by capability, with configuration and examples.

[Browse the catalog](https://fireflyframework.github.io/fireflyframework-jafly/modules/)

### Lumen Lending sample

The book’s loan-origination application, with the saga, its command handlers, and their tests.

[View the source](https://github.com/fireflyframework/fireflyframework-java-book/tree/4ba0eb53ecced41ffa7e8d2bed948dfd7f5b40ec/samples/lumen-lending)

### Firefly CLI

Scaffolds Java services and checks that Java, Maven, and Git are set up.

[View the source](https://github.com/fireflyframework/fireflyframework-cli)

Sources behind this page

- [Java build configuration](https://github.com/fireflyframework/fireflyframework-jafly/blob/2a5704f784bf588807f5e97de363877de98e3355/pom.xml)
- [Command bus tests](https://github.com/fireflyframework/fireflyframework-jafly/blob/358c2401d9357189b765a863adb434ff3e6f3fcb/src/test/java/org/fireflyframework/cqrs/command/CommandBusTest.java)
- [Saga engine unit tests](https://github.com/fireflyframework/fireflyframework-jafly/blob/5ed9d67c2a2ecf62c6cb7a9ab9e34ee11fb4a126/src/test/java/org/fireflyframework/orchestration/unit/saga/SagaEngineTest.java)
- [Validation setup and conditional authorization](https://github.com/fireflyframework/fireflyframework-jafly/blob/358c2401d9357189b765a863adb434ff3e6f3fcb/src/main/java/org/fireflyframework/cqrs/config/CqrsAutoConfiguration.java#L58-L119)
- [Default command authorization](https://github.com/fireflyframework/fireflyframework-jafly/blob/358c2401d9357189b765a863adb434ff3e6f3fcb/src/main/java/org/fireflyframework/cqrs/command/Command.java#L368-L370)
- [Authorization behavior tests](https://github.com/fireflyframework/fireflyframework-jafly/blob/358c2401d9357189b765a863adb434ff3e6f3fcb/src/test/java/org/fireflyframework/cqrs/authorization/AuthorizationIntegrationTest.java#L66-L128)
- [Saga compensation integration test](https://github.com/fireflyframework/fireflyframework-jafly/blob/5ed9d67c2a2ecf62c6cb7a9ab9e34ee11fb4a126/src/test/java/org/fireflyframework/orchestration/integration/SagaIntegrationTest.java#L75-L101)
- [Saga persistence failure handling](https://github.com/fireflyframework/fireflyframework-jafly/blob/5ed9d67c2a2ecf62c6cb7a9ab9e34ee11fb4a126/src/main/java/org/fireflyframework/orchestration/saga/engine/SagaEngine.java#L224-L253)
- [Spring WebFlux validation](https://docs.spring.io/spring-framework/reference/6.2/web/webflux/controller/ann-validation.html)
- [Spring reactive method authorization](https://docs.spring.io/spring-security/reference/6.5/reactive/authorization/method.html)
- [Spring Data R2DBC query foundation](https://docs.spring.io/spring-data/relational/reference/r2dbc/entity-persistence.html)
- [Historical CQRS source tag v26.07.06](https://github.com/fireflyframework/fireflyframework-jafly/tree/legacy/fireflyframework-cqrs/v26.07.06)

Next step

## Run the loan application’s saga test.

[Read the documentation](https://fireflyframework.github.io/fireflyframework-jafly/) [Open the sample](https://github.com/fireflyframework/fireflyframework-java-book/tree/4ba0eb53ecced41ffa7e8d2bed948dfd7f5b40ec/samples/lumen-lending)
