0
# Hazelcast Java Library
1

2
**Hazelcast** is a comprehensive real-time data platform that provides distributed computing capabilities including in-memory data grids, stream processing, and SQL queries. It enables stateful and fault-tolerant data processing with low-latency access to distributed data structures.
3

4
## Package Information
5

6
```xml
7
<dependency>
8
    <groupId>com.hazelcast</groupId>
9
    <artifactId>hazelcast</artifactId>
10
    <version>5.5.0</version>
11
</dependency>
12
```
13

14
**Java Compatibility:** Java 8+  
15
**License:** Apache-2.0  
16
**Documentation:** https://docs.hazelcast.com/
17

18
## Core Imports
19

20
```java { .api }
21
import com.hazelcast.core.Hazelcast;
22
import com.hazelcast.core.HazelcastInstance;
23
import com.hazelcast.map.IMap;
24
import com.hazelcast.collection.IQueue;
25
import com.hazelcast.client.HazelcastClient;
26
import com.hazelcast.config.Config;
27
import com.hazelcast.sql.SqlService;
28
import com.hazelcast.jet.JetService;
29
```
30

31
## Basic Usage
32

33
### Creating a Hazelcast Instance
34

35
```java { .api }
36
import com.hazelcast.core.Hazelcast;
37
import com.hazelcast.core.HazelcastInstance;
38
import com.hazelcast.config.Config;
39

40
// Create with default configuration
41
HazelcastInstance hz = Hazelcast.newHazelcastInstance();
42

43
// Create with custom configuration
44
Config config = new Config();
45
config.setInstanceName("my-instance");
46
HazelcastInstance hz = Hazelcast.newHazelcastInstance(config);
47

48
// Client connection
49
import com.hazelcast.client.HazelcastClient;
50
import com.hazelcast.client.config.ClientConfig;
51

52
ClientConfig clientConfig = new ClientConfig();
53
clientConfig.getNetworkConfig().addAddress("127.0.0.1:5701");
54
HazelcastInstance client = HazelcastClient.newHazelcastClient(clientConfig);
55

56
// Bootstrapped instance for Jet jobs (works locally and in distributed mode)
57
HazelcastInstance jetHz = Hazelcast.bootstrappedInstance();
58
```
59

60
### Working with Distributed Maps
61

62
```java { .api }
63
import com.hazelcast.map.IMap;
64
import java.util.concurrent.TimeUnit;
65

66
// Get distributed map
67
IMap<String, String> map = hz.getMap("my-map");
68

69
// Basic operations
70
map.put("key1", "value1");
71
map.put("key2", "value2", 30, TimeUnit.SECONDS); // with TTL
72
String value = map.get("key1");
73
boolean exists = map.containsKey("key1");
74

75
// Atomic operations
76
String oldValue = map.putIfAbsent("key3", "value3");
77
boolean replaced = map.replace("key1", "value1", "new-value1");
78

79
// Querying
80
import com.hazelcast.query.Predicates;
81
Collection<String> values = map.values(Predicates.like("name", "John%"));
82
```
83

84
### Working with Collections
85

86
```java { .api }
87
import com.hazelcast.collection.IQueue;
88
import com.hazelcast.collection.IList;
89
import com.hazelcast.collection.ISet;
90

91
// Distributed queue
92
IQueue<String> queue = hz.getQueue("my-queue");
93
queue.offer("item1");
94
String item = queue.poll();
95

96
// Distributed list
97
IList<String> list = hz.getList("my-list");
98
list.add("element1");
99
list.add("element2");
100

101
// Distributed set
102
ISet<String> set = hz.getSet("my-set");
103
set.add("unique-element");
104
```
105

106
## Architecture
107

108
Hazelcast provides a distributed architecture with several key components:
109

110
### Cluster Management
111
- **Members**: Server nodes that store data and execute operations
112
- **Clients**: Lightweight connections that access cluster data
113
- **Partitioning**: Automatic data distribution across cluster members
114
- **Discovery**: Multiple mechanisms for cluster formation (TCP/IP, multicast, cloud)
115

116
### Data Distribution
117
- **Partitioned Storage**: Data automatically distributed across cluster
118
- **Replication**: Configurable backup copies for fault tolerance  
119
- **Near Cache**: Local caching for frequently accessed data
120
- **Persistence**: Optional disk storage with MapStore integration
121

122
### Processing Models
123
- **Synchronous Operations**: Traditional request/response patterns
124
- **Asynchronous Operations**: Non-blocking operations with callbacks
125
- **Event-Driven**: Listeners for data and cluster changes
126
- **Stream Processing**: Real-time data processing with Jet engine
127

128
## Capabilities
129

130
### Core API and Instance Management
131
Basic instance creation, lifecycle management, and core distributed object access.
132

133
```java { .api }
134
import com.hazelcast.core.HazelcastInstance;
135
import com.hazelcast.core.LifecycleService;
136
import com.hazelcast.cluster.Cluster;
137

138
// Instance lifecycle
139
LifecycleService lifecycle = hz.getLifecycleService();
140
boolean isRunning = lifecycle.isRunning();
141

142
// Cluster access
143
Cluster cluster = hz.getCluster();
144
Set<Member> members = cluster.getMembers();
145

146
// Graceful shutdown
147
hz.shutdown();
148
```
149

150
[Core API and Instance Management](./core-api.md)
151

152
### Distributed Data Structures
153
Comprehensive collection of distributed data structures including maps, queues, lists, sets, and specialized structures.
154

155
```java { .api }
156
import com.hazelcast.map.IMap;
157
import com.hazelcast.multimap.MultiMap;
158
import com.hazelcast.replicatedmap.ReplicatedMap;
159
import com.hazelcast.ringbuffer.Ringbuffer;
160

161
// Various data structures
162
IMap<String, Object> distributedMap = hz.getMap("cache");
163
MultiMap<String, String> multiMap = hz.getMultiMap("categories");
164
ReplicatedMap<String, String> replicatedMap = hz.getReplicatedMap("config");
165
Ringbuffer<String> ringBuffer = hz.getRingbuffer("events");
166
```
167

168
[Distributed Data Structures](./data-structures.md)
169

170
### Stream Processing (Jet)
171
High-performance stream and batch processing engine built into Hazelcast.
172

173
```java { .api }
174
import com.hazelcast.jet.JetService;
175
import com.hazelcast.jet.pipeline.Pipeline;
176
import com.hazelcast.jet.pipeline.Sinks;
177
import com.hazelcast.jet.pipeline.Sources;
178

179
JetService jet = hz.getJet();
180

181
Pipeline pipeline = Pipeline.create();
182
pipeline.readFrom(Sources.map("source-map"))
183
        .filter(entry -> entry.getValue().toString().length() > 5)
184
        .writeTo(Sinks.map("result-map"));
185

186
Job job = jet.newJob(pipeline);
187
```
188

189
[Stream Processing](./stream-processing.md)
190

191
### SQL Queries
192
Distributed SQL engine for querying data across the cluster with standard SQL syntax.
193

194
```java { .api }
195
import com.hazelcast.sql.SqlService;
196
import com.hazelcast.sql.SqlResult;
197
import com.hazelcast.sql.SqlRow;
198

199
SqlService sql = hz.getSql();
200

201
// Execute query
202
SqlResult result = sql.execute("SELECT name, age FROM person WHERE age > ?", 25);
203

204
// Process results
205
for (SqlRow row : result) {
206
    String name = row.getObject("name");
207
    Integer age = row.getObject("age");
208
    System.out.println(name + ": " + age);
209
}
210
```
211

212
[SQL Queries](./sql-service.md)
213

214
### Cluster Management
215
Cluster membership, discovery, state management, and distributed coordination.
216

217
```java { .api }
218
import com.hazelcast.cluster.Cluster;
219
import com.hazelcast.cluster.Member;
220
import com.hazelcast.cluster.MembershipListener;
221
import com.hazelcast.partition.PartitionService;
222

223
// Cluster operations
224
Cluster cluster = hz.getCluster();
225
cluster.addMembershipListener(new MembershipListener() {
226
    public void memberAdded(MembershipEvent membershipEvent) {
227
        System.out.println("Member added: " + membershipEvent.getMember());
228
    }
229
    // ... other methods
230
});
231

232
// Partition information
233
PartitionService partitionService = hz.getPartitionService();
234
Partition partition = partitionService.getPartition("my-key");
235
```
236

237
[Cluster Management](./cluster-management.md)
238

239
### Configuration
240
Comprehensive configuration system supporting programmatic, XML, and YAML configuration.
241

242
```java { .api }
243
import com.hazelcast.config.Config;
244
import com.hazelcast.config.MapConfig;
245
import com.hazelcast.config.NetworkConfig;
246
import com.hazelcast.config.JoinConfig;
247

248
Config config = new Config();
249

250
// Map configuration
251
MapConfig mapConfig = new MapConfig("my-map");
252
mapConfig.setBackupCount(2);
253
mapConfig.setTimeToLiveSeconds(300);
254
config.addMapConfig(mapConfig);
255

256
// Network configuration
257
NetworkConfig network = config.getNetworkConfig();
258
network.setPort(5701);
259
JoinConfig join = network.getJoin();
260
join.getMulticastConfig().setEnabled(false);
261
join.getTcpIpConfig().setEnabled(true).addMember("192.168.1.100");
262
```
263

264
[Configuration](./configuration.md)
265

266
## Key Features
267

268
- **High Performance**: In-memory storage with microsecond latencies
269
- **Horizontal Scaling**: Linear scale-out across commodity hardware  
270
- **Fault Tolerance**: Automatic failover and data recovery
271
- **ACID Compliance**: Transactions and consistency guarantees
272
- **Standard Integration**: JCache (JSR-107), Spring, CDI support
273
- **Cloud Native**: Kubernetes operator and cloud discovery
274
- **Security**: Authentication, authorization, TLS encryption
275
- **Monitoring**: JMX metrics and management center integration