API Setup

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");
    }
}

When you enable maintenance mode, all non-whitelisted players are immediately kicked from the server.

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]

Use 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

Getting Started

Core API

Proxy API

Events

Examples

Requirements

Adding the Dependency

Maven

Gradle (Kotlin DSL)

Gradle (Groovy DSL)

Getting the API Instance

Null Safety

Basic Usage Examples

Toggle Maintenance Mode

Access Settings

Listen to Events

Plugin Dependency

Paper/Spigot (plugin.yml)

BungeeCord (bungee.yml)

Verify Installation

Next Steps

​Requirements

​Adding the Dependency

​Maven

​Gradle (Kotlin DSL)

​Gradle (Groovy DSL)

​Getting the API Instance

​Null Safety

​Basic Usage Examples

​Toggle Maintenance Mode

​Access Settings

​Listen to Events

​Plugin Dependency

​Paper/Spigot (plugin.yml)

​BungeeCord (bungee.yml)

​Verify Installation

​Next Steps

Requirements

Adding the Dependency

Maven

Gradle (Kotlin DSL)

Gradle (Groovy DSL)

Getting the API Instance

Null Safety

Basic Usage Examples

Toggle Maintenance Mode

Access Settings

Listen to Events

Plugin Dependency

Paper/Spigot (plugin.yml)

BungeeCord (bungee.yml)

Verify Installation

Next Steps