0
# Distributed Data Structures
1

2
Hazelcast provides a comprehensive set of distributed data structures that are partitioned and replicated across the cluster. These structures provide thread-safe, concurrent access with high availability and fault tolerance.
3

4
## Distributed Maps
5

6
### IMap Interface
7

8
The `IMap` is Hazelcast's distributed implementation of `java.util.concurrent.ConcurrentMap` with additional distributed capabilities.
9

10
```java { .api }
11
import com.hazelcast.map.IMap;
12
import com.hazelcast.map.MapStore;
13
import com.hazelcast.map.MapLoader;
14
import com.hazelcast.map.EntryProcessor;
15
import com.hazelcast.map.listener.MapListener;
16
import com.hazelcast.query.Predicate;
17
import com.hazelcast.config.IndexConfig;
18
import com.hazelcast.config.IndexType;
19
import com.hazelcast.core.DistributedObject;
20
import java.util.concurrent.TimeUnit;
21
import java.util.concurrent.CompletionStage;
22
import java.util.UUID;
23
import java.util.Set;
24
import java.util.Collection;
25
import java.util.Map;
26

27
public interface IMap<K, V> extends ConcurrentMap<K, V>, DistributedObject {
28
    // Basic operations
29
    V put(K key, V value);
30
    V put(K key, V value, long ttl, TimeUnit timeunit);
31
    V put(K key, V value, long ttl, TimeUnit ttlUnit, long maxIdle, TimeUnit maxIdleUnit);
32
    
33
    V putIfAbsent(K key, V value);
34
    V putIfAbsent(K key, V value, long ttl, TimeUnit timeunit);
35
    
36
    boolean replace(K key, V oldValue, V newValue);
37
    V replace(K key, V value);
38
    
39
    V get(Object key);
40
    V remove(Object key);
41
    boolean remove(Object key, Object value);
42
    
43
    void delete(Object key);
44
    void set(K key, V value);
45
    void set(K key, V value, long ttl, TimeUnit timeunit);
46
    
47
    // Batch operations
48
    void putAll(Map<? extends K, ? extends V> map);
49
    Map<K, V> getAll(Set<K> keys);
50
    void setAll(Map<? extends K, ? extends V> map);
51
    
52
    // Async operations  
53
    CompletionStage<V> putAsync(K key, V value);
54
    CompletionStage<V> putAsync(K key, V value, long ttl, TimeUnit timeunit);
55
    CompletionStage<V> getAsync(K key);
56
    CompletionStage<V> removeAsync(K key);
57
    
58
    // Querying
59
    Set<K> keySet();
60
    Set<K> keySet(Predicate<K, V> predicate);
61
    Collection<V> values();
62
    Collection<V> values(Predicate<K, V> predicate);
63
    Set<Entry<K, V>> entrySet();
64
    Set<Entry<K, V>> entrySet(Predicate<K, V> predicate);
65
    
66
    // Entry processing
67
    <R> R executeOnKey(K key, EntryProcessor<K, V, R> entryProcessor);
68
    <R> Map<K, R> executeOnKeys(Set<K> keys, EntryProcessor<K, V, R> entryProcessor);
69
    <R> Map<K, R> executeOnEntries(EntryProcessor<K, V, R> entryProcessor);
70
    <R> Map<K, R> executeOnEntries(EntryProcessor<K, V, R> entryProcessor, Predicate<K, V> predicate);
71
    
72
    // Indexing
73
    void addIndex(IndexType type, String... attributes);
74
    void addIndex(IndexConfig indexConfig);
75
    
76
    // Listeners
77
    UUID addEntryListener(MapListener listener, boolean includeValue);
78
    UUID addEntryListener(MapListener listener, K key, boolean includeValue);
79
    UUID addEntryListener(MapListener listener, Predicate<K, V> predicate, boolean includeValue);
80
    boolean removeEntryListener(UUID registrationId);
81
    
82
    // Locking
83
    void lock(K key);
84
    void lock(K key, long leaseTime, TimeUnit timeUnit);
85
    boolean isLocked(K key);
86
    boolean tryLock(K key);
87
    boolean tryLock(K key, long time, TimeUnit timeunit);
88
    void unlock(K key);
89
    void forceUnlock(K key);
90
    
91
    // Storage operations
92
    void flush();
93
    void evict(K key);
94
    void evictAll();
95
    void clear();
96
    
97
    // Statistics and info
98
    LocalMapStats getLocalMapStats();
99
    int size();
100
    boolean isEmpty();
101
    boolean containsKey(Object key);
102
    boolean containsValue(Object value);
103
}
104
```
105

106
### Map Usage Examples
107

108
#### Basic Operations
109

110
```java { .api }
111
IMap<String, User> userMap = hz.getMap("users");
112

113
// Put operations
114
User user = new User("john", "john@example.com");
115
userMap.put("john", user);
116

117
// Put with TTL (expires after 30 minutes)
118
userMap.put("temp-user", user, 30, TimeUnit.MINUTES);
119

120
// Put with TTL and max idle time
121
userMap.put("session-user", user, 1, TimeUnit.HOURS, 30, TimeUnit.MINUTES);
122

123
// Conditional operations
124
User existing = userMap.putIfAbsent("john", user);
125
boolean replaced = userMap.replace("john", oldUser, newUser);
126

127
// Retrieval
128
User retrieved = userMap.get("john");
129
boolean exists = userMap.containsKey("john");
130
```
131

132
#### Querying and Indexing
133

134
```java { .api }
135
import com.hazelcast.query.Predicates;
136
import com.hazelcast.config.IndexType;
137

138
// Add index for better query performance
139
userMap.addIndex(IndexType.SORTED, "age");
140
userMap.addIndex(IndexType.HASH, "department");
141

142
// Query examples
143
Collection<User> youngUsers = userMap.values(Predicates.lessThan("age", 30));
144
Set<String> keys = userMap.keySet(Predicates.like("name", "John%"));
145

146
// Complex predicates
147
Predicate<String, User> complexPredicate = Predicates.and(
148
    Predicates.greaterEqual("age", 25),
149
    Predicates.equal("department", "Engineering")
150
);
151
Collection<User> engineers = userMap.values(complexPredicate);
152

153
// SQL predicates
154
Collection<User> sqlResult = userMap.values(Predicates.sql("age > 25 AND department = 'Engineering'"));
155
```
156

157
#### Entry Processing
158

159
```java { .api }
160
import com.hazelcast.map.EntryProcessor;
161

162
// Custom entry processor
163
public class IncrementCounterProcessor implements EntryProcessor<String, Integer, Integer> {
164
    private int incrementBy;
165
    
166
    public IncrementCounterProcessor(int incrementBy) {
167
        this.incrementBy = incrementBy;
168
    }
169
    
170
    @Override
171
    public Integer process(Map.Entry<String, Integer> entry) {
172
        Integer currentValue = entry.getValue();
173
        if (currentValue == null) {
174
            currentValue = 0;
175
        }
176
        Integer newValue = currentValue + incrementBy;
177
        entry.setValue(newValue);
178
        return newValue;
179
    }
180
}
181

182
// Usage
183
IMap<String, Integer> counters = hz.getMap("counters");
184
Integer result = counters.executeOnKey("page-views", new IncrementCounterProcessor(1));
185

186
// Execute on multiple keys
187
Set<String> keys = Set.of("counter1", "counter2", "counter3");
188
Map<String, Integer> results = counters.executeOnKeys(keys, new IncrementCounterProcessor(5));
189
```
190

191
### MultiMap Interface
192

193
A distributed data structure where each key can be associated with multiple values.
194

195
```java { .api }
196
import com.hazelcast.multimap.MultiMap;
197
import java.util.Collection;
198

199
public interface MultiMap<K, V> extends DistributedObject {
200
    // Basic operations
201
    boolean put(K key, V value);
202
    Collection<V> get(K key);
203
    boolean remove(Object key, Object value);
204
    Collection<V> remove(Object key);
205
    
206
    // Query operations
207
    Set<K> keySet();
208
    Collection<V> values();
209
    Set<Entry<K, V>> entrySet();
210
    
211
    // Bulk operations
212
    boolean containsKey(K key);
213
    boolean containsValue(Object value);
214
    boolean containsEntry(K key, V value);
215
    
216
    int size();
217
    void clear();
218
    
219
    // Listeners
220
    UUID addEntryListener(EntryListener<K, V> listener, boolean includeValue);
221
    UUID addEntryListener(EntryListener<K, V> listener, K key, boolean includeValue);
222
    boolean removeEntryListener(UUID registrationId);
223
    
224
    // Locking
225
    void lock(K key);
226
    void unlock(K key);
227
    boolean tryLock(K key);
228
    boolean isLocked(K key);
229
    
230
    // Statistics
231
    LocalMultiMapStats getLocalMultiMapStats();
232
}
233
```
234

235
#### MultiMap Usage
236

237
```java { .api }
238
MultiMap<String, String> categoryMap = hz.getMultiMap("categories");
239

240
// Add multiple values for same key
241
categoryMap.put("fruits", "apple");
242
categoryMap.put("fruits", "banana");
243
categoryMap.put("fruits", "orange");
244

245
categoryMap.put("vegetables", "carrot");
246
categoryMap.put("vegetables", "lettuce");
247

248
// Get all values for a key
249
Collection<String> fruits = categoryMap.get("fruits"); // [apple, banana, orange]
250

251
// Remove specific value
252
categoryMap.remove("fruits", "banana");
253

254
// Remove all values for key
255
Collection<String> removed = categoryMap.remove("vegetables");
256
```
257

258
### ReplicatedMap Interface
259

260
Eventually consistent replicated map that stores data on every cluster member.
261

262
```java { .api }
263
import com.hazelcast.replicatedmap.ReplicatedMap;
264

265
public interface ReplicatedMap<K, V> extends Map<K, V>, DistributedObject {
266
    // Standard Map operations
267
    V put(K key, V value);
268
    V put(K key, V value, long ttl, TimeUnit timeunit);
269
    V get(Object key);
270
    V remove(Object key);
271
    
272
    // Async operations
273
    ICompletableFuture<V> putAsync(K key, V value);
274
    ICompletableFuture<V> putAsync(K key, V value, long ttl, TimeUnit timeunit);
275
    ICompletableFuture<V> getAsync(K key);
276
    ICompletableFuture<V> removeAsync(K key);
277
    
278
    // Listeners
279
    UUID addEntryListener(EntryListener<K, V> listener);
280
    UUID addEntryListener(EntryListener<K, V> listener, K key);
281
    UUID addEntryListener(EntryListener<K, V> listener, Predicate<K, V> predicate);
282
    boolean removeEntryListener(UUID registrationId);
283
    
284
    // Query operations
285
    Collection<V> values(Predicate<K, V> predicate);
286
    Set<Entry<K, V>> entrySet(Predicate<K, V> predicate);
287
    Set<K> keySet(Predicate<K, V> predicate);
288
    
289
    void clear();
290
}
291
```
292

293
## Distributed Collections
294

295
### IQueue Interface
296

297
Distributed implementation of `java.util.concurrent.BlockingQueue`.
298

299
```java { .api }
300
import com.hazelcast.collection.IQueue;
301
import com.hazelcast.collection.ItemListener;
302
import java.util.concurrent.BlockingQueue;
303
import java.util.concurrent.TimeUnit;
304

305
public interface IQueue<E> extends BlockingQueue<E>, DistributedObject {
306
    // Blocking operations
307
    boolean offer(E item);
308
    boolean offer(E item, long timeout, TimeUnit unit) throws InterruptedException;
309
    E poll();
310
    E poll(long timeout, TimeUnit unit) throws InterruptedException;
311
    E take() throws InterruptedException;
312
    E peek();
313
    
314
    // Capacity and size
315
    int remainingCapacity();
316
    boolean contains(Object o);
317
    int drainTo(Collection<? super E> c);
318
    int drainTo(Collection<? super E> c, int maxElements);
319
    
320
    // Collection operations
321
    boolean add(E e);
322
    boolean remove(Object o);
323
    void clear();
324
    int size();
325
    boolean isEmpty();
326
    Object[] toArray();
327
    <T> T[] toArray(T[] a);
328
    
329
    // Iterator support
330
    Iterator<E> iterator();
331
    
332
    // Listeners
333
    UUID addItemListener(ItemListener<E> listener, boolean includeValue);
334
    boolean removeItemListener(UUID registrationId);
335
    
336
    // Statistics
337
    LocalQueueStats getLocalQueueStats();
338
}
339
```
340

341
#### Queue Usage Examples
342

343
```java { .api }
344
IQueue<Task> taskQueue = hz.getQueue("task-queue");
345

346
// Producer
347
Task task = new Task("process-order", orderId);
348
taskQueue.offer(task); // Non-blocking
349
taskQueue.put(task);   // Blocking if full
350

351
// Consumer
352
Task nextTask = taskQueue.poll();          // Non-blocking, returns null if empty
353
Task taskWithTimeout = taskQueue.poll(5, TimeUnit.SECONDS); // Wait up to 5 seconds
354
Task blockingTask = taskQueue.take();      // Block until available
355

356
// Item listener
357
taskQueue.addItemListener(new ItemListener<Task>() {
358
    @Override
359
    public void itemAdded(ItemEvent<Task> item) {
360
        System.out.println("Task added: " + item.getItem());
361
    }
362
    
363
    @Override
364
    public void itemRemoved(ItemEvent<Task> item) {
365
        System.out.println("Task removed: " + item.getItem());
366
    }
367
}, true);
368
```
369

370
### IList Interface
371

372
Distributed implementation of `java.util.List`.
373

374
```java { .api }
375
import com.hazelcast.collection.IList;
376
import java.util.List;
377

378
public interface IList<E> extends List<E>, DistributedObject {
379
    // Standard List operations
380
    boolean add(E e);
381
    void add(int index, E element);
382
    boolean addAll(Collection<? extends E> c);
383
    boolean addAll(int index, Collection<? extends E> c);
384
    
385
    E get(int index);
386
    E set(int index, E element);
387
    E remove(int index);
388
    boolean remove(Object o);
389
    
390
    int indexOf(Object o);
391
    int lastIndexOf(Object o);
392
    boolean contains(Object o);
393
    boolean containsAll(Collection<?> c);
394
    
395
    List<E> subList(int fromIndex, int toIndex);
396
    ListIterator<E> listIterator();
397
    ListIterator<E> listIterator(int index);
398
    
399
    // Collection operations
400
    void clear();
401
    int size();
402
    boolean isEmpty();
403
    Object[] toArray();
404
    <T> T[] toArray(T[] a);
405
    
406
    // Listeners
407
    UUID addItemListener(ItemListener<E> listener, boolean includeValue);
408
    boolean removeItemListener(UUID registrationId);
409
    
410
    // Statistics
411
    LocalCollectionStats getLocalCollectionStats();
412
}
413
```
414

415
### ISet Interface
416

417
Distributed implementation of `java.util.Set`.
418

419
```java { .api }
420
import com.hazelcast.collection.ISet;
421
import java.util.Set;
422

423
public interface ISet<E> extends Set<E>, DistributedObject {
424
    // Standard Set operations
425
    boolean add(E e);
426
    boolean addAll(Collection<? extends E> c);
427
    boolean remove(Object o);
428
    boolean removeAll(Collection<?> c);
429
    boolean retainAll(Collection<?> c);
430
    
431
    boolean contains(Object o);
432
    boolean containsAll(Collection<?> c);
433
    
434
    // Collection operations
435
    void clear();
436
    int size();
437
    boolean isEmpty();
438
    Object[] toArray();
439
    <T> T[] toArray(T[] a);
440
    Iterator<E> iterator();
441
    
442
    // Listeners
443
    UUID addItemListener(ItemListener<E> listener, boolean includeValue);
444
    boolean removeItemListener(UUID registrationId);
445
    
446
    // Statistics
447
    LocalCollectionStats getLocalCollectionStats();
448
}
449
```
450

451
#### Collection Usage Examples
452

453
```java { .api }
454
// Distributed list
455
IList<String> distributedList = hz.getList("my-list");
456
distributedList.add("first");
457
distributedList.add(1, "second"); // Insert at index
458
String item = distributedList.get(0);
459

460
// Distributed set
461
ISet<String> distributedSet = hz.getSet("unique-items");
462
distributedSet.add("unique-value");
463
boolean added = distributedSet.add("unique-value"); // Returns false (already exists)
464
boolean contains = distributedSet.contains("unique-value");
465
```
466

467
## Specialized Data Structures
468

469
### Ringbuffer Interface
470

471
High-performance circular buffer for reliable messaging.
472

473
```java { .api }
474
import com.hazelcast.ringbuffer.Ringbuffer;
475
import com.hazelcast.ringbuffer.ReadResultSet;
476
import java.util.concurrent.CompletionStage;
477

478
public interface Ringbuffer<E> extends DistributedObject {
479
    // Write operations
480
    long add(E item);
481
    CompletionStage<Long> addAsync(E item, OverflowPolicy overflowPolicy);
482
    long addAll(Collection<? extends E> collection, OverflowPolicy overflowPolicy);
483
    CompletionStage<Long> addAllAsync(Collection<? extends E> collection, OverflowPolicy overflowPolicy);
484
    
485
    // Read operations  
486
    E readOne(long sequence) throws InterruptedException;
487
    CompletionStage<ReadResultSet<E>> readManyAsync(long startSequence, int minCount, int maxCount);
488
    
489
    // Information
490
    long headSequence();
491
    long tailSequence();
492
    long size();
493
    long capacity();
494
    long remainingCapacity();
495
}
496
```
497

498
### Topic Interfaces
499

500
Distributed publish-subscribe messaging.
501

502
```java { .api }
503
import com.hazelcast.topic.ITopic;
504
import com.hazelcast.topic.MessageListener;
505
import java.util.concurrent.CompletionStage;
506

507
public interface ITopic<E> extends DistributedObject {
508
    // Publishing
509
    void publish(E message);
510
    CompletionStage<Void> publishAsync(E message);
511
    
512
    // Subscription
513
    UUID addMessageListener(MessageListener<E> listener);
514
    boolean removeMessageListener(UUID registrationId);
515
    
516
    // Statistics
517
    LocalTopicStats getLocalTopicStats();
518
}
519

520
public interface MessageListener<E> {
521
    void onMessage(Message<E> message);
522
}
523

524
public interface Message<E> {
525
    E getMessageObject();
526
    Member getPublishingMember();
527
    long getPublishTime();
528
}
529
```
530

531
#### Ringbuffer and Topic Usage
532

533
```java { .api }
534
// Ringbuffer usage
535
Ringbuffer<String> ringbuffer = hz.getRingbuffer("events");
536

537
// Producer
538
long sequence = ringbuffer.add("event-data");
539

540
// Consumer  
541
String event = ringbuffer.readOne(sequence);
542

543
// Batch reading
544
ReadResultSet<String> resultSet = ringbuffer.readManyAsync(0, 1, 10).toCompletableFuture().get();
545
for (String item : resultSet) {
546
    System.out.println("Read: " + item);
547
}
548

549
// Topic usage
550
ITopic<String> topic = hz.getTopic("notifications");
551

552
// Publisher
553
topic.publish("Hello subscribers!");
554

555
// Subscriber
556
topic.addMessageListener(message -> {
557
    System.out.println("Received: " + message.getMessageObject());
558
    System.out.println("From: " + message.getPublishingMember());
559
});
560
```
561

562
### Atomic Data Structures
563

564
#### FlakeIdGenerator
565

566
Cluster-wide unique ID generator.
567

568
```java { .api }
569
import com.hazelcast.flakeidgen.FlakeIdGenerator;
570

571
public interface FlakeIdGenerator extends DistributedObject {
572
    long newId();
573
    boolean init(long id);
574
}
575

576
// Usage
577
FlakeIdGenerator idGenerator = hz.getFlakeIdGenerator("user-ids");
578
long uniqueId = idGenerator.newId();
579
```
580

581
#### CardinalityEstimator
582

583
HyperLogLog-based cardinality estimation.
584

585
```java { .api }
586
import com.hazelcast.cardinality.CardinalityEstimator;
587

588
public interface CardinalityEstimator extends DistributedObject {
589
    void add(Object obj);
590
    void addAll(Collection<?> objects);
591
    long estimate();
592
}
593

594
// Usage
595
CardinalityEstimator estimator = hz.getCardinalityEstimator("unique-visitors");
596
estimator.add("user123");
597
estimator.add("user456");
598
long uniqueCount = estimator.estimate();
599
```
600

601
#### PNCounter
602

603
Conflict-free replicated counter.
604

605
```java { .api }
606
import com.hazelcast.crdt.pncounter.PNCounter;
607

608
public interface PNCounter extends DistributedObject {
609
    long get();
610
    long getAndAdd(long delta);
611
    long addAndGet(long delta);
612
    long getAndSubtract(long delta);
613
    long subtractAndGet(long delta);
614
    long decrementAndGet();
615
    long incrementAndGet();
616
    long getAndDecrement();
617
    long getAndIncrement();
618
    void reset();
619
}
620

621
// Usage
622
PNCounter counter = hz.getPNCounter("global-counter");
623
long newValue = counter.incrementAndGet();
624
counter.addAndGet(10);
625
long currentValue = counter.get();
626
```
627

628
## Event Handling
629

630
### Entry Events for Maps
631

632
```java { .api }
633
import com.hazelcast.core.EntryEvent;
634
import com.hazelcast.core.EntryListener;
635
import com.hazelcast.map.MapEvent;
636

637
public interface EntryListener<K, V> extends MapListener {
638
    void entryAdded(EntryEvent<K, V> event);
639
    void entryEvicted(EntryEvent<K, V> event);
640
    void entryExpired(EntryEvent<K, V> event);
641
    void entryRemoved(EntryEvent<K, V> event);
642
    void entryUpdated(EntryEvent<K, V> event);
643
    void mapCleared(MapEvent event);
644
    void mapEvicted(MapEvent event);
645
}
646

647
// Usage example
648
IMap<String, User> userMap = hz.getMap("users");
649
userMap.addEntryListener(new EntryListener<String, User>() {
650
    @Override
651
    public void entryAdded(EntryEvent<String, User> event) {
652
        System.out.println("User added: " + event.getKey() + " = " + event.getValue());
653
    }
654
    
655
    @Override
656
    public void entryUpdated(EntryEvent<String, User> event) {
657
        System.out.println("User updated: " + event.getKey());
658
        System.out.println("Old value: " + event.getOldValue());
659
        System.out.println("New value: " + event.getValue());
660
    }
661
    
662
    // ... other methods
663
}, true); // includeValue = true
664
```
665

666
### Item Events for Collections
667

668
```java { .api }
669
import com.hazelcast.core.ItemEvent;
670
import com.hazelcast.core.ItemListener;
671

672
public interface ItemListener<E> {
673
    void itemAdded(ItemEvent<E> item);
674
    void itemRemoved(ItemEvent<E> item);
675
}
676

677
// Usage example
678
IQueue<Task> taskQueue = hz.getQueue("tasks");
679
taskQueue.addItemListener(new ItemListener<Task>() {
680
    @Override
681
    public void itemAdded(ItemEvent<Task> event) {
682
        System.out.println("Task queued: " + event.getItem());
683
    }
684
    
685
    @Override
686
    public void itemRemoved(ItemEvent<Task> event) {
687
        System.out.println("Task processed: " + event.getItem());
688
    }
689
}, true);
690
```
691

692
## Type Definitions
693

694
### Core Types
695

696
```java { .api }
697
import com.hazelcast.core.DistributedObject;
698

699
public interface DistributedObject {
700
    String getName();
701
    String getServiceName();
702
    void destroy();
703
    PartitionKey getPartitionKey();
704
}
705
```
706

707
### Index Configuration
708

709
```java { .api }
710
import com.hazelcast.config.IndexConfig;
711
import com.hazelcast.config.IndexType;
712

713
public class IndexConfig {
714
    public IndexConfig();
715
    public IndexConfig(IndexType type, String... attributes);
716
    
717
    public IndexConfig setName(String name);
718
    public String getName();
719
    
720
    public IndexConfig setType(IndexType type);
721
    public IndexType getType();
722
    
723
    public IndexConfig setAttributes(List<String> attributes);
724
    public List<String> getAttributes();
725
}
726

727
public enum IndexType {
728
    SORTED,
729
    HASH,
730
    BITMAP
731
}
732
```
733

734
### Map Listener Types
735

736
```java { .api }
737
import com.hazelcast.map.listener.MapListener;
738

739
public interface MapListener {
740
    // Marker interface for all map listeners
741
}
742
```