diff --git a/buildsystem-api/src/main/java/de/eintosti/buildsystem/api/world/BuildWorld.java b/buildsystem-api/src/main/java/de/eintosti/buildsystem/api/world/BuildWorld.java index ee03f364..e327c29d 100644 --- a/buildsystem-api/src/main/java/de/eintosti/buildsystem/api/world/BuildWorld.java +++ b/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. + *

+ * 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(); diff --git a/buildsystem-api/src/main/java/de/eintosti/buildsystem/api/world/backup/Backup.java b/buildsystem-api/src/main/java/de/eintosti/buildsystem/api/world/backup/Backup.java new file mode 100644 index 00000000..1aaab91d --- /dev/null +++ b/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 . + */ +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(); +} diff --git a/buildsystem-api/src/main/java/de/eintosti/buildsystem/api/world/backup/BackupProfile.java b/buildsystem-api/src/main/java/de/eintosti/buildsystem/api/world/backup/BackupProfile.java new file mode 100644 index 00000000..e06d0995 --- /dev/null +++ b/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> 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 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(); +} diff --git a/buildsystem-api/src/main/java/de/eintosti/buildsystem/api/world/backup/BackupStorage.java b/buildsystem-api/src/main/java/de/eintosti/buildsystem/api/world/backup/BackupStorage.java new file mode 100644 index 00000000..7116cfc3 --- /dev/null +++ b/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 . + */ +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> 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}. + *

+ * 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 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 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 deleteBackup(Backup backup); + + /** + * Closes the backup storage, releasing any resources. + */ + void close(); +} diff --git a/buildsystem-api/src/main/java/de/eintosti/buildsystem/api/world/backup/package-info.java b/buildsystem-api/src/main/java/de/eintosti/buildsystem/api/world/backup/package-info.java new file mode 100644 index 00000000..cafd7c5f --- /dev/null +++ b/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 . + */ + +/** + * Provides interfaces and classes for managing world backups. + */ +package de.eintosti.buildsystem.api.world.backup; \ No newline at end of file diff --git a/buildsystem-api/src/main/java/de/eintosti/buildsystem/api/world/builder/package-info.java b/buildsystem-api/src/main/java/de/eintosti/buildsystem/api/world/builder/package-info.java new file mode 100644 index 00000000..26c9a353 --- /dev/null +++ b/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 . + */ + +/** + * Provides interfaces and classes for managing world builders and their associated permissions. + */ +package de.eintosti.buildsystem.api.world.builder; \ No newline at end of file diff --git a/buildsystem-api/src/main/java/de/eintosti/buildsystem/api/world/creation/BuildWorldCreator.java b/buildsystem-api/src/main/java/de/eintosti/buildsystem/api/world/creation/BuildWorldCreator.java index 9f474446..85565ca5 100644 --- a/buildsystem-api/src/main/java/de/eintosti/buildsystem/api/world/creation/BuildWorldCreator.java +++ b/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. *

- * 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. + *

+ * 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); } \ No newline at end of file diff --git a/buildsystem-api/src/main/java/de/eintosti/buildsystem/api/world/creation/package-info.java b/buildsystem-api/src/main/java/de/eintosti/buildsystem/api/world/creation/package-info.java new file mode 100644 index 00000000..2fa2bf6a --- /dev/null +++ b/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 . + */ + +/** + * Provides interfaces and classes for managing world creation and initialization. + */ +package de.eintosti.buildsystem.api.world.creation; \ No newline at end of file diff --git a/buildsystem-api/src/main/java/de/eintosti/buildsystem/api/world/data/BuildWorldType.java b/buildsystem-api/src/main/java/de/eintosti/buildsystem/api/world/data/BuildWorldType.java index 9362f4e6..46b16d9f 100644 --- a/buildsystem-api/src/main/java/de/eintosti/buildsystem/api/world/data/BuildWorldType.java +++ b/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 } \ No newline at end of file diff --git a/buildsystem-api/src/main/java/de/eintosti/buildsystem/api/world/data/WorldData.java b/buildsystem-api/src/main/java/de/eintosti/buildsystem/api/world/data/WorldData.java index 7b007cd3..f788b6b9 100644 --- a/buildsystem-api/src/main/java/de/eintosti/buildsystem/api/world/data/WorldData.java +++ b/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 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 timeSinceBackup(); + /** * Retrieves a {@link Type} object representing the timestamp (in milliseconds since epoch) of the last time the {@link BuildWorld} was edited. * diff --git a/buildsystem-api/src/main/java/de/eintosti/buildsystem/api/world/display/package-info.java b/buildsystem-api/src/main/java/de/eintosti/buildsystem/api/world/display/package-info.java new file mode 100644 index 00000000..5d485e1d --- /dev/null +++ b/buildsystem-api/src/main/java/de/eintosti/buildsystem/api/world/display/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 . + */ + +/** + * Provides interfaces and classes for managing world display and rendering. + */ +package de.eintosti.buildsystem.api.world.display; \ No newline at end of file diff --git a/buildsystem-api/src/main/java/de/eintosti/buildsystem/api/world/util/WorldPermissions.java b/buildsystem-api/src/main/java/de/eintosti/buildsystem/api/world/util/WorldPermissions.java index 503a7628..9a9b40a7 100644 --- a/buildsystem-api/src/main/java/de/eintosti/buildsystem/api/world/util/WorldPermissions.java +++ b/buildsystem-api/src/main/java/de/eintosti/buildsystem/api/world/util/WorldPermissions.java @@ -18,6 +18,7 @@ package de.eintosti.buildsystem.api.world.util; import de.eintosti.buildsystem.api.world.BuildWorld; +import de.eintosti.buildsystem.api.world.builder.Builder; import de.eintosti.buildsystem.api.world.data.BuildWorldStatus; import java.util.function.Supplier; import org.bukkit.entity.Player; @@ -48,13 +49,13 @@ public interface WorldPermissions { boolean canEnter(Player player); /** - * Determines if the given {@link Player} can modify the {@link de.eintosti.buildsystem.api.world.BuildWorld} they are currently in. + * Determines if the given {@link Player} can modify the {@link BuildWorld} they are currently in. *

* Modifications might be disallowed due to: *

* However, a player can bypass these restrictions if: *