0
# File System
1

2
Comprehensive asynchronous file system operations including file I/O, directory management, file properties, and file watching capabilities.
3

4
## Capabilities
5

6
### File System Access
7

8
Get the file system instance for performing file operations.
9

10
```java { .api }
11
/**
12
 * Get the file system instance
13
 * @return FileSystem instance
14
 */
15
FileSystem fileSystem();
16

17
/**
18
 * File System interface for asynchronous file operations
19
 */
20
interface FileSystem {
21
  /**
22
   * Read entire file into buffer
23
   * @param path File path to read
24
   * @return Future that completes with file contents
25
   */
26
  Future<Buffer> readFile(String path);
27

28
  /**
29
   * Write buffer to file
30
   * @param path File path to write
31
   * @param data Data to write
32
   * @return Future that completes when written
33
   */
34
  Future<Void> writeFile(String path, Buffer data);
35

36
  /**
37
   * Copy a file
38
   * @param from Source file path
39
   * @param to Destination file path
40
   * @return Future that completes when copied
41
   */
42
  Future<Void> copy(String from, String to);
43

44
  /**
45
   * Copy a file with options
46
   * @param from Source file path
47
   * @param to Destination file path
48
   * @param options Copy options
49
   * @return Future that completes when copied
50
   */
51
  Future<Void> copy(String from, String to, CopyOptions options);
52

53
  /**
54
   * Copy recursively
55
   * @param from Source directory path
56
   * @param to Destination directory path
57
   * @return Future that completes when copied
58
   */
59
  Future<Void> copyRecursive(String from, String to, boolean recursive);
60

61
  /**
62
   * Move/rename a file
63
   * @param from Source file path
64
   * @param to Destination file path
65
   * @return Future that completes when moved
66
   */
67
  Future<Void> move(String from, String to);
68

69
  /**
70
   * Move with options
71
   * @param from Source file path
72
   * @param to Destination file path
73
   * @param options Copy options
74
   * @return Future that completes when moved
75
   */
76
  Future<Void> move(String from, String to, CopyOptions options);
77

78
  /**
79
   * Truncate a file
80
   * @param path File path
81
   * @param len New length
82
   * @return Future that completes when truncated
83
   */
84
  Future<Void> truncate(String path, long len);
85

86
  /**
87
   * Change file permissions
88
   * @param path File path
89
   * @param perms File permissions
90
   * @return Future that completes when changed
91
   */
92
  Future<Void> chmod(String path, String perms);
93

94
  /**
95
   * Change file permissions recursively
96
   * @param path Directory path
97
   * @param perms File permissions
98
   * @param dirPerms Directory permissions
99
   * @return Future that completes when changed
100
   */
101
  Future<Void> chmodRecursive(String path, String perms, String dirPerms);
102

103
  /**
104
   * Change file owner
105
   * @param path File path
106
   * @param user User name
107
   * @param group Group name
108
   * @return Future that completes when changed
109
   */
110
  Future<Void> chown(String path, String user, String group);
111

112
  /**
113
   * Get file properties
114
   * @param path File path
115
   * @return Future that completes with file properties
116
   */
117
  Future<FileProps> props(String path);
118

119
  /**
120
   * Get link properties (don't follow symlinks)
121
   * @param path File path
122
   * @return Future that completes with file properties
123
   */
124
  Future<FileProps> lprops(String path);
125

126
  /**
127
   * Create hard link
128
   * @param link Link path
129
   * @param existing Existing file path
130
   * @return Future that completes when created
131
   */
132
  Future<Void> link(String link, String existing);
133

134
  /**
135
   * Create symbolic link
136
   * @param link Link path
137
   * @param existing Existing file path
138
   * @return Future that completes when created
139
   */
140
  Future<Void> symlink(String link, String existing);
141

142
  /**
143
   * Delete/unlink a file
144
   * @param path File path
145
   * @return Future that completes when deleted
146
   */
147
  Future<Void> unlink(String path);
148

149
  /**
150
   * Read symbolic link
151
   * @param link Link path
152
   * @return Future that completes with link target
153
   */
154
  Future<String> readSymlink(String link);
155

156
  /**
157
   * Delete a file or directory
158
   * @param path File or directory path
159
   * @return Future that completes when deleted
160
   */
161
  Future<Void> delete(String path);
162

163
  /**
164
   * Delete recursively
165
   * @param path Directory path
166
   * @param recursive Whether to delete recursively
167
   * @return Future that completes when deleted
168
   */
169
  Future<Void> deleteRecursive(String path, boolean recursive);
170

171
  /**
172
   * Create directory
173
   * @param path Directory path
174
   * @return Future that completes when created
175
   */
176
  Future<Void> mkdir(String path);
177

178
  /**
179
   * Create directory with permissions
180
   * @param path Directory path
181
   * @param perms Directory permissions
182
   * @return Future that completes when created
183
   */
184
  Future<Void> mkdir(String path, String perms);
185

186
  /**
187
   * Create directories recursively
188
   * @param path Directory path
189
   * @return Future that completes when created
190
   */
191
  Future<Void> mkdirs(String path);
192

193
  /**
194
   * Create directories with permissions
195
   * @param path Directory path
196
   * @param perms Directory permissions
197
   * @return Future that completes when created
198
   */
199
  Future<Void> mkdirs(String path, String perms);
200

201
  /**
202
   * Read directory
203
   * @param path Directory path
204
   * @return Future that completes with list of files
205
   */
206
  Future<List<String>> readDir(String path);
207

208
  /**
209
   * Read directory with filter
210
   * @param path Directory path
211
   * @param filter Filename filter regex
212
   * @return Future that completes with filtered list of files
213
   */
214
  Future<List<String>> readDir(String path, String filter);
215

216
  /**
217
   * Open file for reading/writing
218
   * @param path File path
219
   * @param options Open options
220
   * @return Future that completes with AsyncFile
221
   */
222
  Future<AsyncFile> open(String path, OpenOptions options);
223

224
  /**
225
   * Create a new file
226
   * @param path File path
227
   * @return Future that completes when created
228
   */
229
  Future<Void> createFile(String path);
230

231
  /**
232
   * Create file with permissions
233
   * @param path File path
234
   * @param perms File permissions
235
   * @return Future that completes when created
236
   */
237
  Future<Void> createFile(String path, String perms);
238

239
  /**
240
   * Check if file exists
241
   * @param path File path
242
   * @return Future that completes with existence check
243
   */
244
  Future<Boolean> exists(String path);
245

246
  /**
247
   * Get file system properties
248
   * @param path Path to check
249
   * @return Future that completes with filesystem properties
250
   */
251
  Future<FileSystemProps> fsProps(String path);
252

253
  /**
254
   * Create temporary directory
255
   * @param prefix Directory name prefix
256
   * @return Future that completes with temp directory path
257
   */
258
  Future<String> createTempDirectory(String prefix);
259

260
  /**
261
   * Create temporary directory with attributes
262
   * @param prefix Directory name prefix
263
   * @param perms Directory permissions
264
   * @param dir Parent directory
265
   * @return Future that completes with temp directory path
266
   */
267
  Future<String> createTempDirectory(String prefix, String perms, String dir);
268

269
  /**
270
   * Create temporary file
271
   * @param prefix File name prefix
272
   * @param suffix File name suffix
273
   * @return Future that completes with temp file path
274
   */
275
  Future<String> createTempFile(String prefix, String suffix);
276

277
  /**
278
   * Create temporary file with attributes
279
   * @param prefix File name prefix
280
   * @param suffix File name suffix
281
   * @param perms File permissions
282
   * @param dir Parent directory
283
   * @return Future that completes with temp file path
284
   */
285
  Future<String> createTempFile(String prefix, String suffix, String perms, String dir);
286

287
  /**
288
   * Watch a file or directory for changes
289
   * @param path Path to watch
290
   * @return Future that completes with file watcher
291
   */
292
  Future<Watcher> watch(String path);
293
}
294
```
295

296
### Async File Operations
297

298
Handle files asynchronously with streaming support and precise positioning.
299

300
```java { .api }
301
/**
302
 * Asynchronous file handle for reading/writing
303
 */
304
interface AsyncFile extends ReadStream<Buffer>, WriteStream<Buffer> {
305
  /**
306
   * Close the file
307
   * @return Future that completes when closed
308
   */
309
  Future<Void> close();
310

311
  /**
312
   * Write buffer to file
313
   * @param buffer Data to write
314
   * @return Future that completes when written
315
   */
316
  Future<Void> write(Buffer buffer);
317

318
  /**
319
   * Write buffer at specific position
320
   * @param buffer Data to write
321
   * @param position Position to write at
322
   * @return Future that completes when written
323
   */
324
  Future<Void> write(Buffer buffer, long position);
325

326
  /**
327
   * Read from file into buffer
328
   * @param buffer Buffer to read into
329
   * @param offset Offset in buffer
330
   * @param position Position in file
331
   * @param length Number of bytes to read
332
   * @return Future that completes with buffer
333
   */
334
  Future<Buffer> read(Buffer buffer, int offset, long position, int length);
335

336
  /**
337
   * Flush data to storage
338
   * @return Future that completes when flushed
339
   */
340
  Future<Void> flush();
341

342
  /**
343
   * Set read position
344
   * @param readPos New read position
345
   * @return this for chaining
346
   */
347
  AsyncFile setReadPos(long readPos);
348

349
  /**
350
   * Set write position
351
   * @param writePos New write position
352
   * @return this for chaining
353
   */
354
  AsyncFile setWritePos(long writePos);
355

356
  /**
357
   * Get current read position
358
   * @return Read position
359
   */
360
  long getReadPos();
361

362
  /**
363
   * Get current write position
364
   * @return Write position
365
   */
366
  long getWritePos();
367

368
  /**
369
   * Get file size
370
   * @return Future that completes with file size
371
   */
372
  Future<Long> size();
373

374
  /**
375
   * Lock the file
376
   * @return Future that completes with file lock
377
   */
378
  Future<AsyncFileLock> lock();
379

380
  /**
381
   * Lock part of the file
382
   * @param position Start position
383
   * @param size Lock size
384
   * @param shared Whether lock is shared
385
   * @return Future that completes with file lock
386
   */
387
  Future<AsyncFileLock> lock(long position, long size, boolean shared);
388

389
  /**
390
   * Try to lock the file (non-blocking)
391
   * @return Future that completes with file lock or null
392
   */
393
  Future<AsyncFileLock> tryLock();
394

395
  /**
396
   * Try to lock part of the file (non-blocking)
397
   * @param position Start position
398
   * @param size Lock size
399
   * @param shared Whether lock is shared
400
   * @return Future that completes with file lock or null
401
   */
402
  Future<AsyncFileLock> tryLock(long position, long size, boolean shared);
403
}
404

405
/**
406
 * File lock for controlling access
407
 */
408
interface AsyncFileLock {
409
  /**
410
   * Get lock position
411
   * @return Lock position
412
   */
413
  long position();
414

415
  /**
416
   * Get lock size
417
   * @return Lock size
418
   */
419
  long size();
420

421
  /**
422
   * Check if lock is shared
423
   * @return true if shared
424
   */
425
  boolean isShared();
426

427
  /**
428
   * Check if lock is valid
429
   * @return true if valid
430
   */
431
  boolean isValid();
432

433
  /**
434
   * Release the lock
435
   * @return Future that completes when released
436
   */
437
  Future<Void> release();
438
}
439
```
440

441
### File Properties and Metadata
442

443
Access file system metadata and properties.
444

445
```java { .api }
446
/**
447
 * File properties interface
448
 */
449
interface FileProps {
450
  /**
451
   * Get creation time
452
   * @return Creation time
453
   */
454
  Instant creationTime();
455

456
  /**
457
   * Get last access time
458
   * @return Last access time
459
   */
460
  Instant lastAccessTime();
461

462
  /**
463
   * Get last modified time
464
   * @return Last modified time
465
   */
466
  Instant lastModifiedTime();
467

468
  /**
469
   * Check if directory
470
   * @return true if directory
471
   */
472
  boolean isDirectory();
473

474
  /**
475
   * Check if other (not regular file, directory, or symlink)
476
   * @return true if other
477
   */
478
  boolean isOther();
479

480
  /**
481
   * Check if regular file
482
   * @return true if regular file
483
   */
484
  boolean isRegularFile();
485

486
  /**
487
   * Check if symbolic link
488
   * @return true if symbolic link
489
   */
490
  boolean isSymbolicLink();
491

492
  /**
493
   * Get file size
494
   * @return File size in bytes
495
   */
496
  long size();
497

498
  /**
499
   * Get file permissions
500
   * @return File permissions string
501
   */
502
  String permissions();
503
}
504

505
/**
506
 * File system properties interface
507
 */
508
interface FileSystemProps {
509
  /**
510
   * Get total space
511
   * @return Total space in bytes
512
   */
513
  long totalSpace();
514

515
  /**
516
   * Get unallocated space
517
   * @return Unallocated space in bytes
518
   */
519
  long unallocatedSpace();
520

521
  /**
522
   * Get usable space
523
   * @return Usable space in bytes
524
   */
525
  long usableSpace();
526
}
527
```
528

529
### File Operations Configuration
530

531
Configure file operations with various options.
532

533
```java { .api }
534
/**
535
 * Options for opening files
536
 */
537
class OpenOptions {
538
  /**
539
   * Set read mode
540
   * @param read Whether to open for reading
541
   * @return this for chaining
542
   */
543
  OpenOptions setRead(boolean read);
544

545
  /**
546
   * Set write mode
547
   * @param write Whether to open for writing
548
   * @return this for chaining
549
   */
550
  OpenOptions setWrite(boolean write);
551

552
  /**
553
   * Set create mode
554
   * @param create Whether to create if doesn't exist
555
   * @return this for chaining
556
   */
557
  OpenOptions setCreate(boolean create);
558

559
  /**
560
   * Set create new mode
561
   * @param createNew Whether to create only if doesn't exist
562
   * @return this for chaining
563
   */
564
  OpenOptions setCreateNew(boolean createNew);
565

566
  /**
567
   * Set delete on close
568
   * @param deleteOnClose Whether to delete when closed
569
   * @return this for chaining
570
   */
571
  OpenOptions setDeleteOnClose(boolean deleteOnClose);
572

573
  /**
574
   * Set truncate existing
575
   * @param truncateExisting Whether to truncate if exists
576
   * @return this for chaining
577
   */
578
  OpenOptions setTruncateExisting(boolean truncateExisting);
579

580
  /**
581
   * Set sparse file
582
   * @param sparse Whether to create sparse file
583
   * @return this for chaining
584
   */
585
  OpenOptions setSparse(boolean sparse);
586

587
  /**
588
   * Set sync mode
589
   * @param sync Whether to sync data and metadata
590
   * @return this for chaining
591
   */
592
  OpenOptions setSync(boolean sync);
593

594
  /**
595
   * Set dsync mode
596
   * @param dsync Whether to sync data only
597
   * @return this for chaining
598
   */
599
  OpenOptions setDsync(boolean dsync);
600

601
  /**
602
   * Set file permissions
603
   * @param perms File permissions
604
   * @return this for chaining
605
   */
606
  OpenOptions setPerms(String perms);
607
}
608

609
/**
610
 * Options for copying files
611
 */
612
class CopyOptions {
613
  /**
614
   * Set replace existing
615
   * @param replaceExisting Whether to replace existing files
616
   * @return this for chaining
617
   */
618
  CopyOptions setReplaceExisting(boolean replaceExisting);
619

620
  /**
621
   * Set copy attributes
622
   * @param copyAttributes Whether to copy file attributes
623
   * @return this for chaining
624
   */
625
  CopyOptions setCopyAttributes(boolean copyAttributes);
626

627
  /**
628
   * Set no follow links
629
   * @param nofollowLinks Whether to not follow symbolic links
630
   * @return this for chaining
631
   */
632
  CopyOptions setNofollowLinks(boolean nofollowLinks);
633

634
  /**
635
   * Set atomic move
636
   * @param atomicMove Whether move should be atomic
637
   * @return this for chaining
638
   */
639
  CopyOptions setAtomicMove(boolean atomicMove);
640
}
641

642
/**
643
 * File system configuration options
644
 */
645
class FileSystemOptions {
646
  FileSystemOptions setClassPathResolvingEnabled(boolean classPathResolvingEnabled);
647
  FileSystemOptions setFileCachingEnabled(boolean fileCachingEnabled);
648
}
649
```
650

651
### File Watching
652

653
Watch files and directories for changes.
654

655
```java { .api }
656
/**
657
 * File watcher for monitoring changes
658
 */
659
interface Watcher {
660
  /**
661
   * Get the watched path
662
   * @return Watched path
663
   */
664
  String path();
665

666
  /**
667
   * Set event handler
668
   * @param handler Handler for file events
669
   * @return this for chaining
670
   */
671
  Watcher handler(Handler<WatchEvent> handler);
672

673
  /**
674
   * Set exception handler
675
   * @param handler Exception handler
676
   * @return this for chaining
677
   */
678
  Watcher exceptionHandler(Handler<Throwable> handler);
679

680
  /**
681
   * Close the watcher
682
   * @return Future that completes when closed
683
   */
684
  Future<Void> close();
685
}
686

687
/**
688
 * File watch event
689
 */
690
interface WatchEvent {
691
  /**
692
   * Get event type
693
   * @return Event type
694
   */
695
  WatchEventType type();
696

697
  /**
698
   * Get file path
699
   * @return File path
700
   */
701
  String path();
702
}
703

704
/**
705
 * Types of watch events
706
 */
707
enum WatchEventType {
708
  CREATE,   // File created
709
  MODIFY,   // File modified
710
  DELETE    // File deleted
711
}
712
```
713

714
### Exception Handling
715

716
File system specific exceptions.
717

718
```java { .api }
719
/**
720
 * Exception for file system operation failures
721
 */
722
class FileSystemException extends VertxException {
723
  public FileSystemException(String message);
724
  public FileSystemException(String message, Throwable cause);
725
}
726
```
727

728
## Usage Examples
729

730
**Basic File Operations:**
731

732
```java
733
import io.vertx.core.file.FileSystem;
734
import io.vertx.core.buffer.Buffer;
735

736
FileSystem fs = vertx.fileSystem();
737

738
// Read file
739
fs.readFile("config.json").onSuccess(buffer -> {
740
  System.out.println("File contents: " + buffer.toString());
741
}).onFailure(err -> {
742
  System.err.println("Failed to read file: " + err.getMessage());
743
});
744

745
// Write file
746
Buffer data = Buffer.buffer("Hello World!");
747
fs.writeFile("output.txt", data).onSuccess(v -> {
748
  System.out.println("File written successfully");
749
});
750

751
// Copy file
752
fs.copy("source.txt", "destination.txt").onSuccess(v -> {
753
  System.out.println("File copied");
754
});
755

756
// Check if file exists
757
fs.exists("somefile.txt").onSuccess(exists -> {
758
  if (exists) {
759
    System.out.println("File exists");
760
  } else {
761
    System.out.println("File does not exist");
762
  }
763
});
764
```
765

766
**Directory Operations:**
767

768
```java
769
// Create directory
770
fs.mkdir("newdir").onSuccess(v -> {
771
  System.out.println("Directory created");
772
});
773

774
// Create nested directories
775
fs.mkdirs("path/to/nested/dir").onSuccess(v -> {
776
  System.out.println("Nested directories created");
777
});
778

779
// Read directory contents
780
fs.readDir("mydir").onSuccess(files -> {
781
  System.out.println("Directory contents:");
782
  files.forEach(System.out::println);
783
});
784

785
// Read directory with filter
786
fs.readDir("logs", ".*\\.log").onSuccess(logFiles -> {
787
  System.out.println("Log files:");
788
  logFiles.forEach(System.out::println);
789
});
790

791
// Delete directory recursively
792
fs.deleteRecursive("olddir", true).onSuccess(v -> {
793
  System.out.println("Directory deleted recursively");
794
});
795
```
796

797
**Async File Handling:**
798

799
```java
800
import io.vertx.core.file.AsyncFile;
801
import io.vertx.core.file.OpenOptions;
802

803
OpenOptions options = new OpenOptions()
804
  .setRead(true)
805
  .setWrite(true)
806
  .setCreate(true);
807

808
fs.open("data.bin", options).onSuccess(file -> {
809
  // Write data at specific position
810
  Buffer data = Buffer.buffer("Hello");
811
  file.write(data, 0).onSuccess(v -> {
812
    System.out.println("Data written at position 0");
813
    
814
    // Read data from specific position
815
    Buffer readBuffer = Buffer.buffer(5);
816
    file.read(readBuffer, 0, 0, 5).onSuccess(buffer -> {
817
      System.out.println("Read: " + buffer.toString());
818
      
819
      // Close file
820
      file.close();
821
    });
822
  });
823
});
824

825
// Stream processing with async file
826
fs.open("largefile.dat", new OpenOptions().setRead(true))
827
  .onSuccess(file -> {
828
    file.handler(buffer -> {
829
      // Process each chunk
830
      processChunk(buffer);
831
    });
832
    
833
    file.endHandler(v -> {
834
      System.out.println("File reading completed");
835
      file.close();
836
    });
837
  });
838
```
839

840
**File Properties and Metadata:**
841

842
```java
843
// Get file properties
844
fs.props("myfile.txt").onSuccess(props -> {
845
  System.out.println("File size: " + props.size());
846
  System.out.println("Is directory: " + props.isDirectory());
847
  System.out.println("Last modified: " + props.lastModifiedTime());
848
  System.out.println("Permissions: " + props.permissions());
849
});
850

851
// Get filesystem properties
852
fs.fsProps("/").onSuccess(fsProps -> {
853
  System.out.println("Total space: " + fsProps.totalSpace());
854
  System.out.println("Usable space: " + fsProps.usableSpace());
855
  System.out.println("Unallocated space: " + fsProps.unallocatedSpace());
856
});
857

858
// Change file permissions
859
fs.chmod("script.sh", "rwxr-xr-x").onSuccess(v -> {
860
  System.out.println("Permissions changed");
861
});
862
```
863

864
**File Watching:**
865

866
```java
867
import io.vertx.core.file.WatchEvent;
868
import io.vertx.core.file.WatchEventType;
869

870
fs.watch("watchdir").onSuccess(watcher -> {
871
  watcher.handler(event -> {
872
    WatchEventType type = event.type();
873
    String path = event.path();
874
    
875
    switch (type) {
876
      case CREATE:
877
        System.out.println("File created: " + path);
878
        break;
879
      case MODIFY:
880
        System.out.println("File modified: " + path);
881
        break;
882
      case DELETE:
883
        System.out.println("File deleted: " + path);
884
        break;
885
    }
886
  });
887
  
888
  watcher.exceptionHandler(err -> {
889
    System.err.println("Watcher error: " + err.getMessage());
890
  });
891
  
892
  // Stop watching after 30 seconds
893
  vertx.setTimer(30000, id -> {
894
    watcher.close().onSuccess(v -> {
895
      System.out.println("Watcher closed");
896
    });
897
  });
898
});
899
```
900

901
**File Locking:**
902

903
```java
904
fs.open("shared.dat", new OpenOptions().setWrite(true).setRead(true))
905
  .onSuccess(file -> {
906
    // Lock entire file exclusively
907
    file.lock().onSuccess(lock -> {
908
      System.out.println("File locked exclusively");
909
      
910
      // Perform operations on locked file
911
      file.write(Buffer.buffer("Exclusive data")).onSuccess(v -> {
912
        // Release lock
913
        lock.release().onSuccess(released -> {
914
          System.out.println("Lock released");
915
          file.close();
916
        });
917
      });
918
    });
919
  });
920

921
// Try to acquire shared lock on part of file
922
fs.open("database.dat", new OpenOptions().setRead(true))
923
  .onSuccess(file -> {
924
    file.tryLock(1000, 500, true).onSuccess(lock -> {
925
      if (lock != null) {
926
        System.out.println("Acquired shared lock on bytes 1000-1500");
927
        // Use the locked region
928
        lock.release();
929
      } else {
930
        System.out.println("Could not acquire lock");
931
      }
932
      file.close();
933
    });
934
  });
935
```