File registration

Since 1.0.0

As mentioned on "Accessing the API", the MCPlugin class provides easy access to most methods of MCUtils, this methods include file registration. The most basic included file type is the YmlFile, but here are all file types, the order is important as PluginFile extends YmlFile and so on.

• YmlFile - A basic .yml file that supports UTF-8 and can be reloaded. (Code)

• PluginFile - This file can also be updated, adding any missing paths by doing so. (Code)

• MessagesFile - Also includes message methods with access to every chat feature. (Code)

A more primitive file type that cannot be registered is the CharsetYamlConfiguration.

Registering a file

Any class extending MCPlugin can register files, here is how to do so:

import net.codersky.mcutils.files.YmlFile;
import you.yourname.yourplugin.files.CustomFile;

// For YmlFiles, PluginFiles and MessagesFiles you can just use this one
YmlFile file = plugin.registerFile("path/to/file", YmlFile.class);

// For custom files implementing either FileHolder or FileUpdater use an instance
CustomFile cFile = plugin.registerFile(new CustomFile());

Note that as a more "complex" approach for yml files only is to create your own class extending YmlFile, (Or any other class implementing FileHolder, but we will use YmlFile on this example for the sake of simplicity) then, registering an instance of said class. For other file types, read file types.

public class CustomYmlFile extends YmlFile {

    public CustomYmlFile(TestPlugin plugin, String path) {
        super(plugin, path);
    }

    // Whatever methods you want to add.
}

CustomYmlFile file = plugin.registerFile(new CustomYmlFile(plugin, "path/to/file"));

Common methods

MCPlugin contains various methods that will perform a certain task for every registered file. MCUtils provides a file updater that can be used on any class extending PluginFile, this method compares the local file stored on the server with the internal file present on the plugin, which is considered to be the latest version of the file, adding any missing paths and removing any unknown path from the local file. Paths can be ignored by the updater by providing a String list with said paths.

// Doing a simple reload on all registered files, without updating them.
plugin.reload();
// Doing a reload, then updating all files ignoring the paths specified on a list.
plugin.reload(Arrays.asList("Ignore.This.Path"));
// Updating all files extending PluginFile without ignoring paths.
plugin.update();
// Updating all files extending PluginFile ignoring the specified paths.
plugin.update(Arrays.asList("Ignore.This.Path"));

Ignored paths also affect child paths, let's see this with a real example. Assume we have the following yml file.

Parent:
  Child: true
  AnotherChild: false
ToUpdate: 42

Imagine "Parent" is a path where the end user should be able to include new paths, this paths would need to be ignored by the file updater, otherwise, they would get removed as the local file won't have them. To achieve this, we can use this code:

// Ignores "Parent" and any path under "Parent", for example "Parent.Child"
plugin.update(Arrays.asList("Parent"));

"ToUpdate" will still be added to the local file if missing, but "Parent" and any path under "Parent", won't.