Skip to main content


ActiveJ FS is a lightweight asynchronous Java library that provides a tiny abstraction on top of common file operations. It provides methods for uploading, downloading, appending, listing, copying, moving, deleting and other methods for working with local, remote or distributed storages.

Why ActiveJ FS?

  • Asynchronous file system
  • Lightweight by design
  • Intuitive API consisting of well-known file operations
  • Supports atomic file uploads
  • Supports client-server communication using the custom binary protocol as well as the HTTP protocol
  • Can be launched as a distributed file system cluster

Where ActiveJ FS can be used?

There are several ActiveJ FS implementations:

  • Local ActiveJ FS is designed to work with file systems located on a single machine. Ideal for implementing local file storage for your application, such as database storage, data backup storage, local logs storage, etc.
  • Client/Server implementations for working with files that are stored remotely. This implementation supports two protocols:
    • A custom binary protocol based on TCP with zero overhead. Similar to FTP, but simpler and more efficient.
    • HTTP protocol that allows you to define a REST API. It also provides third-party clients, such as browsers, with access to remote ActiveJ FS servers.
  • ActiveJ FS Cluster is designed for distributed big data workloads. It is optimized to handle large immutable datasets or append-only files. Cluster ActiveJ FS has been intentionally made not POSIX-compilant and works only with immutable files. This makes the entire system simple, lightweight, and resilient to server or network failures. Moreover, this approach avoids the overhead of master-slave architecture and synchronization of mutable files. With ActiveJ FS you can create distributed, scalable P2P file systems with built-in support for rebalancing, fault tolerance, and scalability.
  • ActiveJ FS Adapters allow you to filter, mount, transform file names, add and remove prefixes, subdirectories, etc.

Streaming file access

upload() and download() operations use the CSP module, so files are uploaded/downloaded using asynchronous data streams.

String filename = "hello.txt";

Eventloop eventloop = Eventloop.builder().withCurrentThread().build();
Executor executor = Executors.newSingleThreadExecutor();

FileSystem fileSystem = FileSystem.create(eventloop, executor, Paths.get("/tmp/file-storage"));

.then(() -> ChannelSupplier.of(ByteBufStrings.wrapAscii("Hello World"))
.then(() ->
.map(supplier -> -> buf.asString(StandardCharsets.US_ASCII)))
.then(supplier -> supplier.streamTo(ChannelConsumer.ofConsumer(System.out::println)));;

Add ActiveJ FS to your project

You can add ActiveJ FS to your project by importing its Maven repository. These docs cover the most recent release of ActiveJ FS v6.0-beta2 (see on Github or Maven).