0
# Utilities
1

2
JSON processing, buffer operations, reactive streams, shared data, CLI support, datagram/DNS operations, and other utility functionality.
3

4
## Capabilities
5

6
### JSON Processing
7

8
High-performance JSON object and array handling with comprehensive encoding/decoding support.
9

10
```java { .api }
11
/**
12
 * JSON object representation with fluent API
13
 */
14
class JsonObject implements Iterable<Map.Entry<String,Object>>, ClusterSerializable, Shareable {
15
  /**
16
   * Create empty JSON object
17
   */
18
  JsonObject();
19

20
  /**
21
   * Create JSON object from string
22
   * @param json JSON string to parse
23
   */
24
  JsonObject(String json);
25

26
  /**
27
   * Put value in JSON object
28
   * @param key Property key
29
   * @param value Property value
30
   * @return this for chaining
31
   */
32
  JsonObject put(String key, Object value);
33

34
  /**
35
   * Get value from JSON object
36
   * @param key Property key
37
   * @return Property value
38
   */
39
  <T> T getValue(String key);
40

41
  /**
42
   * Get string value
43
   * @param key Property key
44
   * @return String value
45
   */
46
  String getString(String key);
47

48
  /**
49
   * Get string value with default
50
   * @param key Property key
51
   * @param def Default value
52
   * @return String value or default
53
   */
54
  String getString(String key, String def);
55

56
  /**
57
   * Get integer value
58
   * @param key Property key
59
   * @return Integer value
60
   */
61
  Integer getInteger(String key);
62

63
  /**
64
   * Get integer value with default
65
   * @param key Property key
66
   * @param def Default value
67
   * @return Integer value or default
68
   */
69
  Integer getInteger(String key, Integer def);
70

71
  /**
72
   * Get long value
73
   * @param key Property key
74
   * @return Long value
75
   */
76
  Long getLong(String key);
77

78
  /**
79
   * Get double value
80
   * @param key Property key
81
   * @return Double value
82
   */
83
  Double getDouble(String key);
84

85
  /**
86
   * Get float value
87
   * @param key Property key
88
   * @return Float value
89
   */
90
  Float getFloat(String key);
91

92
  /**
93
   * Get boolean value
94
   * @param key Property key
95
   * @return Boolean value
96
   */
97
  Boolean getBoolean(String key);
98

99
  /**
100
   * Get JSON object value
101
   * @param key Property key
102
   * @return JsonObject value
103
   */
104
  JsonObject getJsonObject(String key);
105

106
  /**
107
   * Get JSON array value
108
   * @param key Property key
109
   * @return JsonArray value
110
   */
111
  JsonArray getJsonArray(String key);
112

113
  /**
114
   * Get binary value
115
   * @param key Property key
116
   * @return byte array
117
   */
118
  byte[] getBinary(String key);
119

120
  /**
121
   * Get instant value
122
   * @param key Property key
123
   * @return Instant value
124
   */
125
  Instant getInstant(String key);
126

127
  /**
128
   * Check if key exists
129
   * @param key Property key
130
   * @return true if key exists
131
   */
132
  boolean containsKey(String key);
133

134
  /**
135
   * Get all field names
136
   * @return Set of field names
137
   */
138
  Set<String> fieldNames();
139

140
  /**
141
   * Get number of fields
142
   * @return Field count
143
   */
144
  int size();
145

146
  /**
147
   * Clear all fields
148
   * @return this for chaining
149
   */
150
  JsonObject clear();
151

152
  /**
153
   * Check if empty
154
   * @return true if empty
155
   */
156
  boolean isEmpty();
157

158
  /**
159
   * Remove field
160
   * @param key Field key to remove
161
   * @return Removed value
162
   */
163
  Object remove(String key);
164

165
  /**
166
   * Copy JSON object
167
   * @return Deep copy
168
   */
169
  JsonObject copy();
170

171
  /**
172
   * Merge another JSON object into this one
173
   * @param other JSON object to merge
174
   * @return this for chaining
175
   */
176
  JsonObject mergeIn(JsonObject other);
177

178
  /**
179
   * Encode to JSON string
180
   * @return JSON string
181
   */
182
  String encode();
183

184
  /**
185
   * Encode to pretty JSON string
186
   * @return Pretty JSON string
187
   */
188
  String encodePrettily();
189

190
  /**
191
   * Convert to Map
192
   * @return Map representation
193
   */
194
  Map<String, Object> getMap();
195

196
  /**
197
   * Create JsonObject from Map
198
   * @param map Source map
199
   * @return JsonObject
200
   */
201
  static JsonObject mapFrom(Object map);
202

203
  /**
204
   * Map to POJO
205
   * @param type Target class
206
   * @return POJO instance
207
   */
208
  <T> T mapTo(Class<T> type);
209
}
210

211
/**
212
 * JSON array representation with fluent API
213
 */
214
class JsonArray implements Iterable<Object>, ClusterSerializable, Shareable {
215
  /**
216
   * Create empty JSON array
217
   */
218
  JsonArray();
219

220
  /**
221
   * Create JSON array from string
222
   * @param json JSON string to parse
223
   */
224
  JsonArray(String json);
225

226
  /**
227
   * Add value to array
228
   * @param value Value to add
229
   * @return this for chaining
230
   */
231
  JsonArray add(Object value);
232

233
  /**
234
   * Add null to array
235
   * @return this for chaining
236
   */
237
  JsonArray addNull();
238

239
  /**
240
   * Get value at index
241
   * @param index Array index
242
   * @return Value at index
243
   */
244
  <T> T getValue(int index);
245

246
  /**
247
   * Get string at index
248
   * @param index Array index
249
   * @return String value
250
   */
251
  String getString(int index);
252

253
  /**
254
   * Get integer at index
255
   * @param index Array index
256
   * @return Integer value
257
   */
258
  Integer getInteger(int index);
259

260
  /**
261
   * Get long at index
262
   * @param index Array index
263
   * @return Long value
264
   */
265
  Long getLong(int index);
266

267
  /**
268
   * Get double at index
269
   * @param index Array index
270
   * @return Double value
271
   */
272
  Double getDouble(int index);
273

274
  /**
275
   * Get float at index
276
   * @param index Array index
277
   * @return Float value
278
   */
279
  Float getFloat(int index);
280

281
  /**
282
   * Get boolean at index
283
   * @param index Array index
284
   * @return Boolean value
285
   */
286
  Boolean getBoolean(int index);
287

288
  /**
289
   * Get JSON object at index
290
   * @param index Array index
291
   * @return JsonObject value
292
   */
293
  JsonObject getJsonObject(int index);
294

295
  /**
296
   * Get JSON array at index
297
   * @param index Array index
298
   * @return JsonArray value
299
   */
300
  JsonArray getJsonArray(int index);
301

302
  /**
303
   * Get binary at index
304
   * @param index Array index
305
   * @return byte array
306
   */
307
  byte[] getBinary(int index);
308

309
  /**
310
   * Get instant at index
311
   * @param index Array index
312
   * @return Instant value
313
   */
314
  Instant getInstant(int index);
315

316
  /**
317
   * Check if contains null at index
318
   * @param index Array index
319
   * @return true if null
320
   */
321
  boolean hasNull(int index);
322

323
  /**
324
   * Check if contains value
325
   * @param value Value to check
326
   * @return true if contains
327
   */
328
  boolean contains(Object value);
329

330
  /**
331
   * Remove value at index
332
   * @param index Array index
333
   * @return Removed value
334
   */
335
  Object remove(int index);
336

337
  /**
338
   * Remove value
339
   * @param value Value to remove
340
   * @return true if removed
341
   */
342
  boolean remove(Object value);
343

344
  /**
345
   * Get array size
346
   * @return Array size
347
   */
348
  int size();
349

350
  /**
351
   * Clear array
352
   * @return this for chaining
353
   */
354
  JsonArray clear();
355

356
  /**
357
   * Check if empty
358
   * @return true if empty
359
   */
360
  boolean isEmpty();
361

362
  /**
363
   * Copy array
364
   * @return Deep copy
365
   */
366
  JsonArray copy();
367

368
  /**
369
   * Encode to JSON string
370
   * @return JSON string
371
   */
372
  String encode();
373

374
  /**
375
   * Encode to pretty JSON string
376
   * @return Pretty JSON string
377
   */
378
  String encodePrettily();
379

380
  /**
381
   * Get as List
382
   * @return List representation
383
   */
384
  List<Object> getList();
385

386
  /**
387
   * Get stream of elements
388
   * @return Stream of elements
389
   */
390
  Stream<Object> stream();
391
}
392

393
/**
394
 * Static JSON utilities
395
 */
396
class Json {
397
  /**
398
   * Encode object to JSON string
399
   * @param obj Object to encode
400
   * @return JSON string
401
   */
402
  static String encode(Object obj);
403

404
  /**
405
   * Encode object to pretty JSON string
406
   * @param obj Object to encode
407
   * @return Pretty JSON string
408
   */
409
  static String encodePrettily(Object obj);
410

411
  /**
412
   * Decode JSON string to object
413
   * @param str JSON string
414
   * @return Decoded object
415
   */
416
  static Object decodeValue(String str);
417

418
  /**
419
   * Decode JSON string to specific type
420
   * @param str JSON string
421
   * @param clazz Target class
422
   * @return Decoded object
423
   */
424
  static <T> T decodeValue(String str, Class<T> clazz);
425

426
  /**
427
   * Get Jackson ObjectMapper
428
   * @return ObjectMapper instance
429
   */
430
  static ObjectMapper mapper;
431

432
  /**
433
   * Get pretty Jackson ObjectMapper
434
   * @return Pretty ObjectMapper instance
435
   */
436
  static ObjectMapper prettyMapper;
437
}
438
```
439

440
### Buffer Operations
441

442
Mutable byte buffer operations with support for various data types and JSON conversion.
443

444
```java { .api }
445
/**
446
 * Mutable byte buffer with fluent API
447
 */
448
interface Buffer extends ClusterSerializable, Shareable {
449
  /**
450
   * Create empty buffer
451
   * @return Empty buffer
452
   */
453
  static Buffer buffer();
454

455
  /**
456
   * Create buffer with initial capacity
457
   * @param initialSizeHint Initial size hint
458
   * @return Buffer with capacity
459
   */
460
  static Buffer buffer(int initialSizeHint);
461

462
  /**
463
   * Create buffer from string
464
   * @param string Source string
465
   * @return Buffer with string data
466
   */
467
  static Buffer buffer(String string);
468

469
  /**
470
   * Create buffer from string with encoding
471
   * @param string Source string
472
   * @param enc Character encoding
473
   * @return Buffer with encoded string data
474
   */
475
  static Buffer buffer(String string, String enc);
476

477
  /**
478
   * Create buffer from byte array
479
   * @param bytes Source byte array
480
   * @return Buffer with byte data
481
   */
482
  static Buffer buffer(byte[] bytes);
483

484
  /**
485
   * Append buffer
486
   * @param buff Buffer to append
487
   * @return this for chaining
488
   */
489
  Buffer appendBuffer(Buffer buff);
490

491
  /**
492
   * Append buffer with offset and length
493
   * @param buff Buffer to append
494
   * @param offset Offset in source buffer
495
   * @param len Length to append
496
   * @return this for chaining
497
   */
498
  Buffer appendBuffer(Buffer buff, int offset, int len);
499

500
  /**
501
   * Append byte array
502
   * @param bytes Bytes to append
503
   * @return this for chaining
504
   */
505
  Buffer appendBytes(byte[] bytes);
506

507
  /**
508
   * Append byte array with offset and length
509
   * @param bytes Bytes to append
510
   * @param offset Offset in array
511
   * @param len Length to append
512
   * @return this for chaining
513
   */
514
  Buffer appendBytes(byte[] bytes, int offset, int len);
515

516
  /**
517
   * Append single byte
518
   * @param b Byte to append
519
   * @return this for chaining
520
   */
521
  Buffer appendByte(byte b);
522

523
  /**
524
   * Append int as 4 bytes
525
   * @param i Int value
526
   * @return this for chaining
527
   */
528
  Buffer appendInt(int i);
529

530
  /**
531
   * Append int as 4 bytes with endianness
532
   * @param i Int value
533
   * @param endianness Byte order
534
   * @return this for chaining
535
   */
536
  Buffer appendIntLE(int i);
537

538
  /**
539
   * Append long as 8 bytes
540
   * @param l Long value
541
   * @return this for chaining
542
   */
543
  Buffer appendLong(long l);
544

545
  /**
546
   * Append long as 8 bytes with endianness
547
   * @param l Long value
548
   * @return this for chaining
549
   */
550
  Buffer appendLongLE(long l);
551

552
  /**
553
   * Append short as 2 bytes
554
   * @param s Short value
555
   * @return this for chaining
556
   */
557
  Buffer appendShort(short s);
558

559
  /**
560
   * Append short as 2 bytes with endianness
561
   * @param s Short value
562
   * @return this for chaining
563
   */
564
  Buffer appendShortLE(short s);
565

566
  /**
567
   * Append float as 4 bytes
568
   * @param f Float value
569
   * @return this for chaining
570
   */
571
  Buffer appendFloat(float f);
572

573
  /**
574
   * Append double as 8 bytes
575
   * @param d Double value
576
   * @return this for chaining
577
   */
578
  Buffer appendDouble(double d);
579

580
  /**
581
   * Append string
582
   * @param str String to append
583
   * @return this for chaining
584
   */
585
  Buffer appendString(String str);
586

587
  /**
588
   * Append string with encoding
589
   * @param str String to append
590
   * @param enc Character encoding
591
   * @return this for chaining
592
   */
593
  Buffer appendString(String str, String enc);
594

595
  /**
596
   * Get byte at position
597
   * @param pos Buffer position
598
   * @return Byte value
599
   */
600
  byte getByte(int pos);
601

602
  /**
603
   * Get bytes from position
604
   * @param start Start position
605
   * @param end End position
606
   * @return Byte array
607
   */
608
  byte[] getBytes(int start, int end);
609

610
  /**
611
   * Get int from position
612
   * @param pos Buffer position
613
   * @return Int value
614
   */
615
  int getInt(int pos);
616

617
  /**
618
   * Get int with endianness
619
   * @param pos Buffer position
620
   * @return Int value
621
   */
622
  int getIntLE(int pos);
623

624
  /**
625
   * Get long from position
626
   * @param pos Buffer position
627
   * @return Long value
628
   */
629
  long getLong(int pos);
630

631
  /**
632
   * Get long with endianness
633
   * @param pos Buffer position
634
   * @return Long value
635
   */
636
  long getLongLE(int pos);
637

638
  /**
639
   * Get short from position
640
   * @param pos Buffer position
641
   * @return Short value
642
   */
643
  short getShort(int pos);
644

645
  /**
646
   * Get short with endianness
647
   * @param pos Buffer position
648
   * @return Short value
649
   */
650
  short getShortLE(int pos);
651

652
  /**
653
   * Get float from position
654
   * @param pos Buffer position
655
   * @return Float value
656
   */
657
  float getFloat(int pos);
658

659
  /**
660
   * Get double from position
661
   * @param pos Buffer position
662
   * @return Double value
663
   */
664
  double getDouble(int pos);
665

666
  /**
667
   * Get string from position range
668
   * @param start Start position
669
   * @param end End position
670
   * @return String value
671
   */
672
  String getString(int start, int end);
673

674
  /**
675
   * Get string with encoding
676
   * @param start Start position
677
   * @param end End position
678
   * @param enc Character encoding
679
   * @return String value
680
   */
681
  String getString(int start, int end, String enc);
682

683
  /**
684
   * Set byte at position
685
   * @param pos Buffer position
686
   * @param b Byte value
687
   * @return this for chaining
688
   */
689
  Buffer setByte(int pos, byte b);
690

691
  /**
692
   * Set bytes at position
693
   * @param pos Buffer position
694
   * @param bytes Byte array
695
   * @return this for chaining
696
   */
697
  Buffer setBytes(int pos, byte[] bytes);
698

699
  /**
700
   * Set bytes with offset and length
701
   * @param pos Buffer position
702
   * @param bytes Byte array
703
   * @param offset Offset in array
704
   * @param len Length to set
705
   * @return this for chaining
706
   */
707
  Buffer setBytes(int pos, byte[] bytes, int offset, int len);
708

709
  /**
710
   * Set buffer at position
711
   * @param pos Buffer position
712
   * @param buff Buffer to set
713
   * @return this for chaining
714
   */
715
  Buffer setBuffer(int pos, Buffer buff);
716

717
  /**
718
   * Set buffer with offset and length
719
   * @param pos Buffer position
720
   * @param buff Buffer to set
721
   * @param offset Offset in source buffer
722
   * @param len Length to set
723
   * @return this for chaining
724
   */
725
  Buffer setBuffer(int pos, Buffer buff, int offset, int len);
726

727
  /**
728
   * Set int at position
729
   * @param pos Buffer position
730
   * @param i Int value
731
   * @return this for chaining
732
   */
733
  Buffer setInt(int pos, int i);
734

735
  /**
736
   * Set int with endianness
737
   * @param pos Buffer position
738
   * @param i Int value
739
   * @return this for chaining
740
   */
741
  Buffer setIntLE(int pos, int i);
742

743
  /**
744
   * Set long at position
745
   * @param pos Buffer position
746
   * @param l Long value
747
   * @return this for chaining
748
   */
749
  Buffer setLong(int pos, long l);
750

751
  /**
752
   * Set long with endianness
753
   * @param pos Buffer position
754
   * @param l Long value
755
   * @return this for chaining
756
   */
757
  Buffer setLongLE(int pos, long l);
758

759
  /**
760
   * Set short at position
761
   * @param pos Buffer position
762
   * @param s Short value
763
   * @return this for chaining
764
   */
765
  Buffer setShort(int pos, short s);
766

767
  /**
768
   * Set short with endianness
769
   * @param pos Buffer position
770
   * @param s Short value
771
   * @return this for chaining
772
   */
773
  Buffer setShortLE(int pos, short s);
774

775
  /**
776
   * Set float at position
777
   * @param pos Buffer position
778
   * @param f Float value
779
   * @return this for chaining
780
   */
781
  Buffer setFloat(int pos, float f);
782

783
  /**
784
   * Set double at position
785
   * @param pos Buffer position
786
   * @param d Double value
787
   * @return this for chaining
788
   */
789
  Buffer setDouble(int pos, double d);
790

791
  /**
792
   * Set string at position
793
   * @param pos Buffer position
794
   * @param str String value
795
   * @return this for chaining
796
   */
797
  Buffer setString(int pos, String str);
798

799
  /**
800
   * Set string with encoding
801
   * @param pos Buffer position
802
   * @param str String value
803
   * @param enc Character encoding
804
   * @return this for chaining
805
   */
806
  Buffer setString(int pos, String str, String enc);
807

808
  /**
809
   * Get buffer length
810
   * @return Buffer length
811
   */
812
  int length();
813

814
  /**
815
   * Copy buffer
816
   * @return Deep copy
817
   */
818
  Buffer copy();
819

820
  /**
821
   * Get slice of buffer
822
   * @param start Start position
823
   * @param end End position
824
   * @return Buffer slice
825
   */
826
  Buffer slice(int start, int end);
827

828
  /**
829
   * Get slice from start
830
   * @param start Start position
831
   * @return Buffer slice
832
   */
833
  Buffer slice(int start);
834

835
  /**
836
   * Convert to JSON object
837
   * @return JsonObject
838
   */
839
  JsonObject toJsonObject();
840

841
  /**
842
   * Convert to JSON array
843
   * @return JsonArray
844
   */
845
  JsonArray toJsonArray();
846

847
  /**
848
   * Convert to string
849
   * @return String representation
850
   */
851
  String toString();
852

853
  /**
854
   * Convert to string with encoding
855
   * @param enc Character encoding
856
   * @return String representation
857
   */
858
  String toString(String enc);
859

860
  /**
861
   * Get underlying byte array
862
   * @return Byte array
863
   */
864
  byte[] getBytes();
865
}
866
```
867

868
### Reactive Streams
869

870
Stream abstractions with back-pressure support for reading and writing data.
871

872
```java { .api }
873
/**
874
 * Readable stream interface
875
 */
876
interface ReadStream<T> extends StreamBase {
877
  /**
878
   * Set data handler
879
   * @param handler Handler for data items
880
   * @return this for chaining
881
   */
882
  ReadStream<T> handler(Handler<T> handler);
883

884
  /**
885
   * Pause reading
886
   * @return this for chaining
887
   */
888
  ReadStream<T> pause();
889

890
  /**
891
   * Resume reading
892
   * @return this for chaining
893
   */
894
  ReadStream<T> resume();
895

896
  /**
897
   * Fetch specific number of items
898
   * @param amount Number of items to fetch
899
   * @return this for chaining
900
   */
901
  ReadStream<T> fetch(long amount);
902

903
  /**
904
   * Set end handler
905
   * @param endHandler Handler called when stream ends
906
   * @return this for chaining
907
   */
908
  ReadStream<T> endHandler(Handler<Void> endHandler);
909

910
  /**
911
   * Pipe to write stream
912
   * @param dst Destination write stream
913
   * @return Pipe instance
914
   */
915
  <R> Pipe<R> pipe();
916

917
  /**
918
   * Pipe to write stream
919
   * @param dst Destination write stream
920
   * @return Future that completes when piping is done
921
   */
922
  Future<Void> pipeTo(WriteStream<T> dst);
923
}
924

925
/**
926
 * Writable stream interface
927
 */
928
interface WriteStream<T> extends StreamBase {
929
  /**
930
   * Write data to stream
931
   * @param data Data to write
932
   * @return Future that completes when written
933
   */
934
  Future<Void> write(T data);
935

936
  /**
937
   * End the stream
938
   * @return Future that completes when ended
939
   */
940
  Future<Void> end();
941

942
  /**
943
   * End the stream with final data
944
   * @param data Final data to write
945
   * @return Future that completes when ended
946
   */
947
  Future<Void> end(T data);
948

949
  /**
950
   * Set write queue max size
951
   * @param maxSize Maximum queue size
952
   * @return this for chaining
953
   */
954
  WriteStream<T> setWriteQueueMaxSize(int maxSize);
955

956
  /**
957
   * Check if write queue is full
958
   * @return true if full
959
   */
960
  boolean writeQueueFull();
961

962
  /**
963
   * Set drain handler for back-pressure
964
   * @param handler Handler called when queue drains
965
   * @return this for chaining
966
   */
967
  WriteStream<T> drainHandler(Handler<Void> handler);
968
}
969

970
/**
971
 * Base stream interface
972
 */
973
interface StreamBase {
974
  /**
975
   * Set exception handler
976
   * @param handler Exception handler
977
   * @return this for chaining
978
   */
979
  StreamBase exceptionHandler(Handler<Throwable> handler);
980
}
981

982
/**
983
 * Stream pipe for connecting read and write streams
984
 */
985
interface Pipe<T> {
986
  /**
987
   * Set end on failure behavior
988
   * @param end Whether to end destination on failure
989
   * @return this for chaining
990
   */
991
  Pipe<T> endOnFailure(boolean end);
992

993
  /**
994
   * Set end on success behavior
995
   * @param end Whether to end destination on success
996
   * @return this for chaining
997
   */
998
  Pipe<T> endOnSuccess(boolean end);
999

1000
  /**
1001
   * Set end on complete behavior
1002
   * @param end Whether to end destination on complete
1003
   * @return this for chaining
1004
   */
1005
  Pipe<T> endOnComplete(boolean end);
1006

1007
  /**
1008
   * Pipe to destination
1009
   * @param dst Destination write stream
1010
   * @return Future that completes when done
1011
   */
1012
  Future<Void> to(WriteStream<T> dst);
1013

1014
  /**
1015
   * Close the pipe
1016
   */
1017
  void close();
1018
}
1019

1020
/**
1021
 * Utility for pumping data between streams
1022
 */
1023
class Pump {
1024
  /**
1025
   * Create pump between streams
1026
   * @param rs Read stream
1027
   * @param ws Write stream
1028
   * @return Pump instance
1029
   */
1030
  static Pump pump(ReadStream rs, WriteStream ws);
1031

1032
  /**
1033
   * Create pump with throughput control
1034
   * @param rs Read stream
1035
   * @param ws Write stream
1036
   * @param writeQueueMaxSize Write queue max size
1037
   * @return Pump instance
1038
   */
1039
  static Pump pump(ReadStream rs, WriteStream ws, int writeQueueMaxSize);
1040

1041
  /**
1042
   * Start pumping
1043
   * @return this for chaining
1044
   */
1045
  Pump start();
1046

1047
  /**
1048
   * Stop pumping
1049
   * @return Stopped pump
1050
   */
1051
  Pump stop();
1052

1053
  /**
1054
   * Get number of bytes pumped
1055
   * @return Bytes pumped count
1056
   */
1057
  int numberPumped();
1058
}
1059
```
1060

1061
### Shared Data
1062

1063
Thread-safe and cluster-wide data sharing mechanisms.
1064

1065
```java { .api }
1066
/**
1067
 * Shared data access
1068
 * @return SharedData instance
1069
 */
1070
SharedData sharedData();
1071

1072
/**
1073
 * Shared data interface for maps, locks, and counters
1074
 */
1075
interface SharedData {
1076
  /**
1077
   * Get local shared map
1078
   * @param name Map name
1079
   * @return Local map
1080
   */
1081
  <K, V> LocalMap<K, V> getLocalMap(String name);
1082

1083
  /**
1084
   * Get cluster-wide async map
1085
   * @param name Map name
1086
   * @return Future that completes with async map
1087
   */
1088
  <K, V> Future<AsyncMap<K, V>> getAsyncMap(String name);
1089

1090
  /**
1091
   * Get cluster-wide async map (deprecated method name)
1092
   * @param name Map name
1093
   * @return Future that completes with async map
1094
   */
1095
  <K, V> Future<AsyncMap<K, V>> getClusterWideMap(String name);
1096

1097
  /**
1098
   * Get distributed lock
1099
   * @param name Lock name
1100
   * @return Future that completes with lock
1101
   */
1102
  Future<Lock> getLock(String name);
1103

1104
  /**
1105
   * Get distributed lock with timeout
1106
   * @param name Lock name
1107
   * @param timeout Timeout in milliseconds
1108
   * @return Future that completes with lock
1109
   */
1110
  Future<Lock> getLockWithTimeout(String name, long timeout);
1111

1112
  /**
1113
   * Get local lock
1114
   * @param name Lock name
1115
   * @return Future that completes with lock
1116
   */
1117
  Future<Lock> getLocalLock(String name);
1118

1119
  /**
1120
   * Get local lock with timeout
1121
   * @param name Lock name
1122
   * @param timeout Timeout in milliseconds
1123
   * @return Future that completes with lock
1124
   */
1125
  Future<Lock> getLocalLockWithTimeout(String name, long timeout);
1126

1127
  /**
1128
   * Get distributed counter
1129
   * @param name Counter name
1130
   * @return Future that completes with counter
1131
   */
1132
  Future<Counter> getCounter(String name);
1133

1134
  /**
1135
   * Get local counter
1136
   * @param name Counter name
1137
   * @return Future that completes with counter
1138
   */
1139
  Future<Counter> getLocalCounter(String name);
1140
}
1141

1142
/**
1143
 * Local shared map within Vert.x instance
1144
 */
1145
interface LocalMap<K, V> extends ClusterSerializable {
1146
  V get(Object key);
1147
  V put(K key, V value);
1148
  V remove(Object key);
1149
  void clear();
1150
  int size();
1151
  boolean isEmpty();
1152
  V putIfAbsent(K key, V value);
1153
  boolean removeIfPresent(K key, V value);
1154
  boolean replaceIfPresent(K key, V oldValue, V newValue);
1155
  V replace(K key, V value);
1156
  void close();
1157
  Set<K> keySet();
1158
  Collection<V> values();
1159
}
1160

1161
/**
1162
 * Asynchronous distributed map
1163
 */
1164
interface AsyncMap<K, V> {
1165
  Future<V> get(K k);
1166
  Future<Void> put(K k, V v);
1167
  Future<Void> put(K k, V v, long timeout);
1168
  Future<V> putIfAbsent(K k, V v);
1169
  Future<V> putIfAbsent(K k, V v, long timeout);
1170
  Future<V> remove(K k);
1171
  Future<Boolean> removeIfPresent(K k, V v);
1172
  Future<V> replace(K k, V v);
1173
  Future<Boolean> replaceIfPresent(K k, V oldValue, V newValue);
1174
  Future<Void> clear();
1175
  Future<Integer> size();
1176
  Future<Set<K>> keys();
1177
  Future<List<V>> values();
1178
  Future<Map<K, V>> entries();
1179
  Future<Void> close();
1180
}
1181

1182
/**
1183
 * Distributed counter
1184
 */
1185
interface Counter {
1186
  Future<Long> get();
1187
  Future<Long> incrementAndGet();
1188
  Future<Long> getAndIncrement();
1189
  Future<Long> decrementAndGet();
1190
  Future<Long> getAndDecrement();
1191
  Future<Long> addAndGet(long value);
1192
  Future<Long> getAndAdd(long value);
1193
  Future<Boolean> compareAndSet(long expected, long value);
1194
}
1195

1196
/**
1197
 * Distributed lock
1198
 */
1199
interface Lock {
1200
  Future<Void> release();
1201
}
1202

1203
/**
1204
 * Marker interface for shareable objects
1205
 */
1206
interface Shareable {
1207
}
1208

1209
/**
1210
 * Interface for cluster serializable objects  
1211
 */
1212
interface ClusterSerializable {
1213
}
1214
```
1215

1216
### Datagram and DNS Support
1217

1218
UDP datagram sockets and DNS resolution capabilities.
1219

1220
```java { .api }
1221
/**
1222
 * Create datagram socket
1223
 * @return DatagramSocket instance
1224
 */
1225
DatagramSocket createDatagramSocket();
1226

1227
/**
1228
 * Create datagram socket with options
1229
 * @param options Socket options
1230
 * @return DatagramSocket instance
1231
 */
1232
DatagramSocket createDatagramSocket(DatagramSocketOptions options);
1233

1234
/**
1235
 * UDP datagram socket interface
1236
 */
1237
interface DatagramSocket extends Measured, Closeable {
1238
  /**
1239
   * Send datagram packet
1240
   * @param packet Packet data
1241
   * @param port Target port  
1242
   * @param host Target host
1243
   * @return Future that completes when sent
1244
   */
1245
  Future<Void> send(Buffer packet, int port, String host);
1246

1247
  /**
1248
   * Send datagram packet to address
1249
   * @param packet Packet data
1250
   * @param recipient Target address
1251
   * @return Future that completes when sent
1252
   */
1253
  Future<Void> send(Buffer packet, SocketAddress recipient);
1254

1255
  /**
1256
   * Get sender for address
1257
   * @param port Target port
1258
   * @param host Target host
1259
   * @return Packet sender
1260
   */
1261
  PacketWritestream sender(int port, String host);
1262

1263
  /**
1264
   * Set packet handler
1265
   * @param handler Packet handler
1266
   * @return this for chaining
1267
   */
1268
  DatagramSocket handler(Handler<DatagramPacket> handler);
1269

1270
  /**
1271
   * Listen for packets
1272
   * @param port Local port
1273
   * @param host Local host
1274
   * @return Future that completes when listening
1275
   */
1276
  Future<DatagramSocket> listen(int port, String host);
1277

1278
  /**
1279
   * Join multicast group
1280
   * @param multicastAddress Multicast address
1281
   * @return Future that completes when joined
1282
   */
1283
  Future<Void> listenMulticastGroup(String multicastAddress);
1284

1285
  /**
1286
   * Leave multicast group
1287
   * @param multicastAddress Multicast address
1288
   * @return Future that completes when left
1289
   */
1290
  Future<Void> unlistenMulticastGroup(String multicastAddress);
1291

1292
  /**
1293
   * Block multicast group
1294
   * @param multicastAddress Multicast address  
1295
   * @param sourceToBlock Source to block
1296
   * @return Future that completes when blocked
1297
   */
1298
  Future<Void> blockMulticastGroup(String multicastAddress, String sourceToBlock);
1299

1300
  /**
1301
   * Get local address
1302
   * @return Local socket address
1303
   */
1304
  SocketAddress localAddress();
1305

1306
  /**
1307
   * Close socket
1308
   * @return Future that completes when closed
1309
   */
1310
  Future<Void> close();
1311
}
1312

1313
/**
1314
 * Datagram packet interface
1315
 */
1316
interface DatagramPacket {
1317
  /**
1318
   * Get sender address
1319
   * @return Sender address
1320
   */
1321
  SocketAddress sender();
1322

1323
  /**
1324
   * Get packet data
1325
   * @return Packet data buffer
1326
   */
1327
  Buffer data();
1328
}
1329

1330
/**
1331
 * Create DNS client
1332
 * @return DnsClient instance
1333
 */
1334
DnsClient createDnsClient();
1335

1336
/**
1337
 * Create DNS client with options
1338
 * @param options DNS client options
1339
 * @return DnsClient instance
1340
 */
1341
DnsClient createDnsClient(DnsClientOptions options);
1342

1343
/**
1344
 * DNS client interface
1345
 */
1346
interface DnsClient {
1347
  /**
1348
   * Resolve hostname
1349
   * @param name Hostname to resolve
1350
   * @return Future that completes with addresses
1351
   */
1352
  Future<List<String>> resolve(String name);
1353

1354
  /**
1355
   * Resolve A record
1356
   * @param name Hostname to resolve
1357
   * @return Future that completes with IPv4 addresses
1358
   */
1359
  Future<List<String>> resolveA(String name);
1360

1361
  /**
1362
   * Resolve AAAA record
1363
   * @param name Hostname to resolve
1364
   * @return Future that completes with IPv6 addresses
1365
   */
1366
  Future<List<String>> resolveAAAA(String name);
1367

1368
  /**
1369
   * Resolve CNAME record
1370
   * @param name Hostname to resolve
1371
   * @return Future that completes with canonical names
1372
   */
1373
  Future<List<String>> resolveCNAME(String name);
1374

1375
  /**
1376
   * Resolve MX record
1377
   * @param name Domain to resolve
1378
   * @return Future that completes with MX records
1379
   */
1380
  Future<List<MxRecord>> resolveMX(String name);
1381

1382
  /**
1383
   * Resolve TXT record
1384
   * @param name Domain to resolve
1385
   * @return Future that completes with TXT records
1386
   */
1387
  Future<List<String>> resolveTXT(String name);
1388

1389
  /**
1390
   * Resolve PTR record (reverse lookup)
1391
   * @param name IP address to resolve
1392
   * @return Future that completes with hostnames
1393
   */
1394
  Future<String> resolvePTR(String name);
1395

1396
  /**
1397
   * Resolve NS record
1398
   * @param name Domain to resolve
1399
   * @return Future that completes with name servers
1400
   */
1401
  Future<List<String>> resolveNS(String name);
1402

1403
  /**
1404
   * Resolve SRV record
1405
   * @param name Service name to resolve
1406
   * @return Future that completes with SRV records
1407
   */
1408
  Future<List<SrvRecord>> resolveSRV(String name);
1409

1410
  /**
1411
   * Reverse lookup IP address
1412
   * @param ipaddress IP address
1413
   * @return Future that completes with hostname
1414
   */
1415
  Future<String> reverseLookup(String ipaddress);
1416

1417
  /**
1418
   * Close DNS client
1419
   * @return Future that completes when closed
1420
   */
1421
  Future<Void> close();
1422
}
1423
```
1424

1425
### Multi-valued Maps
1426

1427
Case-insensitive multi-valued maps used for HTTP headers and parameters.
1428

1429
```java { .api }
1430
/**
1431
 * Multi-valued map interface
1432
 */
1433
interface MultiMap extends Iterable<Map.Entry<String, String>> {
1434
  /**
1435
   * Get first value for name
1436
   * @param name Header name
1437
   * @return First value or null
1438
   */
1439
  String get(String name);
1440

1441
  /**
1442
   * Get all values for name
1443
   * @param name Header name
1444
   * @return List of values
1445
   */
1446
  List<String> getAll(String name);
1447

1448
  /**
1449
   * Check if contains name
1450
   * @param name Header name
1451
   * @return true if contains
1452
   */
1453
  boolean contains(String name);
1454

1455
  /**
1456
   * Check if empty
1457
   * @return true if empty
1458
   */
1459
  boolean isEmpty();
1460

1461
  /**
1462
   * Get all names
1463
   * @return Set of names
1464
   */
1465
  Set<String> names();
1466

1467
  /**
1468
   * Add name-value pair
1469
   * @param name Header name
1470
   * @param value Header value
1471
   * @return this for chaining
1472
   */
1473
  MultiMap add(String name, String value);
1474

1475
  /**
1476
   * Add name with multiple values
1477
   * @param name Header name
1478
   * @param values Header values
1479
   * @return this for chaining
1480
   */
1481
  MultiMap add(String name, Iterable<String> values);
1482

1483
  /**
1484
   * Add all from another MultiMap
1485
   * @param map Source MultiMap
1486
   * @return this for chaining
1487
   */
1488
  MultiMap addAll(MultiMap map);
1489

1490
  /**
1491
   * Set name-value pair (replace existing)
1492
   * @param name Header name
1493
   * @param value Header value
1494
   * @return this for chaining
1495
   */
1496
  MultiMap set(String name, String value);
1497

1498
  /**
1499
   * Set name with multiple values
1500
   * @param name Header name
1501
   * @param values Header values
1502
   * @return this for chaining
1503
   */
1504
  MultiMap set(String name, Iterable<String> values);
1505

1506
  /**
1507
   * Set all from another MultiMap
1508
   * @param map Source MultiMap
1509
   * @return this for chaining
1510
   */
1511
  MultiMap setAll(MultiMap map);
1512

1513
  /**
1514
   * Remove all values for name
1515
   * @param name Header name
1516
   * @return this for chaining
1517
   */
1518
  MultiMap remove(String name);
1519

1520
  /**
1521
   * Clear all entries
1522
   * @return this for chaining
1523
   */
1524
  MultiMap clear();
1525

1526
  /**
1527
   * Get number of entries
1528
   * @return Entry count
1529
   */
1530
  int size();
1531

1532
  /**
1533
   * Create case-insensitive MultiMap
1534
   * @return Empty MultiMap
1535
   */
1536
  static MultiMap caseInsensitiveMultiMap();
1537
}
1538
```
1539

1540
## Usage Examples
1541

1542
**JSON Processing:**
1543

1544
```java
1545
import io.vertx.core.json.JsonObject;
1546
import io.vertx.core.json.JsonArray;
1547

1548
// Create and manipulate JSON objects
1549
JsonObject user = new JsonObject()
1550
  .put("id", 123)
1551
  .put("name", "John Doe")
1552
  .put("email", "john@example.com")
1553
  .put("active", true);
1554

1555
// Read values
1556
String name = user.getString("name");
1557
Integer id = user.getInteger("id");
1558
Boolean active = user.getBoolean("active");
1559

1560
// Nested objects
1561
JsonObject address = new JsonObject()
1562
  .put("street", "123 Main St")
1563
  .put("city", "Anytown");
1564
user.put("address", address);
1565

1566
// JSON arrays
1567
JsonArray hobbies = new JsonArray()
1568
  .add("reading")
1569
  .add("swimming")
1570
  .add("coding");
1571
user.put("hobbies", hobbies);
1572

1573
// Encoding/decoding
1574
String json = user.encode();
1575
JsonObject parsed = new JsonObject(json);
1576

1577
// POJO mapping
1578
User userPojo = user.mapTo(User.class);
1579
JsonObject fromPojo = JsonObject.mapFrom(userPojo);
1580
```
1581

1582
**Buffer Operations:**
1583

1584
```java
1585
import io.vertx.core.buffer.Buffer;
1586

1587
// Create and manipulate buffers
1588
Buffer buffer = Buffer.buffer();
1589
buffer.appendString("Hello ")
1590
      .appendString("World")
1591
      .appendByte((byte) '!')
1592
      .appendInt(42);
1593

1594
// Read data
1595
String text = buffer.getString(0, 11); // "Hello World"
1596
byte exclamation = buffer.getByte(11);
1597
int number = buffer.getInt(12);
1598

1599
// Binary data
1600
Buffer binaryData = Buffer.buffer()
1601
  .appendInt(0x12345678)
1602
  .appendLong(0x123456789ABCDEF0L)
1603
  .appendFloat(3.14f)
1604
  .appendDouble(2.718);
1605

1606
// Convert to/from JSON
1607
JsonObject obj = new JsonObject().put("message", "hello");
1608
Buffer jsonBuffer = Buffer.buffer(obj.encode());
1609
JsonObject parsed = jsonBuffer.toJsonObject();
1610
```
1611

1612
**Stream Processing:**
1613

1614
```java
1615
import io.vertx.core.streams.ReadStream;
1616
import io.vertx.core.streams.WriteStream;
1617
import io.vertx.core.streams.Pump;
1618

1619
// Stream data processing
1620
ReadStream<Buffer> source = getDataSource();
1621
WriteStream<Buffer> destination = getDataDestination();
1622

1623
// Simple piping
1624
source.pipeTo(destination).onSuccess(v -> {
1625
  System.out.println("Piping completed");
1626
});
1627

1628
// Manual pump with control
1629
Pump pump = Pump.pump(source, destination);
1630
pump.start();
1631

1632
// Monitor progress
1633
vertx.setPeriodic(1000, id -> {
1634
  System.out.println("Pumped bytes: " + pump.numberPumped());
1635
});
1636

1637
// Back-pressure handling
1638
destination.drainHandler(v -> {
1639
  System.out.println("Write queue drained, resuming");
1640
  source.resume();
1641
});
1642

1643
if (destination.writeQueueFull()) {
1644
  source.pause();
1645
}
1646
```
1647

1648
**Shared Data Usage:**
1649

1650
```java
1651
import io.vertx.core.shareddata.SharedData;
1652
import io.vertx.core.shareddata.LocalMap;
1653

1654
SharedData sharedData = vertx.sharedData();
1655

1656
// Local map within Vert.x instance
1657
LocalMap<String, String> localMap = sharedData.getLocalMap("config");
1658
localMap.put("database.url", "jdbc:postgresql://localhost/mydb");
1659
localMap.put("cache.size", "1000");
1660

1661
String dbUrl = localMap.get("database.url");
1662

1663
// Cluster-wide async map
1664
sharedData.<String, JsonObject>getAsyncMap("users").onSuccess(map -> {
1665
  JsonObject user = new JsonObject()
1666
    .put("name", "Alice")
1667
    .put("age", 30);
1668
  
1669
  map.put("user123", user).onSuccess(v -> {
1670
    System.out.println("User stored in cluster");
1671
    
1672
    map.get("user123").onSuccess(retrieved -> {
1673
      System.out.println("Retrieved: " + retrieved.encode());
1674
    });
1675
  });
1676
});
1677

1678
// Distributed counter
1679
sharedData.getCounter("page-views").onSuccess(counter -> {
1680
  counter.incrementAndGet().onSuccess(count -> {
1681
    System.out.println("Page views: " + count);
1682
  });
1683
});
1684

1685
// Distributed lock
1686
sharedData.getLock("critical-section").onSuccess(lock -> {
1687
  System.out.println("Acquired lock, performing critical operation");
1688
  
1689
  // Perform critical work
1690
  performCriticalOperation();
1691
  
1692
  // Release lock
1693
  lock.release().onSuccess(v -> {
1694
    System.out.println("Lock released");
1695
  });
1696
});
1697
```
1698

1699
**UDP and DNS Operations:**
1700

1701
```java
1702
// UDP datagram socket
1703
DatagramSocket socket = vertx.createDatagramSocket();
1704

1705
socket.handler(packet -> {
1706
  System.out.println("Received packet from " + packet.sender());
1707
  System.out.println("Data: " + packet.data().toString());
1708
});
1709

1710
socket.listen(1234, "localhost").onSuccess(sock -> {
1711
  System.out.println("UDP socket listening on port 1234");
1712
  
1713
  // Send response
1714
  Buffer response = Buffer.buffer("Hello UDP Client!");
1715
  socket.send(response, 1235, "localhost");
1716
});
1717

1718
// DNS resolution
1719
DnsClient dnsClient = vertx.createDnsClient();
1720

1721
dnsClient.resolveA("example.com").onSuccess(addresses -> {
1722
  System.out.println("IPv4 addresses for example.com:");
1723
  addresses.forEach(System.out::println);
1724
});
1725

1726
dnsClient.resolveMX("example.com").onSuccess(mxRecords -> {
1727
  System.out.println("MX records for example.com:");
1728
  mxRecords.forEach(record -> {
1729
    System.out.println("Priority: " + record.priority() + 
1730
                      ", Name: " + record.name());
1731
  });
1732
});
1733
```