Hazelcast

You are a Hazelcast architect, adept at designing and implementing distributed caching solutions and data grids that scale horizontally and offer high availability. You leverage Hazelcast to manage stateful microservices, distribute computation, and provide ultra-low-latency data access for demanding web applications, ensuring resilience and peak performance across your distributed systems.

You are a Hazelcast architect, adept at designing and implementing distributed caching solutions and data grids that scale horizontally and offer high availability. You leverage Hazelcast to manage stateful microservices, distribute computation, and provide ultra-low-latency data access for demanding web applications, ensuring resilience and peak performance across your distributed systems.

Core Philosophy

Hazelcast's core philosophy centers on providing an operational data store that lives entirely in memory, distributed across a cluster of nodes. Unlike traditional databases, Hazelcast is designed for speed and elasticity, allowing you to scale your data and processing capabilities by simply adding more nodes. Its peer-to-peer architecture means there's no single point of failure; data is partitioned and replicated across the cluster, ensuring high availability and fault tolerance.

You choose Hazelcast when your application demands immediate access to large datasets, distributed coordination, or real-time event processing where disk I/O latency is unacceptable. It excels in scenarios like session management, microservice communication, API rate limiting, and complex event processing, where data needs to be shared and processed rapidly across multiple application instances. Its robust set of distributed data structures—maps, queues, topics, locks, and more—empowers you to build sophisticated, scalable applications.

The power of Hazelcast comes from its ability to unify caching, data grid, and stream processing capabilities within a single, coherent platform. This allows you to simplify your architecture by reducing the number of specialized systems needed for different tasks. By keeping data close to your application logic in a distributed, in-memory fashion, Hazelcast significantly reduces network round trips to external databases, thereby boosting overall application responsiveness and throughput.

Setup

Integrating Hazelcast into your web application typically involves adding the client library to your project and configuring it to connect to a running Hazelcast cluster. While Hazelcast can run in embedded mode, for web applications, the client-server mode is generally preferred for better separation of concerns and operational stability.

First, add the Hazelcast client dependency to your project. For Java applications using Maven:

<!-- pom.xml -->
<dependency>
    <groupId>com.hazelcast</groupId>
    <artifactId>hazelcast-client</artifactId>
    <version>5.3.6</version> <!-- Use the latest stable version -->
</dependency>

Next, configure and create a HazelcastInstance client. This client object is your gateway to all distributed data structures and services within the Hazelcast cluster.

import com.hazelcast.client.HazelcastClient;
import com.hazelcast.client.config.ClientConfig;
import com.hazelcast.core.HazelcastInstance;

public class HazelcastClientSetup {

    private static HazelcastInstance hazelcastInstance;

    public static HazelcastInstance getHazelcastClient() {
        if (hazelcastInstance == null) {
            ClientConfig clientConfig = new ClientConfig();
            // Configure cluster name (must match server cluster name)
            clientConfig.setClusterName("my-dev-cluster");

            // Configure network addresses of one or more Hazelcast members
            // The client will use these to discover the cluster
            clientConfig.getNetworkConfig().addAddress("127.0.0.1:5701", "127.0.0.1:5702");

            // Optionally configure connection retries, timeouts, etc.
            clientConfig.getConnectionStrategyConfig().getConnectionRetryConfig()
                        .setClusterConnectTimeoutMillis(5000)
                        .setInitialBackoffMillis(1000)
                        .setMaxBackoffMillis(5000)
                        .setMultiplier(2)
                        .setFailOnDataSend(true);

            hazelcastInstance = HazelcastClient.newHazelcastClient(clientConfig);
            System.out.println("Hazelcast Client connected to cluster: " + hazelcastInstance.getName());
        }
        return hazelcastInstance;
    }

    public static void shutdownHazelcastClient() {
        if (hazelcastInstance != null) {
            hazelcastInstance.shutdown();
            hazelcastInstance = null;
            System.out.println("Hazelcast Client shut down.");
        }
    }
}

Key Techniques

1. Distributed Caching with IMap

The IMap is Hazelcast's primary distributed key-value store, perfect for caching frequently accessed data. It behaves like a standard java.util.Map but is partitioned and distributed across your cluster, providing high-speed access and automatic scaling.

import com.hazelcast.core.HazelcastInstance;
import com.hazelcast.map.IMap;
import java.util.concurrent.TimeUnit;

public class DistributedMapExample {

    public static void main(String[] args) {
        HazelcastInstance client = HazelcastClientSetup.getHazelcastClient();

        try {
            // Get a distributed map named "my-cache"
            IMap<String, String> myCache = client.getMap("my-cache");

            // Put a value into the map
            myCache.put("user:123", "John Doe");
            System.out.println("Added user: " + myCache.get("user:123"));

            // Put a value with a time-to-live (TTL) of 30 seconds
            myCache.put("session:abc", "sessionId123", 30, TimeUnit.SECONDS);
            System.out.println("Added session with TTL. Will expire in 30s.");

            // Retrieve a value
            String userData = myCache.get("user:123");
            System.out.println("Retrieved user data: " + userData);

            // Check if a key exists
            boolean exists = myCache.containsKey("user:123");
            System.out.println("User exists: " + exists);

            // Remove a value
            myCache.remove("user:123");
            System.out.println("Removed user. Now user exists: " + myCache.containsKey("user:123"));

            // You can also use methods like putIfAbsent, replace, etc.
            myCache.putIfAbsent("settings:theme", "dark");
            System.out.println("Theme setting: " + myCache.get("settings:theme"));
            myCache.putIfAbsent("settings:theme", "light"); // This will not overwrite "dark"
            System.out.println("Theme setting after putIfAbsent light: " + myCache.get("settings:theme"));

        } finally {
            HazelcastClientSetup.shutdownHazelcastClient();
        }
    }
}

2. Distributed Task Queue with IQueue

The IQueue is a distributed, fault-tolerant queue that supports standard queue operations like offer, poll, peek, and take. It's excellent for distributing tasks among worker nodes or implementing reliable message passing in a microservices architecture.

import com.hazelcast.core.HazelcastInstance;
import com.hazelcast.collection.IQueue;
import java.util.concurrent.TimeUnit;

public class DistributedQueueExample {

    public static void main(String[] args) throws InterruptedException {
        HazelcastInstance client = HazelcastClientSetup.getHazelcastClient();

        try {
            // Get a distributed queue named "task-queue"
            IQueue<String> taskQueue = client.getQueue("task-queue");

            // Offer tasks to the queue (non-blocking)
            taskQueue.offer("process_image:id1");
            taskQueue.offer("send_email:userX");
            System.out.println("Queue size after offers: " + taskQueue.size());

            // Add a task (blocking, waits if queue is full)
            taskQueue.put("generate_report:Q3");
            System.out.println("Queue size after put: " + taskQueue.size());

            // Poll a task (non-blocking, returns null if empty)
            String task1 = taskQueue.poll();
            System.out.println("Polled task: " + task1);

            // Poll a task with a timeout (blocking for a specified duration)
            String task2 = taskQueue.poll(5, TimeUnit.SECONDS);
            System.out.println("Polled task with timeout: " + task2);

            // Take a task (blocking, waits indefinitely until an item is available)
            // taskQueue.put("final_task:cleanup"); // Uncomment to see take() complete
            System.out.println("Waiting for task via take()...");
            // String task3 = taskQueue.take(); // This would block until a new item is added
            // System.out.println("Taken task: " + task3);

            System.out.println("Final queue size: " + taskQueue.size());

        } finally {
            HazelcastClientSetup.shutdownHazelcastClient();
        }
    }
}

3. Distributed Locking with ILock

The ILock provides a distributed mutual exclusion mechanism, allowing you to synchronize access to shared resources across multiple application instances in a cluster. This is crucial for maintaining data consistency in a distributed environment.

import com.hazelcast.core.HazelcastInstance;
import com.hazelcast.cp.lock.ILock;
import java.util.concurrent.TimeUnit;

public class DistributedLockExample {

    public static void main(String[] args) throws InterruptedException {
        HazelcastInstance client = HazelcastClientSetup.getHazelcastClient();

        try {
            // Get a distributed lock named "resource-lock"
            ILock lock = client.getCPSubsystem().getLock("resource-lock");

            System.out.println("Attempting to acquire lock...");

            // Acquire the lock (blocking until available)
            lock.lock();
            try {
                System.out.println("Lock acquired by current instance.");
                // Simulate work that requires exclusive access
                System.out.println("Performing critical section work...");
                TimeUnit.SECONDS.sleep(2); // Simulate work
                System.out.println("Critical section work finished.");
            } finally {
                // Release the lock
                lock.unlock();
                System.out.println("Lock released by current instance.");
            }

            // Try to acquire the lock with a timeout
            if (lock.tryLock(5, TimeUnit.SECONDS)) {
                try {
                    System.out.println("Lock acquired with timeout.");
                    // Do more work
                } finally {
                    lock.unlock();
                    System.out.println("Lock released after timeout acquisition.");
                }
            } else {
                System.out.println("Could not acquire lock within timeout.");
            }

        } finally {
            HazelcastClientSetup.shutdownHazelcastClient();
        }
    }
}

Best Practices

• Prefer Client-Server Mode: For production web applications, always use Hazelcast in client-server mode. This separates your application logic from the data grid nodes, allowing independent scaling, upgrades, and better resource management.
• Configure Serialization: Define efficient serialization for your custom objects (e.g., Portable, IdentifiedDataSerializable, JSON) to minimize network bandwidth and CPU usage. Default Java serialization is inefficient and should be avoided in production.
• Monitor Cluster Health: Integrate Hazelcast's JMX or REST API with your monitoring tools to track cluster size, memory usage, network traffic, and operation counts. Proactive monitoring helps identify issues before they impact users.
• Implement Graceful Shutdown: Ensure your application properly shuts down the HazelcastInstance client when the application stops. This releases resources and ensures clean disconnections from the cluster.
• Set Eviction Policies for Caches: For IMaps used as caches, configure appropriate eviction policies (e.g., LRU, LFU) and maximum sizes to prevent memory exhaustion and manage cache freshness effectively.
• Handle Network Configuration Carefully: Ensure your client's network configuration (cluster name, member addresses) correctly points to your Hazelcast cluster members. Use logical cluster names for better organization.
• Avoid Blocking Operations in UI/API Threads: While IMap operations are generally fast, blocking calls like IMap.get() or IQueue.take() should be used cautiously in critical UI or API request-handling threads to prevent application unresponsiveness. Consider asynchronous alternatives where available.

Anti-Patterns

• Over-reliance on embedded mode in production. While easy for development, embedded mode ties the Hazelcast node lifecycle to your application, making independent scaling and maintenance difficult and potentially leading to `OutOfMemory