Jafly. Cache - Hazelcast

Cache - Hazelcast¶

Adapt a host-managed Hazelcast map to the common cache contract.

Provide a HazelcastInstance bean and select HAZELCAST in the core cache settings. The provider is discovered with ServiceLoader; this module does not configure your cluster topology or add its own Spring auto-configuration.

Maven artifact	Packaging	Source project
`org.fireflyframework:fireflyframework-cache-hazelcast`	`jar`	modules/cache-hazelcast

Part of Domain and data.

In the onboarding service¶

If the onboarding deployment already supplies a Hazelcast instance, this provider can back the shared cache API. The host supplies the cluster member and its networking/security configuration.

Add the component¶

Installation and version availability explains source builds and published releases.

<dependency>
    <groupId>org.fireflyframework</groupId>
    <artifactId>fireflyframework-cache-hazelcast</artifactId>
    <version>26.10.20-SNAPSHOT</version>
</dependency>

Quick start¶

The Java examples in this section are API fragments for application code. Use the stated imports and supply the application-owned collaborators described alongside them.

Provide a HazelcastInstance bean (embedded member shown; use a client config to join an external cluster):

import com.hazelcast.core.Hazelcast;
import com.hazelcast.core.HazelcastInstance;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class HazelcastConfig {

    @Bean
    public HazelcastInstance hazelcastInstance() {
        return Hazelcast.newHazelcastInstance();
    }
}

Select Hazelcast as the cache provider:

firefly:
  cache:
    default-cache-type: HAZELCAST

With both the HazelcastInstance bean on the context and the property set, the core CacheManagerFactory discovers HazelcastProvider through the SPI and routes all cache operations to Hazelcast. Your application code keeps using the standard Firefly cache API. Nothing else changes.

Configuration and wiring¶

This module declares no @ConfigurationProperties class of its own. Use the constructor/port contracts above and the configuration of the host or related core module.

Public API and extension points¶

Type	Contract and responsibility
`HazelcastProvider`	Defines `create` operations.
`HazelcastCacheHelper`	Reflection-based helper to create a Hazelcast-backed CacheAdapter without a compile-time dependency.

Related component	Why it belongs nearby
Common Cache Library	Use a common cache API with a local Caffeine default and pluggable distributed providers.

Build and test¶

Use Java 25. From the repository root, build this component with its required dependencies:

git clone https://github.com/fireflyframework/fireflyframework-jafly.git
cd fireflyframework-jafly
./mvnw -pl :fireflyframework-cache-hazelcast -am verify
./mvnw -pl :fireflyframework-cache-hazelcast -am install

verify runs the selected projects' tests. install makes the current build available in your local Maven repository.

Representative test sources:

HazelcastProviderWiringTest.java.

Test fixture¶

The hazelcastProviderIsDiscoveredViaServiceLoader test demonstrates one concrete behavior. Excerpt from HazelcastProviderWiringTest.java. The test class supplies its fixtures and imports.

@Test
void hazelcastProviderIsDiscoveredViaServiceLoader() {
    ServiceLoader<CacheProviderFactory> loader = ServiceLoader.load(CacheProviderFactory.class);

    var factories = StreamSupport.stream(loader.spliterator(), false)
            .collect(Collectors.toList());

    assertThat(factories)
            .as("ServiceLoader should discover at least one CacheProviderFactory")
            .isNotEmpty();

    assertThat(factories)
            .as("a Hazelcast provider with getType()==HAZELCAST must be present")
            .anySatisfy(factory ->
                    assertThat(factory.getType()).isEqualTo(CacheType.HAZELCAST));

    CacheProviderFactory hazelcast = factories.stream()
            .filter(f -> f.getType() == CacheType.HAZELCAST)
            .findFirst()
            .orElseThrow();

    assertThat(hazelcast).isInstanceOf(HazelcastProvider.class);
}

Detailed reference¶

How It Works¶

Application code
      │  (Firefly cache API, provider-agnostic)
      ▼
fireflyframework-cache  ──►  CacheManagerFactory
                                   │ ServiceLoader lookup of CacheProviderFactory
                                   ▼
                          HazelcastProvider  (CacheType.HAZELCAST, priority 20)
                                   │ wraps the host HazelcastInstance bean
                                   ▼
                  HazelcastCacheHelper / HazelcastCacheAdapterReflective
                                   │ reflective access (no compile-time dep in core)
                                   ▼
                          Hazelcast IMap  (TTL-aware, key = <prefix>:<cacheName>:<key>)

Configuration¶

This adapter has no @ConfigurationProperties of its own. It is selected and tuned entirely through the core module's firefly.cache.* properties; the only requirement specific to this adapter is a HazelcastInstance bean on the application context. The minimum configuration to activate it:

firefly:
  cache:
    default-cache-type: HAZELCAST   # selects this provider (default is CAFFEINE)

Property	Owner	Purpose
`firefly.cache.default-cache-type`	core	Set to `HAZELCAST` to activate this adapter.
`firefly.cache.*` (TTL, key prefix, etc.)	core	Shared cache settings; the adapter honors `keyPrefix` to namespace keys as `<prefix>:<cacheName>:<key>`.

Hazelcast cluster topology, discovery, networking, and security are configured on the HazelcastInstance bean by the host application, not through Firefly properties.

Continue the application¶

Use the Cache guide for the next part of this integration. The runnable submission/query service is in Getting started.