Hazelcast Migration

LoomCache is not a Hazelcast member implementation and it does not accept Hazelcast clients. Migrate it as a client API, configuration, and operations change: replace the dependency, map each data structure to a LoomCache facade, and test failure behavior under Raft replication.

Recommended path

1. Inventory Hazelcast APIs in use: data structures, SQL, CP primitives, Spring Cache, MapStore, discovery, security, and management endpoints.
2. Replace the client bootstrap and connect to explicit LoomCache seeds.
3. Migrate one data structure at a time, keeping object names stable where possible.
4. Run shadow reads or dual writes for critical maps.
5. Rehearse member restart, leader failover, and snapshot restore with production-like data.

Client bootstrap

LoomClient client = LoomClient.builder()
    .addSeed("loomcache-0.loomcache-headless.loomcache.svc.cluster.local:7654")
    .addSeed("loomcache-1.loomcache-headless.loomcache.svc.cluster.local:7654")
    .addSeed("loomcache-2.loomcache-headless.loomcache.svc.cluster.local:7654")
    .strictHandshake(true)
    .build();
client.connect();

// Production map values must use documented scalar/binary encodings in this release.
LoomMap<String, String> customers = client.getMap("customers");

Spring applications can use loom-spring-boot for LoomClient, AsyncLoomClient, LoomCacheManager, REST controllers, Spring Session, actuator health, and optional embedded server beans.

API mapping

Hazelcast API	LoomCache API	Notes
IMap<K,V>	LoomMap<K,V>	Get, put, putAll, putIfAbsent, delete, scan, getAll, listeners, near cache, stats, SQL helpers, and selected atomic map operations.
Spring Cache	LoomCacheManager	Cache names map to LoomCache map names.
IQueue<E>	LoomQueue<E>	Client facade supports offer, poll, peek, size, drain, bulk offer, bounded bulk poll/drain, and async variants. QueueStore snapshot/restart parity is not production-supported yet.
ISet<E>	LoomSet<E>	Add, remove, contains, size, clear, members, scan, and async operations.
ITopic<E>	LoomTopic<E>	Publish/subscribe over the current client-managed polling path; do not assume Hazelcast-style push dispatch semantics.
ReliableTopic<E>	LoomReliableTopic<E>	Ringbuffer-backed replay; validate retention settings.
MultiMap<K,V>	LoomMultiMap<K,V>	Dedicated client facade and REST controller.
IList<E>	LoomList<E>	Dedicated client facade and REST controller.
Ringbuffer<E>	LoomRingbuffer<E>	Dedicated client facade; embedded persistence uses RingbufferStore.
FlakeIdGenerator	LoomIdGenerator	Snowflake-style IDs; verify bit-layout assumptions.
PNCounter, GSet, ORSet, LWWRegister	LoomPNCounter, LoomGSet, LoomORSet, LoomLWWRegister	CRDT facades for AP-style state, not linearizable coordination.
FencedLock and CP primitives	LoomAtomicLong; embedded ConsistencySubsystem	CP_ATOMIC_* is the supported wire CP surface. Wire locks and semaphores fail closed in production until session lifecycle opcodes exist.
Hazelcast SQL	LoomCache SQL	Map-scoped SELECT support exists. CREATE INDEX and declarative SQL indexes are unsupported/rejected in this release. No Jet job model.
MapStore / MapLoader	No production equivalent	MapStore, MapLoader, EntryStore, and JDBC generic MapStore are fully disabled/fail-closed in production for this release. Treat any SPI use as non-production integration work only.
Management Center	REST, JMX, Prometheus, Grafana	Use management REST endpoints, MXBeans, metrics, bundled dashboards, and sample alerts.

Configuration changes

Hazelcast concept	LoomCache equivalent
Member port 5701	Direct JVM/default ClusterConfig member port is 5701; the Kubernetes samples expose the member service on 7654.
backup-count / async-backup-count	Raft majority replication; no async backup count knob.
Partition count	271 smart-routing partitions by default plus the server migration-slot table.
In-memory format	Kryo-serialized payloads; no OBJECT or NATIVE toggle.
Serialization config	Explicit Kryo IDs, Compact serializers, GenericRecord, or the global serializer SPI. There is no Hazelcast-like implicit POJO object mode.
Kubernetes discovery	Use explicit seeds, the sample StatefulSet headless service, or included discovery providers.
TLS / mTLS	Configure tls.* or loomcache.tls.* keystore, truststore, client-auth, and hot reload settings.

Gotchas

• Hazelcast clients and XML/YAML config files are not wire-compatible with LoomCache.
• Writes acknowledge after Raft majority commit, so latency and minority-partition behavior differ.
• Reads are linearizable by default; local backup reads are opt-in and may be stale.
• SQL targets maps only. There is no Jet pipeline, CDC connector suite, or multi-language client set.
• Kryo class IDs must be stable and identical across clients and members before data is written.
• Arbitrary LoomMap<K,V> POJO values are not production-supported in this release; use documented scalar/binary encodings until the public map path is certified through client round-trip, Raft apply, WAL replay, snapshot restore, and restart tests.
• Production sharding is unsupported/fail-closed until per-group WAL, snapshot, install-snapshot, and restart recovery exists; certify on the default single replicated Raft group unless the release notes say otherwise.
• Server-side LRU, LFU, finite max-entry/max-memory eviction, and max-idle are unsupported for production parity until eviction decisions are Raft-applied and proven through WAL/snapshot/restart tests.
• There is no off-heap/NATIVE memory tier.

Cutover checklist

• Map every Hazelcast object name to a LoomCache object name and facade.
• Port client bootstrap, TLS, auth, and serializer registration.
• Restore a staging snapshot with production-like serialized classes.
• Compare counts, sampled reads, SQL results, TTL behavior, listener events, and MapStore effects.
• Run restart, leader-failover, network-partition, and restore drills.
• Enable Prometheus scraping, import Grafana dashboards, and load the alert rules.
• Freeze Hazelcast writes, replay the final delta, switch clients to LoomCache seeds, and retain rollback data.

The root HAZELCAST_MIGRATION.md includes the longer operator-oriented version.