Document versioning system

DVS, what it is and why it's important.

DVS stands for "Document Versioning System" - a system used by the updater to index documents (the updated document and defaults) by their version IDs.

Version IDs represent the individual revisions of certain file; while being unique (there cannot be one ID assigned to multiple revisions of the file) - just like version (ID) of your plugin. IDs are specified by patterns, which define their composition.

Such indexing tells the updater if an upgrade, downgrade, or if anything at all is needed, saving time and memory consumption on almost every run. Relocations and ignored routes are also indexed by version IDs.

Need a hand?

Feel free to join our Discord server and we'll more than happily help you.

Quick setup

You might already be familiar with specifying something like this inside your configuration file:

...
config-version: 1
...

Pick your route

Now, pick any route at which you would like the current version ID of the file to be specified. Create a new BasicVersioning object, pass the desired route in and set it to your UpdaterSettings, just like this:

UpdaterSettings.builder().setVersioning(new BasicVersioning("config-version"))

Please note you can also use routes as the parameter, not only string ones. Once you chose a route, you cannot change it (technically, you can, but the previous route will no longer be known by the updater).

Pattern scheme

The versioning used (BasicVersioning) defines the pattern for version IDs as integers starting from 1 and going all the way to the infinity (1, 2, 3... Integer.MAX_VALUE).

That means, the first version ID you are going to use for the document is 1, the next revision of the file will have 2... Here is an example of your second revision of the document:

...
config-version: 2
...

Important notes

The defaults must always have the version ID specified at the given route and it must be an integer (or string containing the integer) as described above. The updater will throw an NPE otherwise.

Unlike version ID of the defaults, ID in the document itself is open and vulnerable to modifications from the user's side (mainly if it is used as a configuration file...). If no version ID was found at the specified route inside the document, or it is not valid (not an integer in this case), the first version ID defined by the pattern is assigned to it. That is, for the current configuration, it is 1.

After a successful update, the version ID inside the document is automatically changed.

Malforming the version ID inside the document might still lead to potentially destructive actions and loss of content.

This only applies if using relocations and/or ignored routes. You should always instruct (using a comment) users that the ID should never be changed, nor manipulated with.

That's all

You can now use advanced updater settings, like relocations and ignored routes. Please remember that in-code, version IDs are always specified as strings. Done 👏

Not enough?

To use the full potential out of the DVS, you can dive into advanced topics.