How to Build an EhCache Cluster for Spring Boot: A Step‑by‑Step Guide

Hands‑On Example

Based on the previous article that introduced EhCache integration in Spring Boot, this guide shows how to build a process‑level cache cluster and configure its synchronization strategy.

First step : Make the cached objects implement the Serializable interface to avoid serialization errors during cluster communication.

@Entity
@Data
@NoArgsConstructor
public class User implements Serializable {
    @Id
    @GeneratedValue
    private Long id;
    private String name;
    private Integer age;
    public User(String name, Integer age) {
        this.name = name;
        this.age = age;
    }
}

Second step : Create separate EhCache XML configuration files for each instance, adding a cacheEventListenerFactory to define replication parameters and a cacheManagerPeerProviderFactory to specify cluster node information.

<ehcache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="ehcache.xsd">
    <cache name="users"
           maxEntriesLocalHeap="200"
           timeToLiveSeconds="600">
        <cacheEventListenerFactory class="net.sf.ehcache.distribution.RMICacheReplicatorFactory"
            properties="replicateAsynchronously=true,
                        replicatePuts=true,
                        replicateUpdates=true,
                        replicateUpdatesViaCopy=false,
                        replicateRemovals=true"/>
    </cache>
    <cacheManagerPeerProviderFactory class="net.sf.ehcache.distribution.RMICacheManagerPeerProviderFactory"
        properties="hostName=10.10.0.100,
                    port=40001,
                    socketTimeoutMillis=2000,
                    peerDiscovery=manual,
                    rmiUrls=//10.10.0.101:40001/users"/>
</ehcache>

The second instance uses a similar file (ehcache‑2.xml) with its own hostName and rmiUrls pointing to the first node.

Third step : Package and start the application with JVM arguments that select the appropriate configuration file for each instance.

-Dspring.cache.ehcache.config=classpath:ehcache-1.xml
-Dspring.cache.ehcache.config=classpath:ehcache-2.xml

Fourth step : Implement REST endpoints to verify cache synchronization.

@RestController
static class HelloController {
    @Autowired
    private UserRepository userRepository;

    @GetMapping("/create")
    public void create() {
        userRepository.save(new User("AAA", 10));
    }

    @GetMapping("/find")
    public User find() {
        User u1 = userRepository.findByName("AAA");
        System.out.println("Query AAA user: " + u1.getAge());
        return u1;
    }
}

Verification steps:

Start two instances with the parameters from the third step.

Call /create on instance 1 to insert a record.

Call /find on instance 1; the user is cached and the cache is replicated to instance 2.

Call /find on instance 2; the query hits the replicated cache, avoiding a database query.

Further Considerations

When data is updated, use @CachePut on the save method and ensure replicateUpdates=true so the updated entry is replicated to other nodes. Although this reduces stale data, replication still incurs a short delay and each JVM holds its own in‑process cache, which may not be economical for large datasets. Therefore, in‑process caches are often not the primary caching solution; the next article will discuss a more important caching approach.

References

EhCache Distributed Cache / Cache Cluster – https://www.cnblogs.com/hoojo/archive/2012/07/19/2599534.html

Java RMI: rmi Connection refused to host: 127.0.0.1 – https://blog.csdn.net/chenchaofuck1/article/details/51558995