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

    • 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)

    • 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)