Backup Service API

Trigger and restore backups programmatically.

Interact with BuildSystem's backup scheduler, configure storage credentials, and execute restores programmatically.

---

1. Backup Operations

Manage world backups using the BackupService interface, resolved from the root BuildSystem instance.

Checking Backup History

Fetch the BackupProfile for a target world to list its existing backups:

import de.eintosti.buildsystem.api.BuildSystem;
import de.eintosti.buildsystem.api.BuildSystemProvider;
import de.eintosti.buildsystem.api.world.BuildWorld;
import de.eintosti.buildsystem.api.world.backup.Backup;
import de.eintosti.buildsystem.api.world.backup.BackupProfile;
import de.eintosti.buildsystem.api.world.backup.BackupService;
import java.util.List;

BackupService backupService = BuildSystemProvider.get().getBackupService();
BackupProfile profile = backupService.getProfile(buildWorld);

// Retrieve all stored backups asynchronously
profile.listBackups().thenAccept(backups -> {
    for (Backup backup : backups) {
        long creationTime = backup.creationTime();
        String backupKey = backup.key(); // Identifier string
    }
});

Programmatic Backup Creation

Trigger an off-thread backup execution:

// Starts asynchronous backup generation
profile.createBackup(); 

Programmatic Backup Restoration

Restore a world state using a reference to a Backup. This task executes off-thread.

import org.bukkit.entity.Player;

Backup targetBackup = backups.get(0); // Choose target
Player playerAudience = event.getPlayer(); // Audience to receive status logs

// Executes asynchronous restoration sequence
profile.restoreBackup(targetBackup, playerAudience); 

---

2. Technical Safeguards & Off-Thread Execution

• Thread Optimization: The backup service allocates a bounded background executor to run file compression (ZIP/Tarball operations) and remote transfers (S3, SFTP). This isolates resource-heavy IO operations from the Bukkit server tick thread.

• Storage Provider Failures: Storage credential resolution and handshake checks execute before world archiving starts. SFTP storage issues raise standard IOException failures immediately, protecting active memory states from silent failures.