Package dev.cwhead.GravesX.module

Interface GravesXModuleController

public interface GravesXModuleController
Runtime lifecycle controller for GravesX modules.

Implementations are provided by the host (manager/controller). The controller exposed to a module via ModuleContext.getGravesXModules() can:

  • Query enablement state for itself or other modules
  • Enable/disable itself (current module)
  • Enable/disable another module by key (module.yml name, simple class name, or FQCN)
  • Access read-only module descriptors and enumerate all modules
  • Query Folia support flags for itself or other modules
  • Query module load phase for itself or other modules

Unless otherwise noted, enable/disable operations are idempotent: invoking them when the target is already in the requested state returns true (no-op) and does not throw.

Note: the host may choose to permanently mark a module as failed (for example, if its enable logic throws, or if it is incompatible with the current server type such as Folia vs non-Folia). In such cases, enableModule(...) may consistently return false even though no exception is thrown.

  • Method Details

    • isEnabled

      boolean isEnabled()
      Reports whether this (current) module is enabled.
      Returns:
      true if the current module is enabled; false otherwise

    • isEnabled

      boolean isEnabled(String moduleKey)
      Reports whether a target module is enabled. The moduleKey can be:
      • the module.yml name
      • the module's simple class name
      • the module's fully qualified class name (FQCN)
      Matching is implementation-defined (typically case-insensitive).
      Parameters:
      moduleKey - identifier for the target module
      Returns:
      true if the target module is enabled; false if disabled or not found

    • disableModule

      void disableModule()
      Disables this (current) module.

      Idempotent: if already disabled, no action is taken.

    • disableModule

      boolean disableModule(String moduleKey)
      Disables a target module identified by key.

      Idempotent: returns true if the module becomes or was already disabled.

      Parameters:
      moduleKey - identifier for the target module (module.yml name, simple class name, or FQCN)
      Returns:
      true if state changed or the module was already disabled; false if not found

    • enableModule

      void enableModule()
      Enables this (current) module.

      Idempotent: if already enabled, no action is taken.

      The host may choose to refuse re-enabling modules that previously failed or are incompatible with the current runtime (e.g. Folia) without throwing; in such cases, this is a no-op.

    • enableModule

      boolean enableModule(String moduleKey)
      Enables a target module identified by key.

      Idempotent: returns true if the module becomes or was already enabled.

      The host may choose to refuse enabling modules that previously failed or are incompatible with the current runtime (e.g. Folia), in which case this returns false.

      Parameters:
      moduleKey - identifier for the target module (module.yml name, simple class name, or FQCN)
      Returns:
      true if state changed or the module was already enabled; false if not found

    • getModule

      GravesXModuleDescriptor getModule(String moduleKey)
      Returns the descriptor for a target module identified by key.

      The descriptor provides read-only metadata parsed from module.yml (name, version, authors, dependencies, flags, etc.) plus runtime state.

      Parameters:
      moduleKey - identifier for the target module (module.yml name, simple class name, or FQCN)
      Returns:
      a descriptor, or null if the module is unknown

    • getThisModule

      GravesXModuleDescriptor getThisModule()
      Returns the descriptor for this (current) module.
      Returns:
      a non-null descriptor for the current module

    • isEnabled

      boolean isEnabled(GravesXModule module)
      Returns whether the given module instance is enabled.
      Parameters:
      module - module instance (e.g. this or another module)
      Returns:
      true if the module is enabled, false otherwise

    • isEnabled

      boolean isEnabled(Class<? extends GravesXModule> moduleClass)
      Returns whether the module with the given implementation class is enabled.
      Parameters:
      moduleClass - implementation class of the module
      Returns:
      true if the module is enabled, false otherwise

    • disableModule

      boolean disableModule(GravesXModule module)
      Disables the target module instance.
      Parameters:
      module - module instance to disable
      Returns:
      true if the module was found and is now disabled (or already disabled); false if not found

    • disableModule

      boolean disableModule(Class<? extends GravesXModule> moduleClass)
      Disables the module with the given implementation class.
      Parameters:
      moduleClass - implementation class of the module to disable
      Returns:
      true if the module was found and is now disabled (or already disabled); false if not found

    • enableModule

      boolean enableModule(GravesXModule module)
      Enables the target module instance.
      Parameters:
      module - module instance to enable
      Returns:
      true if the module was found and is now enabled (or already enabled); false if not found

    • enableModule

      boolean enableModule(Class<? extends GravesXModule> moduleClass)
      Enables the module with the given implementation class.
      Parameters:
      moduleClass - implementation class of the module to enable
      Returns:
      true if the module was found and is now enabled (or already enabled); false if not found

    • getModule

      GravesXModuleDescriptor getModule(GravesXModule module)
      Looks up a module descriptor by its instance.
      Parameters:
      module - module instance
      Returns:
      descriptor for the target module, or null if unknown

    • getModule

      GravesXModuleDescriptor getModule(Class<? extends GravesXModule> moduleClass)
      Looks up a module descriptor by its implementation class.
      Parameters:
      moduleClass - implementation class of the module
      Returns:
      descriptor for the target module, or null if unknown

    • listModules

      Collection<GravesXModuleDescriptor> listModules()
      Returns descriptors for all discovered modules, regardless of enablement.
      Returns:
      a collection view of all module descriptors (may be empty, never null)

    • registerCommand

      void registerCommand(String label, GravesXModuleCommand command)
      Registers a command owned by this module with the GravesX command dispatcher.

      The exact wiring to Bukkit's command map is implementation-defined; the intent is that modules can expose lightweight, module-scoped commands without touching the core plugin's plugin.yml.

      Parameters:
      label - primary command label (without leading /)
      command - module command implementation
      Throws:
      IllegalArgumentException - if label is invalid or already in use

    • registerCommand

      void registerCommand(String label, Class<? extends GravesXModuleCommand> commandClass)
      Registers a command owned by this module with the GravesX command dispatcher, using a command implementation class.

      The host is responsible for instantiating the command class (for example via a no-arg constructor or dependency injection). This allows any class that implements GravesXModuleCommand to be registered without the module having to manage the instance lifecycle itself.

      Parameters:
      label - primary command label (without leading /)
      commandClass - implementation class of the command
      Throws:
      IllegalArgumentException - if label is invalid or already in use

    • getName

      default String getName(String moduleKey)
      Convenience accessor for getModule(moduleKey).getName().
      Parameters:
      moduleKey - identifier for the target module
      Returns:
      the module name, or null if not found

    • getVersion

      default String getVersion(String moduleKey)
      Convenience accessor for getModule(moduleKey).getVersion().
      Parameters:
      moduleKey - identifier for the target module
      Returns:
      the version string, or null if not found or unspecified

    • getWebsite

      default String getWebsite(String moduleKey)
      Convenience accessor for getModule(moduleKey).getWebsite().
      Parameters:
      moduleKey - identifier for the target module
      Returns:
      the website URL, or null if not found or unspecified

    • getAuthors

      default List<String> getAuthors(String moduleKey)
      Convenience accessor for getModule(moduleKey).getAuthors().
      Parameters:
      moduleKey - identifier for the target module
      Returns:
      the authors list, List.of() if not found or unspecified (never null)

    • supportsFolia

      default boolean supportsFolia(String moduleKey)
      Convenience accessor for getModule(moduleKey).supportsFolia().

      This reflects the supportsFolia boolean parsed from the target module's module.yml. If the module cannot be found, this returns false.

      Parameters:
      moduleKey - identifier for the target module
      Returns:
      true if the module exists and declares Folia support; false otherwise

    • supportsFolia

      default boolean supportsFolia()
      Convenience accessor for getThisModule().supportsFolia().

      This reflects the supportsFolia boolean parsed from this module's module.yml.

      Returns:
      true if the current module declares Folia support; false otherwise

    • getLoadPhase

      default GravesXModuleController.LoadPhase getLoadPhase(String moduleKey)
      Convenience accessor for getModule(moduleKey).getLoadPhase().

      This reflects the module load phase parsed from module.yml (or host defaults). If the module cannot be found, this returns GravesXModuleController.LoadPhase.STARTUP.

      Parameters:
      moduleKey - identifier for the target module
      Returns:
      the target module load phase (never null)

    • getLoadPhase

      default GravesXModuleController.LoadPhase getLoadPhase()
      Convenience accessor for getThisModule().getLoadPhase().

      This reflects this module's load phase parsed from module.yml (or host defaults). If unset, this returns GravesXModuleController.LoadPhase.STARTUP.

      Returns:
      the current module load phase (never null)