Save & Load Data Files

In this tutorial we will cover the basics of saving and loading your own custom data files.
We will cover how to create Classes that can be serialized, how to "deflate" the data to save on file space, and how to inflate the data while simultaneously loading it back from the hard disk to speed up load times.

First we will start with a container class. This class will be a template to hold all of the data we wish to serialize (save) and deserialize (load).
All primitive data types, such as Integers, Strings, and Bytes can be serialized without any added code. Most bukkit/Spigot classes can be serialized as well, but not all directly.
To ensure that our Classes can be serialized they will need to implement the "Serializable" interface. We will call our container class Data and implement this now.
Now to compile without warnings we will have to add a Serial version ID.
Most IDEs should have a suggestion or quick fix on how to achieve this. If so, click "Add generated serial version ID" and it will generate a serial version for us, if not use the one from this tutorial.

Next lets talk about the transient variable modifier. It can be used to specify fields within classes that are not essential, or should not be serialized when we go to do so.
For example, you store the "current" location of a player in one of your classes. If that location is serialized, saved, then loaded back later, it will most likely no longer be "current" and will need to be recalculated. This is when you would mark the variable as transient to keep the serialization as logical and efficient as possible, no need to save something that has no purpose to us when it is loaded back.
Another example is this serial version ID we just created. It is static and our program will already be aware of it if we do not load it back, so we should mark this field as transient.

Our class should now look like this:
Next we will add a function to save this data to a file. The data will be blank for now, but that is O.K..
To do this we will need a few things.
We now have the shell of a method that will take in a file path parameter and return true when the data is saved successfully or false if not.
The BukkitObjectOutputStream is where the magic happens for us. It will take any serializable object that bukkit/Spigot can use and convert it to a savable (serializable) format. It's constructor requires an implementation of an output stream. We could simply provide it with the FileOutputStream, but we would like to compress (deflate) our data to shrink it down in size. The GZIPOutputStream does that for us, so we pass the FileOutputStream to the GZIPOutputStream 's constructor, then the GZIPOutputStream to the BukkitObjectOutputStream 's constructor and we have a ready to go BukkitObjectOutputStream.

Now that you understand how all that works, we will condense it down into a one liner and attempt to write the data to a file, and close the stream:
Time to add in a loadData method, this works the exact same way as our saveData method, just with input streams rather than output streams:
Excellent, now we can save and load data to and from files, however the data is still blank, and the file currently comes back to us a temporary value.
Now we will need to decide what kind of data we wish to add to the container. This will most likely be separate data that you already have in memory, and we will have to modify the save and load methods to handle this.

Let us say that you have a Collection of Blocks that you wish to save. Unfortunately one can not simply serialize a Block, but it can be done indirectly.
Blocks are made up of components that can be serialized. The Block's Location can be serialized as well as it's BlockData because the block data itself can be serialized as a String. We can then map the BlockData to a Location using a HashMap<Location, String> and we can store what the block data at each location should be. You can also serialize Player's indirectly using their UUID.
Lets say we want to do this, save a bunch of BlockData for specific locations, and all the players that were online when the file last saved.
We will add both of these elements to the container Data class, and add in a constructor to use when saving data, and one to use while loading data:
Next we will modify the the loadData method to become a static method and return a Data object when loaded, or null if the load has failed:
Notice how we must cast the in.readObject() to (Data). This is important, what we read in (the file) must be the same type of object as what we are trying to assign to in memory. If you mix and match data types an exception will be thrown.

And finally we will put it all together, we will create some methods that will retrieve some data from the server and call our saveData method to save it to disk, and retrieve some data from our saved File and do cool stuff with it:
This example is honestly a little computationally ridiculous to be expected to run in one server tick and should really be spread out over time, but is meant as an example to show you potential.
For this machine it takes about 10 seconds to save and load the data respectively.

You now just need to pick an appropriate time and place in your code to call your getBlocksPlayersAndSave and welcomePlayersAndResetBlocks methods.

I have decided to call them when /save and /load commands are issued. You can check that out in the Tutorial.jar attached here: Tutorial.jar


Hope you have fun TNTing the heck out of your spawn, then using the data we saved to load it back.

A more serious note, you do not have to store all of your data into one single container like that, you can spread the data among multiple folders (use like keys) and files (use like values) or shortcuts(use like pointers). You will have to keep track of what type of data goes where, so that you can cast the loaded object to the correct type of data.

That will concludes this tutorial.

Thanks for reading, and have fun coding.
ForbiddenSoul