0
# Vert.x Core
1

2
Vert.x Core is a high-performance, reactive application toolkit for the JVM that provides fundamental building blocks for creating modern, scalable applications. It offers comprehensive support for asynchronous I/O operations including HTTP/HTTPS servers and clients, TCP networking, file system access, event bus messaging, and WebSocket communication, all built on top of Netty for maximum performance.
3

4
## Package Information
5

6
- **Package Name**: io.vertx:vertx-core
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Add dependency in `pom.xml`:
10

11
```xml
12
<dependency>
13
  <groupId>io.vertx</groupId>
14
  <artifactId>vertx-core</artifactId>
15
  <version>4.5.14</version>
16
</dependency>
17
```
18

19
## Core Imports
20

21
```java
22
import io.vertx.core.Vertx;
23
import io.vertx.core.Future;
24
import io.vertx.core.Promise;
25
import io.vertx.core.Context;
26
import io.vertx.core.Handler;
27
import io.vertx.core.Verticle;
28
import io.vertx.core.AbstractVerticle;
29
```
30

31
## Basic Usage
32

33
```java
34
import io.vertx.core.Vertx;
35
import io.vertx.core.AbstractVerticle;
36
import io.vertx.core.Future;
37

38
public class BasicExample extends AbstractVerticle {
39
  
40
  @Override
41
  public Future<Void> start() {
42
    // Create HTTP server
43
    return vertx.createHttpServer()
44
      .requestHandler(request -> {
45
        request.response()
46
          .putHeader("content-type", "text/plain")
47
          .end("Hello from Vert.x!");
48
      })
49
      .listen(8080)
50
      .mapEmpty();
51
  }
52
  
53
  public static void main(String[] args) {
54
    Vertx vertx = Vertx.vertx();
55
    vertx.deployVerticle(new BasicExample());
56
  }
57
}
58
```
59

60
## Architecture
61

62
Vert.x Core is built around several key components:
63

64
- **Event Loop**: Non-blocking event-driven architecture with multiple event loops
65
- **Verticles**: Deployable units of functionality that communicate through the event bus
66
- **Future/Promise Pattern**: Asynchronous programming model for non-blocking operations
67
- **Context Propagation**: Execution contexts that ensure thread-safe handler execution
68
- **Event Bus**: Distributed messaging system for inter-verticle communication
69
- **Reactive Streams**: Back-pressure aware streaming abstractions
70

71
## Capabilities
72

73
### Core API and Asynchronous Programming
74

75
Main entry points, verticle deployment, future composition, and asynchronous execution patterns. Essential for all Vert.x applications.
76

77
```java { .api }
78
// Main Vertx factory methods
79
static Vertx vertx();
80
static Vertx vertx(VertxOptions options);
81
static Future<Vertx> clusteredVertx(VertxOptions options);
82

83
// Future composition and handling
84
interface Future<T> extends AsyncResult<T> {
85
  Future<T> onSuccess(Handler<T> handler);
86
  Future<T> onFailure(Handler<Throwable> handler);
87
  Future<T> onComplete(Handler<AsyncResult<T>> handler);
88
  <U> Future<U> compose(Function<T, Future<U>> successMapper);
89
  <U> Future<U> map(Function<T, U> mapper);
90
  Future<T> recover(Function<Throwable, Future<T>> mapper);
91
}
92

93
// Promise for completing futures
94
interface Promise<T> extends Handler<AsyncResult<T>> {
95
  void complete(T result);
96
  void fail(Throwable cause);
97
  Future<T> future();
98
  boolean tryComplete(T result);
99
  boolean tryFail(Throwable cause);
100
}
101
```
102

103
[Core API](./core-api.md)
104

105
### HTTP Client and Server
106

107
Full-featured HTTP 1.1/2.0 client and server with WebSocket support, request/response handling, and streaming capabilities.
108

109
```java { .api }
110
// HTTP Server creation and configuration
111
HttpServer createHttpServer();
112
HttpServer createHttpServer(HttpServerOptions options);
113

114
interface HttpServer extends Measured, Closeable {
115
  HttpServer requestHandler(Handler<HttpServerRequest> handler);
116
  Future<HttpServer> listen(int port);
117
  Future<HttpServer> listen(int port, String host);
118
  HttpServer webSocketHandler(Handler<ServerWebSocket> handler);
119
}
120

121
// HTTP Client creation and requests
122
HttpClient createHttpClient();
123
HttpClient createHttpClient(HttpClientOptions options);
124

125
interface HttpClient extends Measured, Closeable {
126
  Future<HttpClientRequest> request(HttpMethod method, int port, String host, String requestURI);
127
  Future<HttpClientResponse> get(int port, String host, String requestURI);
128
  Future<HttpClientResponse> post(int port, String host, String requestURI);
129
}
130
```
131

132
[HTTP Client and Server](./http.md)
133

134
### TCP Networking, DNS, and UDP
135

136
Low-level TCP client/server networking with comprehensive SSL/TLS support, DNS resolution, and UDP datagram communication.
137

138
```java { .api }
139
// TCP Server and Client creation
140
NetServer createNetServer();
141
NetServer createNetServer(NetServerOptions options);
142
NetClient createNetClient();
143
NetClient createNetClient(NetClientOptions options);
144

145
// DNS Client creation
146
DnsClient createDnsClient();
147
DnsClient createDnsClient(int port, String host);
148
DnsClient createDnsClient(DnsClientOptions options);
149

150
// UDP/Datagram Socket creation
151
DatagramSocket createDatagramSocket();
152
DatagramSocket createDatagramSocket(DatagramSocketOptions options);
153

154
interface NetServer extends Measured, Closeable {
155
  NetServer connectHandler(Handler<NetSocket> handler);
156
  Future<NetServer> listen(int port);
157
  Future<NetServer> listen(int port, String host);
158
}
159

160
interface NetClient extends Measured, Closeable {
161
  Future<NetSocket> connect(int port, String host);
162
  Future<NetSocket> connect(SocketAddress remoteAddress);
163
}
164

165
interface DnsClient {
166
  Future<String> lookup(String name);
167
  Future<List<String>> resolveA(String name);
168
  Future<List<MxRecord>> resolveMX(String name);
169
  Future<String> reverseLookup(String ipaddress);
170
}
171

172
interface DatagramSocket extends Measured, Closeable {
173
  Future<DatagramSocket> send(Buffer packet, int port, String host);
174
  Future<DatagramSocket> listen(int port, String host);
175
  DatagramSocket handler(Handler<DatagramPacket> handler);
176
}
177
```
178

179
[Networking](./networking.md)
180

181
### Event Bus Messaging
182

183
Distributed messaging system for inter-verticle and inter-node communication with publish/subscribe and request/response patterns.
184

185
```java { .api }
186
// Event Bus access and messaging
187
EventBus eventBus();
188

189
interface EventBus extends Measured {
190
  EventBus send(String address, Object message);
191
  EventBus publish(String address, Object message);
192
  <T> Future<Message<T>> request(String address, Object message);
193
  <T> MessageConsumer<T> consumer(String address);
194
  <T> MessageConsumer<T> consumer(String address, Handler<Message<T>> handler);
195
}
196

197
interface Message<T> {
198
  String address();
199
  MultiMap headers();
200
  T body();
201
  void reply(Object message);
202
  void fail(int failureCode, String message);
203
}
204
```
205

206
[Event Bus](./event-bus.md)
207

208
### File System Operations
209

210
Comprehensive asynchronous file system operations including file I/O, directory management, and file watching.
211

212
```java { .api }
213
// File System access
214
FileSystem fileSystem();
215

216
interface FileSystem {
217
  Future<Buffer> readFile(String path);
218
  Future<Void> writeFile(String path, Buffer data);
219
  Future<Void> copy(String from, String to);
220
  Future<Void> move(String from, String to);
221
  Future<Void> delete(String path);
222
  Future<AsyncFile> open(String path, OpenOptions options);
223
  Future<List<String>> readDir(String path);
224
}
225

226
interface AsyncFile extends ReadStream<Buffer>, WriteStream<Buffer> {
227
  Future<Void> close();
228
  Future<Buffer> read(Buffer buffer, int offset, long position, int length);
229
  Future<Void> write(Buffer buffer, long position);
230
}
231
```
232

233
[File System](./file-system.md)
234

235
### JSON, Buffers, and Utility APIs
236

237
JSON processing, buffer operations, reactive streams, shared data, CLI support, and other utility functionality.
238

239
```java { .api }
240
// Buffer operations
241
interface Buffer extends ClusterSerializable, Shareable {
242
  static Buffer buffer();
243
  static Buffer buffer(String string);
244
  static Buffer buffer(byte[] bytes);
245
  Buffer appendString(String str);
246
  Buffer appendBuffer(Buffer buff);
247
  String getString(int start, int end);
248
  JsonObject toJsonObject();
249
}
250

251
// JSON processing
252
class JsonObject implements Iterable<Map.Entry<String,Object>> {
253
  JsonObject put(String key, Object value);
254
  <T> T getValue(String key);
255
  String getString(String key);
256
  Integer getInteger(String key);
257
  JsonObject getJsonObject(String key);
258
  String encode();
259
}
260
```
261

262
[Utilities](./utilities.md)
263

264
## Types
265

266
```java { .api }
267
// Core execution contexts and handlers
268
interface Context {
269
  void runOnContext(Handler<Void> action);
270
  <T> void executeBlocking(Handler<Promise<T>> blockingCodeHandler, Handler<AsyncResult<T>> resultHandler);
271
  boolean isEventLoopContext();
272
  boolean isWorkerContext();
273
}
274

275
@FunctionalInterface
276
interface Handler<E> {
277
  void handle(E event);
278
}
279

280
// Asynchronous result handling
281
interface AsyncResult<T> {
282
  T result();
283
  Throwable cause();
284
  boolean succeeded();
285
  boolean failed();
286
}
287

288
// Verticle deployment and lifecycle
289
interface Verticle {
290
  Vertx getVertx();
291
  void init(Vertx vertx, Context context);
292
  Future<Void> start();
293
  Future<Void> stop();
294
}
295

296
// Configuration options base classes
297
class VertxOptions {
298
  VertxOptions setEventLoopPoolSize(int eventLoopPoolSize);
299
  VertxOptions setWorkerPoolSize(int workerPoolSize);
300
  VertxOptions setBlockedThreadCheckInterval(long blockedThreadCheckInterval);
301
  VertxOptions setHAEnabled(boolean haEnabled);
302
}
303

304
class DeploymentOptions {
305
  DeploymentOptions setConfig(JsonObject config);
306
  DeploymentOptions setWorker(boolean worker);
307
  DeploymentOptions setInstances(int instances);
308
  DeploymentOptions setThreadingModel(ThreadingModel threadingModel);
309
}
310

311
// Threading models
312
enum ThreadingModel {
313
  EVENT_LOOP, WORKER, VIRTUAL_THREAD
314
}
315
```