Add ability to create World Backups

buildsystem-api/src/main/java/de/eintosti/buildsystem/api/world/BuildWorld.java

@@ -88,8 +88,10 @@ public interface BuildWorld extends Displayable {
 
     /**
      * Gets the custom chunk generator used to generate the world.
+     * <p>
+     * Only set when the world type is {@link BuildWorldType#CUSTOM} or {@link BuildWorldType#IMPORTED}.
      *
-     * @return The custom chunk generator used to generate the world.
+     * @return The custom chunk generator used to generate the world, or {@code null} if not set
      */
     @Nullable
     CustomGenerator getCustomGenerator();

buildsystem-api/src/main/java/de/eintosti/buildsystem/api/world/backup/Backup.java

@@ -0,0 +1,45 @@
+/*
+ * Copyright (c) 2018-2025, Thomas Meaney
+ * Copyright (c) contributors
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+package de.eintosti.buildsystem.api.world.backup;
+
+/**
+ * Represents a single backup of a {@link de.eintosti.buildsystem.api.world.BuildWorld}.
+ */
+public interface Backup {
+
+    /**
+     * Returns the {@link BackupProfile} that owns this backup.
+     *
+     * @return The owner of the backup.
+     */
+    BackupProfile owner();
+
+    /**
+     * Returns the timestamp when this backup was created.
+     *
+     * @return The creation time in milliseconds since the Unix epoch.
+     */
+    long creationTime();
+
+    /**
+     * Returns a unique key or identifier for this backup.
+     *
+     * @return The key of the backup.
+     */
+    String key();
+}

buildsystem-api/src/main/java/de/eintosti/buildsystem/api/world/backup/BackupProfile.java

@@ -0,0 +1,46 @@
+/*
+ * Copyright (c) 2023-2025, Thomas Meaney
+ * All rights reserved.
+ *
+ * Unauthorized copying of this file, via any medium is strictly prohibited
+ * Proprietary and confidential
+ */
+package de.eintosti.buildsystem.api.world.backup;
+
+import de.eintosti.buildsystem.api.world.BuildWorld;
+import java.util.List;
+import java.util.concurrent.CompletableFuture;
+import org.bukkit.entity.Player;
+
+/**
+ * Represents a profile for managing backups of a specific {@link BuildWorld}. This interface defines operations related to listing, creating, restoring, and destroying backups.
+ */
+public interface BackupProfile {
+
+    /**
+     * Asynchronously populates a list of available {@link Backup}s under this profile.
+     *
+     * @return Future that will be completed with available backups
+     */
+    CompletableFuture<List<Backup>> listBackups();
+
+    /**
+     * Creates a backup of the {@link BuildWorld}. If the profile is at the maximum backup capacity, the oldest backup will be deleted.
+     *
+     * @return Future that completes with the created backup.
+     */
+    CompletableFuture<Backup> createBackup();
+
+    /**
+     * Restores a {@link Backup}.
+     *
+     * @param backup Backup to restore
+     * @param player The player restoring the backup
+     */
+    void restoreBackup(Backup backup, Player player);
+
+    /**
+     * Removes all {@link Backup}s stored for this profile.
+     */
+    void destroy();
+}

buildsystem-api/src/main/java/de/eintosti/buildsystem/api/world/backup/BackupStorage.java

@@ -0,0 +1,79 @@
+/*
+ * Copyright (c) 2018-2025, Thomas Meaney
+ * Copyright (c) contributors
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+package de.eintosti.buildsystem.api.world.backup;
+
+import de.eintosti.buildsystem.api.world.BuildWorld;
+import java.io.File;
+import java.util.List;
+import java.util.concurrent.CompletableFuture;
+
+/**
+ * Represents a storage mechanism for managing world backups.
+ */
+public interface BackupStorage {
+
+    /**
+     * Generates a unique backup name based on a given timestamp.
+     *
+     * @param timestamp The timestamp to use for the backup name.
+     * @return A string representing the backup name (e.g., "1678886400000.zip").
+     */
+    default String getBackupName(long timestamp) {
+        return timestamp + ".zip";
+    }
+
+    /**
+     * Lists all available {@link Backup}s for a specific {@link BuildWorld}.
+     *
+     * @param buildWorld The world for which to list backups
+     * @return A future with a list of backup objects associated with the specified world
+     */
+    CompletableFuture<List<Backup>> listBackups(BuildWorld buildWorld);
+
+    /**
+     * Creates and stores a new {@link Backup} for a given {@link BuildWorld}. The result of the operation is communicated via the provided {@link CompletableFuture}.
+     * <p>
+     * In comparison to {@link BackupProfile#createBackup()}, a backup will always be created and no older backups will be deleted. This method is intended for immediate backup
+     * creation and storage, rather than profile management.
+     *
+     * @param buildWorld The world to be backed up
+     * @return A future that will be completed with the backup object upon successful storage, or exceptionally if an error occurs
+     */
+    CompletableFuture<Backup> storeBackup(BuildWorld buildWorld);
+
+    /**
+     * Downloads a specific {@link Backup} file asynchronously.
+     *
+     * @param backup The backup object representing the backup to be downloaded
+     * @return A future that will complete with a {@link File} object pointing to the downloaded backup once the download operation is finished
+     */
+    CompletableFuture<File> downloadBackup(Backup backup);
+
+    /**
+     * Deletes a specific {@link Backup}.
+     *
+     * @param backup The backup object representing the backup to be deleted
+     * @return A future that will complete after the deletion
+     */
+    CompletableFuture<Void> deleteBackup(Backup backup);
+
+    /**
+     * Closes the backup storage, releasing any resources.
+     */
+    void close();
+}

buildsystem-api/src/main/java/de/eintosti/buildsystem/api/world/backup/package-info.java

@@ -0,0 +1,22 @@
+/*
+ * Copyright (c) 2018-2025, Thomas Meaney
+ * Copyright (c) contributors
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+/**
+ * Provides interfaces and classes for managing world backups.
+ */
+package de.eintosti.buildsystem.api.world.backup; 

buildsystem-api/src/main/java/de/eintosti/buildsystem/api/world/builder/package-info.java

@@ -0,0 +1,22 @@
+/*
+ * Copyright (c) 2018-2025, Thomas Meaney
+ * Copyright (c) contributors
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+/**
+ * Provides interfaces and classes for managing world builders and their associated permissions.
+ */
+package de.eintosti.buildsystem.api.world.builder;

buildsystem-api/src/main/java/de/eintosti/buildsystem/api/world/creation/BuildWorldCreator.java

@@ -127,25 +127,26 @@ public interface BuildWorldCreator {
     void importWorld(Player player, boolean teleport);
 
     /**
-     * Generates the underlying Bukkit {@link World} and applies post-generation settings.
+     * Generates the underlying Bukkit {@link World} and applies post-generation settings. Only generates the world if the world was not created in a newer Minecraft version that
+     * the server is running.
      * <p>
-     * Only generates the world if the world was not created in a newer Minecraft version that the server is running.
+     * Important: This method should only be called after the world has been created and registered with the plugin.
      *
-     * @param buildWorld The build world to generate
      * @return The generated {@link World}, or {@code null} if generation failed
      */
     @Nullable
-    default World generateBukkitWorld(BuildWorld buildWorld) {
-        return generateBukkitWorld(buildWorld, true);
+    default World generateBukkitWorld() {
+        return generateBukkitWorld(true);
     }
 
     /**
      * Generates the underlying Bukkit {@link World} and applies post-generation settings.
+     * <p>
+     * Important: This method should only be called after the world has been created and registered with the plugin.
      *
-     * @param buildWorld   The build world to generate
      * @param checkVersion If true, verify that the world's data version is compatible
-     * @return The generated {@link World}, or {@code null} if generation failed.
+     * @return The generated {@link World}, or {@code null} if generation failed
      */
     @Nullable
-    World generateBukkitWorld(BuildWorld buildWorld, boolean checkVersion);
+    World generateBukkitWorld(boolean checkVersion);
 }

buildsystem-api/src/main/java/de/eintosti/buildsystem/api/world/creation/package-info.java

@@ -0,0 +1,22 @@
+/*
+ * Copyright (c) 2018-2025, Thomas Meaney
+ * Copyright (c) contributors
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+/**
+ * Provides interfaces and classes for managing world creation and initialization.
+ */
+package de.eintosti.buildsystem.api.world.creation;

buildsystem-api/src/main/java/de/eintosti/buildsystem/api/world/data/BuildWorldType.java

@@ -32,50 +32,50 @@ public enum BuildWorldType {
     /**
      * A standard world type, equivalent to a default Minecraft overworld with {@link Environment#NORMAL}.
      */
-    NORMAL(),
+    NORMAL,
 
     /**
      * A super-flat world, ideal for creative building without terrain obstacles.
      */
-    FLAT(),
+    FLAT,
 
     /**
      * A world type representing the Nether dimension, with {@link Environment#NETHER}.
      */
-    NETHER(),
+    NETHER,
 
     /**
      * A world type representing the End dimension, with {@link Environment#THE_END}.
      */
-    END(),
+    END,
 
     /**
      * An empty world, containing no blocks except for a single platform at spawn.
      */
-    VOID(),
+    VOID,
 
     /**
      * A world created as an identical copy of an existing template world.
      */
-    TEMPLATE(),
+    TEMPLATE,
 
     /**
      * A world that, by default, can only be modified by its creator.
      */
-    PRIVATE(),
+    PRIVATE,
 
     /**
      * A world that was not originally created by the BuildSystem plugin but has been imported for management.
      */
-    IMPORTED(),
+    IMPORTED,
 
     /**
      * A world generated using a custom {@link ChunkGenerator}.
      */
-    CUSTOM(),
+    CUSTOM,
 
     /**
      * A world whose type could not be determined or is not recognized by the BuildSystem.
      */
-    UNKNOWN()
+    UNKNOWN
 }

buildsystem-api/src/main/java/de/eintosti/buildsystem/api/world/data/WorldData.java

@@ -19,6 +19,7 @@
 
 import com.cryptomorin.xseries.XMaterial;
 import de.eintosti.buildsystem.api.world.BuildWorld;
+import de.eintosti.buildsystem.api.world.backup.Backup;
 import java.util.Map;
 import org.bukkit.Difficulty;
 import org.bukkit.Location;
@@ -139,6 +140,13 @@ public interface WorldData {
      */
     Type<Boolean> privateWorld();
 
+    /**
+     * Gets the number of seconds that have passed since that last {@link Backup} of the {@link BuildWorld} was created.
+     *
+     * @return The number of seconds since the last backup
+     */
+    Type<Integer> timeSinceBackup();
+
     /**
      * Retrieves a {@link Type} object representing the timestamp (in milliseconds since epoch) of the last time the {@link BuildWorld} was edited.
      *