Hazelcast backend

Latest stable Based on Leader release 0.4.0

Library module

Problem

Implements single and fixed-slot group election with Hazelcast IMap TTL entries and owner tokens. Blocking, future, and coroutine paths share the Core skip-on-contention contract.

When to use it

Choose it when the application already operates a Hazelcast cluster and wants coordination in the same failure domain.

Coordinates

Artifact: io.github.bluetape4k.leader:bluetape4k-leader-hazelcast

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

Core concepts

putIfAbsent plus TTL acquires a token-owned entry. The lock is not thread-bound; extend and release must still verify the token so an old holder cannot modify a newer lease.

Quick start

val elector = HazelcastLeaderElector(
    hazelcastInstance,
    LeaderElectionOptions(leaseTime = 30.seconds)
)
elector.runIfLeader("cache-warmer") { warmCache() }

API by task

Use single/group electors and suspend variants; factories connect framework integrations. State APIs read the shared map but do not grant execution rights.

Recommended patterns

Keep the Hazelcast instance caller-owned, use stable lock names, leave capacity for election maps, and make protected work idempotent.

Integrations

Spring factories can use a HazelcastInstance. The cache-warmer example demonstrates an ordinary scheduled workload.

Configuration

Tune wait, lease, minimum lease, group size, cluster discovery, split-brain protection, and map backup policy. The default single-lock map is bluetape4k:leader:locks.

Failure modes

Contention returns null. Cluster disconnects, serialization/configuration errors, and owner-safe extend/release failures propagate. TTL expiry can overlap a paused old action.

Operations

Monitor cluster membership, partition migration, map operation latency, backup health, extension failures, and skip rate.

Testing

Use a multi-member test cluster for contention, partition/membership changes, TTL expiry, owner-token release, group slots, and suspend cancellation.

Workshops and learning path

Run cache-warmer, then compare the in-memory distributed model with Redis and MongoDB backends.

Limitations

Hazelcast availability and split-brain policy become election dependencies. TTL ownership is not an external fencing token.

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

Elector · Lock implementation · Stable guide