Conditional Registration

Since v6.2.0

The @ConditionalOnConfig annotation is available starting from UltiTools-API v6.2.0.

UltiTools allows you to conditionally register components based on YAML configuration values. This lets server admins enable or disable features without requiring code changes.

Basic Usage

Add @ConditionalOnConfig to any component class (@Service, @CmdExecutor, @EventListener):

@CmdExecutor(alias = {"warp"}, permission = "myplugin.command.warp")
@ConditionalOnConfig(value = "config/config.yml", path = "enableWarp")
public class WarpCommands extends AbstractCommandExecutor {
    // Only registered if enableWarp: true in config.yml
}

The corresponding YAML:

# config/config.yml
enableWarp: true

If enableWarp is false or missing, the WarpCommands class is not registered at all — no command, no memory usage, no side effects.

Annotation Attributes

Attribute	Type	Default	Description
value	String	(required)	Config file path relative to the plugin data folder
path	String	(required)	Dot-separated or slash-separated YAML key path
negate	boolean	false	If true, register when config value is false (inverted logic)

Examples

Conditional Service

@Service
@ConditionalOnConfig(value = "config/config.yml", path = "economy.enabled")
public class EconomyService {

    @Scheduled(period = 36000, async = true)
    public void distributeTax() {
        // Only runs if economy.enabled: true
    }
}

Conditional Event Listener

@EventListener
@ConditionalOnConfig(value = "config/config.yml", path = "welcomeMessage.enabled")
public class WelcomeListener implements Listener {

    @EventHandler
    public void onPlayerJoin(PlayerJoinEvent event) {
        event.getPlayer().sendMessage("Welcome to the server!");
    }
}

Nested Config Keys

Use dots or slashes for nested keys:

# config/config.yml
features:
  teleport:
    enabled: true
  pvp:
    enabled: false

@CmdExecutor(alias = {"tp"}, permission = "myplugin.teleport")
@ConditionalOnConfig(value = "config/config.yml", path = "features.teleport.enabled")
public class TeleportCommands extends AbstractCommandExecutor {
    // ...
}

Inverted Logic with negate

Use negate = true to register a component when the config value is false:

@Service
@ConditionalOnConfig(value = "config/config.yml", path = "maintenance", negate = true)
public class NormalModeService {
    // Only active when maintenance: false (or missing)
}

Complete Example

A plugin with optional features controlled by config:

# config/config.yml
features:
  home: true
  warp: true
  economy: false
  welcome: true

@UltiToolsModule(scanBasePackages = {"com.example.plugin"})
public class MyPlugin extends UltiToolsPlugin {
    @Override
    public boolean registerSelf() { return true; }

    @Override
    public void unregisterSelf() { }
}

@CmdExecutor(alias = {"home"}, permission = "myplugin.home")
@ConditionalOnConfig(value = "config/config.yml", path = "features.home")
public class HomeCommands extends AbstractCommandExecutor {
    // Registered (features.home = true)
}

@CmdExecutor(alias = {"warp"}, permission = "myplugin.warp")
@ConditionalOnConfig(value = "config/config.yml", path = "features.warp")
public class WarpCommands extends AbstractCommandExecutor {
    // Registered (features.warp = true)
}

@Service
@ConditionalOnConfig(value = "config/config.yml", path = "features.economy")
public class EconomyService {
    // NOT registered (features.economy = false)
}

@EventListener
@ConditionalOnConfig(value = "config/config.yml", path = "features.welcome")
public class WelcomeListener implements Listener {
    // Registered (features.welcome = true)
}

Before v6.2.0

Without @ConditionalOnConfig, developers had to manually check config values in registerSelf() and conditionally register components with if statements. The annotation approach is cleaner and eliminates boilerplate.

Contributors

Ling Bao

Claude Opus 4.6

Changelog

Last edited 1 minute ago

View full history

619b0c9-feat: add version switcher with @viteplus/versions for v6.1.0/v6.2.0 docs