Spring Boot integration

Latest stable Based on Leader release 0.4.0

Library module

Problem

Provides Spring Boot auto-configuration, backend factories, compile-time-woven AOP for @LeaderElection/@LeaderGroupElection, SpEL lock names, failure policy, and lock scope utilities.

When to use it

Use it for Spring-managed jobs that benefit from declarative election. Use direct elector calls when ownership should remain explicit in application code.

Coordinates

Artifact: io.github.bluetape4k.leader:bluetape4k-leader-spring-boot

dependencies {
    implementation(platform("io.github.bluetape4k:bluetape4k-dependencies:<version>"))
    implementation("io.github.bluetape4k.leader:bluetape4k-leader-spring-boot")
}

Core concepts

The aspect resolves a factory, builds options, acquires, and invokes the method only when elected. Private methods are not intercepted. This project uses AspectJ compile-time weaving, so @EnableAspectJAutoProxy is not the activation switch.

Quick start

@Service
class Jobs {
    @LeaderElection(name = "daily-settlement", leaseTime = "30m")
    fun settle(): SettlementReport? = settlementService.settle()
}

API by task

Use @LeaderElection for one owner and @LeaderGroupElection for bounded parallelism. Select a factory with @LeaderElectionBackend; LockAssert/LockExtender work only inside an active scope.

Recommended patterns

Keep annotated methods externally reachable by the woven aspect, use stable or validated SpEL names, disable method invocation in SpEL unless trusted, and keep FAIL_OPEN_RUN for idempotent work only.

Integrations

Auto-configuration supports available backend clients and Micrometer recording. batch-scheduler and webhook-poller show annotation-driven jobs.

Configuration

Configure defaults under bluetape4k.leader, backend-specific properties, AOP order, failure mode, SpEL policy, single/group leases, and factory bean selection.

Failure modes

RETHROW surfaces backend failure, SKIP suppresses execution, and FAIL_OPEN_RUN executes without ownership. Invalid annotations or ambiguous factories should fail startup. Long streams need explicit renewal.

Operations

Monitor elected/skipped/failure outcomes, selected factory, resolved lock name, duration, and extension. Document fail-open decisions in the runbook.

Testing

Use application-context tests for auto-configuration and CTW interception; cover private/non-intercepted methods, SpEL, meta-annotations, failure modes, suspend/reactive results, and cancellation.

Workshops and learning path

Start with batch-scheduler, then webhook-poller and prometheus-dashboard. Read the chosen backend manual for its client and lease operations.

Limitations

AOP cannot make arbitrary side effects exactly once. Self/private invocation and long-lived streams require careful boundary testing; FAIL_OPEN_RUN permits duplicates by design.

Release diagrams

These diagrams are loaded directly from README assets published with the 0.4.0 release and pinned to its immutable commit. They describe this manual’s released structure and runtime flows, not later Snapshot changes. Select a preview to open the SVG at the same release commit.

Sources

Auto-configuration · Aspect · Stable guide