Configuration

In addition to the standard cache-hibernate dependency, the clustered setup requires the cache-clustered-kafka module:

<dependency>
    <groupId>org.eclipse.store</groupId>
    <artifactId>cache-hibernate</artifactId>
    <version>${eclipsestore-version}</version>
</dependency>
<dependency>
    <groupId>org.eclipse.store</groupId>
    <artifactId>cache-clustered-kafka</artifactId>
    <version>${eclipsestore-version}</version>
</dependency>

The key difference to the standard setup is the use of ClusteredCacheRegionFactory instead of CacheRegionFactory, along with the Kafka communication provider configuration.

Property Reference

The following table lists all configuration properties for the clustered Hibernate cache. The property names shown are the raw Hibernate properties. Depending on your framework, they need to be prefixed accordingly (see the framework-specific examples below).

Property Required Description

javax.persistence.sharedCache.mode

Yes

Enables the shared cache for all entities.

hibernate.cache.use_second_level_cache

Yes

Activates Hibernate’s second-level cache.

hibernate.cache.use_query_cache

Yes

Activates the query cache. Without this, there is no query cache to invalidate across nodes.

hibernate.cache.region.factory_class

Yes

Must be set to org.eclipse.datagrid.cache.clustered.types.ClusteredCacheRegionFactory. This class sets up all the clustering.

hibernate.cache.eclipsestore.missing_cache_strategy

Yes

Automatically creates cache regions for entities that don’t have an explicit cache configuration.

hibernate.cache.eclipsestore.clustered.com-provider

Yes

Must be set to org.eclipse.datagrid.cache.clustered.kafka.types.KafkaClusteredCacheMessageComProvider. Tells the clustered cache to use Kafka for message sending/receiving.

hibernate.cache.eclipsestore.clustered.kafka.config.bootstrap.servers

Yes

The Kafka bootstrap servers address. This is the only required Kafka property.

hibernate.cache.eclipsestore.clustered.kafka.topic

No

Custom Kafka topic name for cache replication messages. A default topic name is used if not provided.

hibernate.cache.eclipsestore.clustered.kafka.config.<kafka-property>

No

Any property prefixed with kafka.config is passed to both the Kafka producer and consumer. Use standard Kafka client configuration keys after the prefix.

hibernate.cache.eclipsestore.clustered.kafka.config.producer.<kafka-property>

No

Properties prefixed with kafka.config.producer are passed to the Kafka producer only. Example: kafka.config.producer.delivery.timeout.ms=500000

hibernate.cache.eclipsestore.clustered.kafka.config.consumer.<kafka-property>

No

Properties prefixed with kafka.config.consumer are passed to the Kafka consumer only. Example: kafka.config.consumer.max.poll.interval.ms=500000

JPA / Hibernate Properties

# Required: Enable second-level cache (identical to normal EclipseStore Cache settings)
javax.persistence.sharedCache.mode=ALL
hibernate.cache.use_second_level_cache=true
hibernate.cache.use_query_cache=true
hibernate.cache.eclipsestore.missing_cache_strategy=create

# Required: Use the clustered region factory instead of the standard one
hibernate.cache.region.factory_class=org.eclipse.datagrid.cache.clustered.types.ClusteredCacheRegionFactory

# Required: Configure Kafka as the communication provider for cache replication
hibernate.cache.eclipsestore.clustered.com-provider=org.eclipse.datagrid.cache.clustered.kafka.types.KafkaClusteredCacheMessageComProvider
hibernate.cache.eclipsestore.clustered.kafka.config.bootstrap.servers=<KAFKA_BOOTSTRAP_SERVERS>

# Optional: Custom Kafka topic name (a default is used if omitted)
hibernate.cache.eclipsestore.clustered.kafka.topic=my-cache-messages

# Optional: Kafka producer-specific configuration
hibernate.cache.eclipsestore.clustered.kafka.config.producer.delivery.timeout.ms=500000

# Optional: Kafka consumer-specific configuration
hibernate.cache.eclipsestore.clustered.kafka.config.consumer.max.poll.interval.ms=500000

Micronaut Example

When using Micronaut Data with Hibernate, configure the properties in application.properties. All Hibernate properties are prefixed with jpa.default.properties.:

# Required: These settings are identical to the normal EclipseStore Cache
jpa.default.properties.javax.persistence.sharedCache.mode=ALL
jpa.default.properties.hibernate.cache.use_second_level_cache=true
jpa.default.properties.hibernate.cache.use_query_cache=true
jpa.default.properties.hibernate.cache.eclipsestore.missing_cache_strategy=create

# Required: Clustered region factory and Kafka communication provider
jpa.default.properties.hibernate.cache.region.factory_class=org.eclipse.datagrid.cache.clustered.types.ClusteredCacheRegionFactory
jpa.default.properties.hibernate.cache.eclipsestore.clustered.com-provider=org.eclipse.datagrid.cache.clustered.kafka.types.KafkaClusteredCacheMessageComProvider
jpa.default.properties.hibernate.cache.eclipsestore.clustered.kafka.config.bootstrap.servers=${KAFKA_BOOTSTRAP_SERVERS}

# Optional: Custom Kafka topic and producer/consumer tuning
jpa.default.properties.hibernate.cache.eclipsestore.clustered.kafka.topic=my-cache-messages
jpa.default.properties.hibernate.cache.eclipsestore.clustered.kafka.config.producer.delivery.timeout.ms=500000
jpa.default.properties.hibernate.cache.eclipsestore.clustered.kafka.config.consumer.max.poll.interval.ms=500000

Spring Boot Example

When using Spring Boot, configure the properties in application.properties. All Hibernate properties are prefixed with spring.jpa.properties.:

# Required: These settings are identical to the normal EclipseStore Cache
spring.jpa.properties.javax.persistence.sharedCache.mode=ALL
spring.jpa.properties.hibernate.cache.use_second_level_cache=true
spring.jpa.properties.hibernate.cache.use_query_cache=true
spring.jpa.properties.hibernate.cache.eclipsestore.missing_cache_strategy=create

# Required: Clustered region factory and Kafka communication provider
spring.jpa.properties.hibernate.cache.region.factory_class=org.eclipse.datagrid.cache.clustered.types.ClusteredCacheRegionFactory
spring.jpa.properties.hibernate.cache.eclipsestore.clustered.com-provider=org.eclipse.datagrid.cache.clustered.kafka.types.KafkaClusteredCacheMessageComProvider
spring.jpa.properties.hibernate.cache.eclipsestore.clustered.kafka.config.bootstrap.servers=${KAFKA_BOOTSTRAP_SERVERS}

# Optional: Custom Kafka topic and producer/consumer tuning
spring.jpa.properties.hibernate.cache.eclipsestore.clustered.kafka.topic=my-cache-messages
spring.jpa.properties.hibernate.cache.eclipsestore.clustered.kafka.config.producer.delivery.timeout.ms=500000
spring.jpa.properties.hibernate.cache.eclipsestore.clustered.kafka.config.consumer.max.poll.interval.ms=500000

Or in application.yml:

spring:
  jpa:
    properties:
      javax:
        persistence:
          sharedCache:
            mode: ALL
      hibernate:
        cache:
          use_second_level_cache: true
          use_query_cache: true
          region:
            factory_class: org.eclipse.datagrid.cache.clustered.types.ClusteredCacheRegionFactory
          eclipsestore:
            missing_cache_strategy: create
            clustered:
              com-provider: org.eclipse.datagrid.cache.clustered.kafka.types.KafkaClusteredCacheMessageComProvider
              kafka:
                topic: my-cache-messages
                config:
                  bootstrap:
                    servers: ${KAFKA_BOOTSTRAP_SERVERS}
                  producer:
                    delivery:
                      timeout:
                        ms: 500000
                  consumer:
                    max:
                      poll:
                        interval:
                          ms: 500000