This guide shows you how to add the Maintenance API to your plugin project and get started with basic usage.
Requirements
- Java 21 or higher
- Maintenance plugin installed on your server
- Maven or Gradle build system
Adding the Dependency
Maven
Add the Maintenance API dependency to your pom.xml:
<dependency>
<groupId>eu.kennytv.maintenance</groupId>
<artifactId>maintenance-api</artifactId>
<version>5.0.0-SNAPSHOT</version>
<scope>provided</scope>
</dependency>
Gradle (Kotlin DSL)
Add the dependency to your build.gradle.kts:
dependencies {
compileOnly("eu.kennytv.maintenance:maintenance-api:5.0.0-SNAPSHOT")
}
Gradle (Groovy DSL)
Add the dependency to your build.gradle:
dependencies {
compileOnly 'eu.kennytv.maintenance:maintenance-api:5.0.0-SNAPSHOT'
}
Use compileOnly (or provided scope in Maven) since the Maintenance plugin provides the API at runtime.
Getting the API Instance
The API is accessed through the MaintenanceProvider class:
import eu.kennytv.maintenance.api.Maintenance;
import eu.kennytv.maintenance.api.MaintenanceProvider;
public class MyPlugin extends JavaPlugin {
@Override
public void onEnable() {
Maintenance api = MaintenanceProvider.get();
if (api == null) {
getLogger().warning("Maintenance plugin not found!");
return;
}
// API is ready to use
getLogger().info("Connected to Maintenance v" + api.getVersion());
}
}
Null Safety
The MaintenanceProvider.get() method returns @Nullable Maintenance, so always check for null:
Maintenance api = MaintenanceProvider.get();
if (api != null) {
// Safe to use API
boolean inMaintenance = api.isMaintenance();
} else {
// Maintenance plugin not loaded yet or not installed
}
Basic Usage Examples
Toggle Maintenance Mode
Maintenance api = MaintenanceProvider.get();
if (api != null) {
// Enable maintenance mode
api.setMaintenance(true);
// Disable maintenance mode
api.setMaintenance(false);
// Check current status
if (api.isMaintenance()) {
System.out.println("Server is in maintenance mode");
}
}
Access Settings
Maintenance api = MaintenanceProvider.get();
if (api != null) {
Settings settings = api.getSettings();
// Check if ping messages are enabled
boolean pingMessages = settings.isEnablePingMessages();
// Get all whitelisted players
Map<UUID, String> whitelisted = settings.getWhitelistedPlayers();
// Reload configuration
settings.reloadConfigs();
}
Listen to Events
import eu.kennytv.maintenance.api.event.MaintenanceChangedEvent;
import eu.kennytv.maintenance.api.event.MaintenanceReloadedEvent;
Maintenance api = MaintenanceProvider.get();
if (api != null) {
// Listen for maintenance mode changes
api.getEventManager().registerListener(
event -> {
MaintenanceChangedEvent e = (MaintenanceChangedEvent) event;
System.out.println("Maintenance mode: " + e.isMaintenance());
},
MaintenanceChangedEvent.class
);
// Listen for config reloads
api.getEventManager().registerListener(
event -> {
System.out.println("Configuration reloaded");
},
MaintenanceReloadedEvent.class
);
}
Plugin Dependency
Make sure to declare Maintenance as a dependency in your plugin descriptor:
Paper/Spigot (plugin.yml)
name: MyPlugin
version: 1.0.0
main: com.example.MyPlugin
depend: [Maintenance]
BungeeCord (bungee.yml)
name: MyPlugin
main: com.example.MyPlugin
depends: [Maintenance]
depend if your plugin requires Maintenance to function, or softdepend if it’s optional.
Verify Installation
To verify the API is working correctly:
@Override
public void onEnable() {
Maintenance api = MaintenanceProvider.get();
if (api == null) {
getLogger().severe("Maintenance API not available!");
getServer().getPluginManager().disablePlugin(this);
return;
}
getLogger().info("Successfully hooked into Maintenance v" + api.getVersion());
getLogger().info("Current maintenance status: " + api.isMaintenance());
}
Next Steps
- Events - Learn about the event system in detail
- Settings API - Working with settings and config
- Examples - More complete usage examples