Package com.ultikits.ultitools.api

Class UltiToolsAPI

java.lang.Object
com.ultikits.ultitools.api.UltiToolsAPI
public final class UltiToolsAPI extends Object
Public API for external Bukkit plugins to integrate with UltiTools framework.

Usage: 

 public class MyPlugin extends JavaPlugin {
     public void onEnable() {
         UltiToolsAPI.connect(this);
     }
     public void onDisable() {
         UltiToolsAPI.disconnect(this);
     }
 }
Since:
6.2.2

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private static final Map<org.bukkit.plugin.java.JavaPlugin,ExternalPluginAdapter>
    adapters
     

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    private
    UltiToolsAPI()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    static void
    connect(org.bukkit.plugin.java.JavaPlugin plugin)
    Connect an external Bukkit plugin to UltiTools framework.
    static void
    connect(org.bukkit.plugin.java.JavaPlugin plugin, Class<?>... additionalEntities)
    Connect an external Bukkit plugin to UltiTools framework, declaring entity classes that legitimately live outside the plugin's own JAR (D-19) -- a shared library JAR, or a multi-module build's common artifact.
    static void
    disconnect(org.bukkit.plugin.java.JavaPlugin plugin)
    Disconnect an external Bukkit plugin from UltiTools framework.
    static void
    disconnectAll()
    Disconnect all external plugins.
    (package private) static ExternalPluginAdapter
    getAdapter(org.bukkit.plugin.java.JavaPlugin plugin)
     
    static <T extends BaseDataEntity<String>>
    DataOperator<T>
    getDataOperator(org.bukkit.plugin.java.JavaPlugin plugin, Class<T> dataEntity)
    Get a DataOperator for an external plugin's data entity.
    static EventBus
    getEventBus()
    Get the UltiTools EventBus for inter-plugin communication.
    static boolean
    isConnected(org.bukkit.plugin.java.JavaPlugin plugin)
    Check if a plugin is connected.
    static void
    onPluginDisable(org.bukkit.plugin.java.JavaPlugin plugin)
    Auto-disconnect a plugin when it is disabled.
    (package private) static void
    registerAdapter(org.bukkit.plugin.java.JavaPlugin plugin, ExternalPluginAdapter adapter)
     
    (package private) static void
    removeAdapter(org.bukkit.plugin.java.JavaPlugin plugin)
     
    (package private) static void
    reset()
    Reset all state.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

  • Constructor Details

    • UltiToolsAPI

      private UltiToolsAPI()

  • Method Details

    • connect

      public static void connect(org.bukkit.plugin.java.JavaPlugin plugin)
      Connect an external Bukkit plugin to UltiTools framework. Scans the plugin's package for @Service, @CmdExecutor, @EventListener, etc.
      Parameters:
      plugin - the external JavaPlugin to connect
      Throws:
      IllegalStateException - if UltiTools is not loaded

    • connect

      public static void connect(org.bukkit.plugin.java.JavaPlugin plugin, Class<?>... additionalEntities)
      Connect an external Bukkit plugin to UltiTools framework, declaring entity classes that legitimately live outside the plugin's own JAR (D-19) -- a shared library JAR, or a multi-module build's common artifact. The plugin's own JAR is always scanned for @Table classes automatically; additionalEntities is additive to that scan, not a replacement for it. The single-argument connect(JavaPlugin) overload is unchanged and delegates here with an empty array.

      additionalEntities is validated, not trusted (02-14). Each class must live on plugin's own classpath -- either its own JAR, or a jar/module not already known to belong to a different, currently-loaded plugin. A class that structurally belongs to a DIFFERENT plugin (its own JAR, or one already recorded as owned by another plugin) is refused with an IllegalStateException wrapping a com.ultikits.ultitools.exceptions.PluginModuleException, and no partial registration is left behind -- additionalEntities cannot be used to obtain a working DataOperator for another plugin's entity, only to declare entities this plugin genuinely owns but does not package.

      Parameters:
      plugin - the external JavaPlugin to connect
      additionalEntities - entity classes owned by this plugin that live outside its own JAR
      Throws:
      IllegalStateException - if UltiTools is not loaded, or if an entity in additionalEntities does not live on plugin's own classpath (02-14)
      Since:
      6.3.0

    • disconnect

      public static void disconnect(org.bukkit.plugin.java.JavaPlugin plugin)
      Disconnect an external Bukkit plugin from UltiTools framework.
      Parameters:
      plugin - the external JavaPlugin to disconnect

    • getDataOperator

      public static <T extends BaseDataEntity<String>> DataOperator<T> getDataOperator(org.bukkit.plugin.java.JavaPlugin plugin, Class<T> dataEntity)
      Get a DataOperator for an external plugin's data entity. Data is stored in the plugin's own data folder. Refuses outright if dataEntity is not registered to plugin (D-14) -- checked against the same DataScope minted for this plugin at connect(...) time, via the same refusal DataStore.getOperator(DataScope, Class) builds, so the exception type, error code, and message shape are identical regardless of which entry point a caller reaches.

      02-13 (CR-03): before this, scope.owns(...) was checked here inline and this method then delegated to the deprecated getOperator(File, Class) overload directly -- so DataStore.getOperator(DataScope, Class), the method D-17/02-07 built specifically as the credential-typed supported path, had zero real callers anywhere in the framework. This now routes through it, so production actually uses the path it was built for. scope is normally non-null by the time a connected plugin calls this (set by PluginManager.registerExternal right after minting); the null fallback below only covers an adapter that predates that wiring, where the deprecated overload's own checkOwnership(...) call still refuses correctly on its own.

      Type Parameters:
      T - entity type
      Parameters:
      plugin - the external JavaPlugin
      dataEntity - the data entity class (must have @Table annotation)
      Returns:
      data operator
      Throws:
      DataAccessException - if dataEntity is not registered to plugin

    • getEventBus

      public static EventBus getEventBus()
      Get the UltiTools EventBus for inter-plugin communication.
      Returns:
      the EventBus instance

    • isConnected

      public static boolean isConnected(org.bukkit.plugin.java.JavaPlugin plugin)
      Check if a plugin is connected.
      Parameters:
      plugin - the plugin to check
      Returns:
      true if connected

    • getAdapter

      static ExternalPluginAdapter getAdapter(org.bukkit.plugin.java.JavaPlugin plugin)

    • registerAdapter

      static void registerAdapter(org.bukkit.plugin.java.JavaPlugin plugin, ExternalPluginAdapter adapter)

    • removeAdapter

      static void removeAdapter(org.bukkit.plugin.java.JavaPlugin plugin)

    • reset

      static void reset()
      Reset all state. For testing only.

    • onPluginDisable

      public static void onPluginDisable(org.bukkit.plugin.java.JavaPlugin plugin)
      Auto-disconnect a plugin when it is disabled. Called by the PluginDisableEvent listener in PluginManager.
      Parameters:
      plugin - the plugin being disabled
      Since:
      6.2.2

    • disconnectAll

      public static void disconnectAll()
      Disconnect all external plugins. Called during UltiTools shutdown.
      Since:
      6.2.2