Bootstrapping a Java File System

So what does file system mean to you? Most think of file systems as directories and files accessed via your computer: local disk, remotely shared via NFS or SMB, thumb drives, something else. Sufficient for those who require basic file access, nothing more nothing less.

That perspective of file systems is too limited: VCS repositories, archive files (zip/jar), remote systems can be viewed as file systems, potentially accessed via the same APIs used to for local file access while still maintaining security and data requirements. Or how about a file system which automatically transcodes videos to different formats or extracts audio metadata for vector searches? Wouldn’t it be cool to use standard APIs rather than create something customized? Definitely!

Java provides a file system abstraction that enables solution-specific implementations accessed via the APIs used for traditional disk-backed file systems. Potentially overwhelming at first blush, getting the basics bootstrapped is remarkably straight-forward, with the implementation effort dependent on what your requirements need.

In this post, I’ll explain the basics of Java’s file systems to get you started. I created a starter project which is a bare-bones Java file system with two operation implemented (create directory and exists) are used via a demo class. If you’re a glutton for punishment, you can also clone/fork my neo4j-filesystem project which is an almost fully-functioning file system minus some edge cases.

History of File Systems Within Java

A short, flippant, perhaps not even completely correct history of the Java APIs for file systems. Not required reading, jump ahead if you’re getting antsy to start actual work!

The initial release of Java 1.0 provided access to the operating system’s file system via java.io.File, a simple implementation built on blocking I/O and single-threaded operations. Usable but limited, adequate performance but definitely not scalable. Acceptable for a small target audience, perhaps viewed as more proof-of-concept than anything; doubtful that James Gosling or anyone at Sun envisioned the boheimeth Java has since become.

Java continued growth and inroads in software engineering lead to its First Age of (I/O) Enlightenment: Java 1.4 introduced Java NIO, providing better abstractions, non-blocking I/O, multi-threaded operations, and more. Performance improved. And there was some rejoicing (maybe).

However, Java NIO was difficult to use (or so I’ve read), leading to the Second Age of (I/O) Enlightenment: Java 1.7 introduced Java NIO.2 to address perceived usability issues and implemented a File System abstraction that allowed customized file systems. No longer restricted to OS perspective, one can now implement a file system based on your specific requirements . The crown jewels: java.nio.file.Files which delegates operations to whichever file system based on a file/directory Path. And there was more rejoicing.

Prior to a recent project, I had not used (actually avoided) Java NIO and did not understand its value. Yes, java.nio.file.Files simplifies repetitive, templated I/O operations, nothing more, nothing less. I had a superficial understanding at best, legacy java.io.File was sufficient … until it wasn’t.

Most important are the Java NIO.2 changes which allow solutions to implement their file systems based on their requirements that seamlessly integrate with the JVM. Third-party or customized implementations are no longer necessary which should greatly simplifying many aspects of your solution.

Before You Start

Implementing your first custom file system will not be quick, straight-forward nor painless, so I recommend you consider the following to create a high-level, conceptual design before you start coding. The design is not immutable; in fact, I fully expect course corrections and refinements as you get deeper. Even an in-your-head design makes future decisions easier to contextualize and implement. You’ll thank me later!

NOTE: Java is POSIX-biased – unsurprising considering its Sun Solaris origins – and therefore so is its file system abstraction: path separator, owner user/groups, access modes, file permissions, file types, etc. Moving away from POSIX likely means working around, rather than with, Java’s file systems. Possible? Yes. Recommended? No.. You’ve been warned.

URI Design

URIs have two important purposes within Java file systems:

• the URI identifies the specific file system with which to work;
• the URI identifies a specific file or directory within the specified file system.

The URI is the core concept upon which a Java file system is built, and understanding its construction and purpose is required.

A URI has four components that are relevant for file systems:

• scheme: Uniquely identifies to which file system implementation Java should delegate operations. Required and must be unique among all file systems present in the JVM. [The exception is the JVM’s [default file system](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/nio/file/FileSystems.html#getDefault()), typically file:// for OS local storage.].
• user:password: Optional username/password for user authentication, such as authenticating to remote system before operations are executed. NOTE: passwords in cleartext are not secure. Use at your own risk.
• host: Optional. Host names generally identify the remote system to connect to, but also are used to partition the file system for security or data management purposes. For example, each user or customer may have a dedicated partition.
• /path/to/file: A fully-qualified or relative path to identify a specific directory or file. The most common path separator is a slash; using other special characters is possible (somewhat) but introduces other problems. If you require directories, stick with slashed. Again, you have been warned.

URI query strings may be used for unique requirements but generally are not necessary.

File Tree Management

You need to track the directories and files comprising your file tree, but where? Relational and document-based NoSQL database systems are obvious choices, your requirements may lead you elsewhere.

What data or properties are stored with each entry? Definitely directory/file name and parent/child info. Security? Owners? Timestamps? Encryption key? Something else? Consider carefully what you include and what you don’t.

Managing a file tree is challenging: operating systems structures – e.g., *nix iNodes or NTFS‘s master file table in Windows– have evolved to be highly optimized and efficient. Your challenge providing efficient access and navigation while maintaining your organization’s non-functional requirements. I’ve experience customized file systems struggle to provide both efficient tree management (write) and navigation (read), leading to on-going hacks to fix the performance problem of the day. File trees are simple graphs, but arbitrary directory depth and number of files/directories within a directory are problematic.

Binary Storage

Where does your file system store the actual file, the raw bytes representing the file uploaded to your file system? Storing locally is feasible, though counter-intuitive; storing files externally is more likely, such as AWS S3, Azure Blob Storage, Google Cloud Storage, even a database which supports blobs. Each approach has different functionality, limitations, costs, so choose wisely for the sake of your implementation.

Your solution may require functionality not always available to your file storage approach. Must files be automatically encrypted/unencrypted? Do you need file’s metadata to be extracted and stored separately? Can users request previous versions of a file? Anything else?

File storage is as simple or as complicated as defined by your requirements.

The Bare Minimum

Four components must be present to bootstrap your Java file system. Clone the starter file system repository if you want to follow along in your IDE: after reviewing you’ll understanding how little magic is actually involved.

• Implement Path: Represents a file system’s directory or file based on its URI representation, created either by direct calls to FileSystem.getPath() or indirectly via Path.of(). Implement the methods:
  • Constructor to which a generic Path or path as a string are passed in; the associated FileSystem instance may also be useful.
  • getFileName()
  • getParent()
  • subpath()
  • toUri()

• Extend FileSystem: An instance of a file system, usually identified by a truncated URI (e.g., scheme and hostname). For example, a zip file has its own ZipFileSystem instance with which to interact with the zip file via the Java file system. Implement the methods:
  • Constructor which accepts a FileSystemProvider
  • getPath()
  • provider()

• Extend [FileSystemProvider](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/nio/file/FileSystem.html#provider()): The power engine of a Java file system, as the functionality implemented determines what/how your file system operates. A singleton is registered with the JVM at startup. Once registered, operations for the defined scheme are forwarded to the FileSystemProvider instance. Implement the methods:
  • getScheme()
  • newFileSystem()
  • getFileSystem()
  • getPath()

• Register FileSystemProvider: Create the resource file META-INFO/services/java.nio.file.spr.FileSystemProvider. The file must contain the fully-qualified class name for your file system provider.

That’s it. Really. Review the starter project. You now have a working Java file system which does absolutely nothing. At this point, you are ready to implement the functionality required by your custom file system. So far, so good!

Next Steps

Implement, implement, implement. Now the real ~fun~ work begins. Some suggestions:

• Database Layer: Managing the file tree is fundamental to every operation of your file system, so you’ll need at least the basics in place immediately. Define the entries supported – directories, files, maybe symbolic links – with the necessary metadata. Implement the CRUD operations. Emulate path navigation to ensure arbitrary depth doesn’t cause problems.
• My First Operations: I started with basic directory operations that don’t require storing files: createDirectory(), exists(), delete(), deleteIfExists(). Test by creating FileSystem and making calls to Files. Start to get feel for how things fit together.
• File Storage: After directories work comes files, so you are unable to avoid figuring your file management strategy. Early on, local disk may actually be sufficient to allow you to proceed. Define a robust interface that allows additional implementations without require larger rework. A bit-bucket file storage implement provides for large-scale file tree work when actual files aren’t required.
• My First File Operations: Implement FileSystem.newInputStream() and FileSystem.newOutputStream() to start creating files using Files.createFile() or Files.copy(). Now you’ve got something vaguely useful.
• Local File System Testing: My file system is intended to be a fully-functioning POSIX-based file system, so dug deep into code for working with a local file for better understanding: method return values, exceptions thrown, edge cases, enum interpretation, how attributes are implemented, etc. Create demos/tests using Files and see what works, what doesn’t, debug, refactor, etc., etc.
• Patience: Frustrating initially, rewarding later. The abstraction makes some things much more difficult than I expected/wanted, but little by little the pieces start fitting together. This is not an afternoon’s work!

Final Thoughts

Now with a better understanding, I have additional ideas on unique ways to leverage Java file systems. Could I have asked AI to do this for me? Sure, but what fun would that have been! Creating a custom Java file system was both geeky and fun, perhaps more fun than I have had in a while, plus I have a deeper understanding of a core Java concept. Score!

References Links

• https://github.com/scsosna99/java-file-system-starter
• https://github.com/scsosna99/neo4j-filesystem
• https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/nio/file/package-summary.html
• https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/nio/file/spi/FileSystemProvider.html

Image Credits

• “James Gosling 2008” by Peter Campbell is licensed under CC BY-SA 4.0.
• “URI Format” generated by Claude.AI based on my prompts.
• “File Tree” © 2026 Scott C Sosna
• “NetApp FAS270” by mondopiccolo is licensed under CC BY-NC 2.0.
• “Code Snippets” © 2026 Scott C Sosna

• Tutorials
• Use Cases

Scott Sosna

Author

Scott's career has spanned multiple technical epochs, playing many roles in many business domains. Starting with Apple Basic, Scott's started with Java 1.2 and since has almost exclusively worked in the JVM world. He speaks at conferences and loves sharing insights and experiences with attendees.