Basics

Note: This part of the guide is structured like a "walkthrough". If you would like a more direct to-the-point guide please see the summary section of the wiki.

---

Let's start with the root of FS4J: The FileSystem interface.

The FileSystem is where all file I/O will originate from. It is where you open, read, write, delete, and create your files and folders. It is also where you decide what folders and files are accessible to the user, and which ones are not. Let's have a look at the basic steps to setting it up.

First things first, let's pretend our filetree looks like this:

assets/
   names.txt
   archive.zip/
      textures/
         brass.txt
   textures/
      grass.png
      sand.png
      bark.png
   sounds/
      nature.ogg
      machines.ogg
output/
   textures/

Now let's create our FileSystem:

// Whatever FileSystem implementation you want to use.
// We are using the java.nio.* FileSystem implementation that comes with FS4J.
NIOFileSystem fs = new NIOFileSystem(); 

Alright, that was easy. Let's try to open a file:

// Open sand.png for reading. If the file could not be opened, throw a NullPointerException.
FSFile sandTexture = fs.open("assets/textures/sand.png", FileAccessType.READ).orElseThrow(NullPointerException::new);
byte[] bytes = sandTexture.readBytes();

Uh oh! NullPointerException! We forgot to tell the FileSystem that assets/textures/ is okay to access!

// We specify the folder the file is in, not the file itself.
fs.addToSearchPath("assets/", FileLocation.EXTERNAL); // or FileLocation.INTERNAL if the file is in the .jar

We can now open the file again, and it should open just fine and we can read the bytes from the file. The above also made every other file and folder in the assets/ folder accessible.

// We DON'T prefix with assets/
FSFile sandTexture = fs.open("textures/sand.png", FileAccessType.READ).orElseThrow(NullPointerException::new);
FSFile grassTexture = fs.open("textures/grass.png", FileAccessType.READ).orElseThrow(NullPointerException::new);
FSFile barkTexture = fs.open("textures/bark.png", FileAccessType.READ).orElseThrow(NullPointerException::new);

Okay, cool. Now let's try to create a new texture in the assets/textures folder:

FSFile iron = fs.createFile("textures/iron.png").orElseThrow(NullPointerException::new);

Uh oh, NullPointerException again! But why? We already added assets/textures to our search path! Well that's because the read path (a.k.a. the search path) is not the same as the write directory! This is to ensure that the user cannot modify any files we provide. So to create a file we simply first have to specify where we want to create all files. There can only be one write directory at a time.

boolean success = fs.setWriteDirectory("output/");

Now let's try creating that file again:

// The root is the output/ folder, so we don't have to specify that
FSFile iron = fs.createFile("textures/iron.png").orElseThrow(NullPointerException::new);
iron.writeBytes(ironTexture, false);

Nice! But what if we want to create an output directory for sounds, and another for nature-only textures? Say no more:

boolean success = fs.createDirectory("sounds/");
success = fs.createDirectory("textures/nature/");

// Will also create any non-existing sub-folders
fs.createDirectory("textures/nature/more/folders/here");

The file system can also handle archive files (.zip, more in the future).

fs.addToSearchPath("assets/archive.zip", FileLocation.EXTERNAL);
// File comes from inside the zip file
FSFile brass = fs.open("textures/brass.txt", FileAccessType.READ).orElseThrow(NullPointerException::new);