Package cn.lunadeer.dominion.api

Class DominionAPI

java.lang.Object
cn.lunadeer.dominion.api.DominionAPI
public abstract class DominionAPI extends Object
Entry point for the public Dominion API.

The API exposes read-only cache access, privilege checks, provider instances, and a small number of maintenance operations. It is initialized by the Dominion plugin during startup.

Use the getInstance() method to retrieve the singleton instance of the DominionAPI.

  • Field Details

    • instance

      protected static DominionAPI instance
      The API instance initialized by the Dominion plugin.

  • Constructor Details

    • DominionAPI

      public DominionAPI()

  • Method Details

    • getInstance

      public static DominionAPI getInstance()
      Returns the Dominion API instance initialized by the plugin.

      This method does not load or enable the Dominion plugin. Call it after declaring Dominion as a dependency in plugin.yml and after the plugin has been enabled.

      Returns:
      the singleton instance of the DominionAPI

    • getPlayer

      @Nullable public abstract @Nullable PlayerDTO getPlayer(String name)
      Retrieves a PlayerDTO by the player's name.
      Parameters:
      name - the name of the player
      Returns:
      the PlayerDTO associated with the given name, or null if not found

    • getPlayer

      @Nullable public abstract @Nullable PlayerDTO getPlayer(@NotNull @NotNull UUID player)
      Retrieves a PlayerDTO by the player's UUID.
      Parameters:
      player - the UUID of the player
      Returns:
      the PlayerDTO associated with the given UUID, or null if not found

    • getPlayerName

      @NotNull public abstract @NotNull String getPlayerName(@NotNull @NotNull UUID uuid)
      Retrieves the cached name of a player by their UUID.
      Parameters:
      uuid - the UUID of the player
      Returns:
      the cached name, or an implementation-defined placeholder when the player is unknown

    • getAllDominions

      public abstract List<DominionDTO> getAllDominions()
      Retrieves all DominionDTO objects.

      This method retrieves all dominions from the cache of this server. If multi-servers mode is enabled, it also retrieves dominions from the caches of other servers.

      Returns:
      a list of all DominionDTO objects

    • getAllDominionsOfPlayer

      public abstract List<DominionDTO> getAllDominionsOfPlayer(@NotNull @NotNull UUID player)
      Retrieves all dominions owned by a specific player.

      In multi-server mode, the result can include dominions cached for other servers.

      Parameters:
      player - the UUID of the player
      Returns:
      a list of DominionDTO objects owned by the specified player

    • getChildrenDominionOf

      public abstract List<DominionDTO> getChildrenDominionOf(DominionDTO parent)
      Retrieves the direct child dominions of a given parent dominion.

      In multi-server mode, the result can include children cached for other servers.

      Parameters:
      parent - the parent DominionDTO whose children are to be retrieved
      Returns:
      a list of child DominionDTO objects

    • getDominion

      @Nullable public abstract @Nullable DominionDTO getDominion(Integer id)
      Retrieves a DominionDTO by its ID.

      This method will first attempt to retrieve the DominionDTO from the cache of this server. If the DominionDTO is not found, it will then attempt to retrieve the DominionDTO from the caches of other servers.

      Parameters:
      id - the ID of the dominion to retrieve
      Returns:
      the DominionDTO associated with the given ID

    • getDominion

      @Nullable public abstract @Nullable DominionDTO getDominion(String name)
      Retrieves a DominionDTO by its name.

      This method will first attempt to retrieve the DominionDTO from the cache of this server. If the DominionDTO is not found, it will then attempt to retrieve the DominionDTO from the caches of other servers.

      Parameters:
      name - the name of the dominion to retrieve
      Returns:
      the DominionDTO associated with the given name

    • getDominion

      @Nullable public abstract @Nullable DominionDTO getDominion(org.bukkit.Location location)
      Retrieves a DominionDTO by its location.

      This method retrieves the DominionDTO associated with the given location from the cache of this server.

      Parameters:
      location - the location to retrieve the dominion for
      Returns:
      the DominionDTO associated with the given location, or null if not found

    • getPlayerOwnDominionDTOs

      public abstract List<DominionDTO> getPlayerOwnDominionDTOs(UUID player)
      Retrieves the dominions owned by a player.

      This method retrieves the dominions owned by the player from the cache of this server. If multi-servers mode is enabled, it also retrieves the dominions owned by the player from the caches of other servers.

      Parameters:
      player - the UUID of the player
      Returns:
      a list of DominionDTO objects representing the dominions owned by the player

    • getPlayerAdminDominionDTOs

      public abstract List<DominionDTO> getPlayerAdminDominionDTOs(UUID player)
      Retrieves the dominions where a player is an admin.

      This method retrieves the dominions where the player is an admin from the cache of this server. If multi-servers mode is enabled, it also retrieves the dominions where the player is an admin from the caches of other servers.

      Parameters:
      player - the UUID of the player
      Returns:
      a list of DominionDTO objects representing the dominions where the player is an admin

    • getMember

      @Nullable public abstract @Nullable MemberDTO getMember(@Nullable @Nullable DominionDTO dominion, @NotNull @NotNull org.bukkit.entity.Player player)
      Retrieves a member by a Bukkit player object.

      This overload uses the player's UUID and is equivalent to the UUID overload.

      Parameters:
      dominion - the DominionDTO to retrieve the member from
      player - the Player object representing the player
      Returns:
      the MemberDTO associated with the given player, or null if not found

    • getMember

      @Nullable public abstract @Nullable MemberDTO getMember(@Nullable @Nullable DominionDTO dominion, @NotNull @NotNull UUID player)
      Retrieves a MemberDTO by the player's UUID.

      This method retrieves the MemberDTO associated with the given player from the specified dominion. If the member is not found in the cache of this server, it will attempt to retrieve the member from the caches of other servers if multi-servers mode is enabled.

      Parameters:
      dominion - the DominionDTO to retrieve the member from
      player - the UUID of the player
      Returns:
      the MemberDTO associated with the given player, or null if not found

    • getGroup

      @Nullable public abstract @Nullable GroupDTO getGroup(MemberDTO member)
      Retrieves the group to which a member belongs.

      A member whose group ID is -1, or whose group cannot be found, produces a null result.

      Parameters:
      member - the MemberDTO whose group ID is to be used for retrieval
      Returns:
      the GroupDTO associated with the given member's group ID, or null if not found

    • getGroup

      @Nullable public abstract @Nullable GroupDTO getGroup(Integer id)
      Retrieves a GroupDTO by its ID.

      This method retrieves the GroupDTO associated with the given ID from the cache of this server. If the GroupDTO is not found, it will then attempt to retrieve the GroupDTO from the caches of other servers if multi-servers mode is enabled.

      Parameters:
      id - the ID of the group to retrieve
      Returns:
      the GroupDTO associated with the given ID, or null if not found

    • getPlayerCurrentDominion

      @Nullable public abstract @Nullable DominionDTO getPlayerCurrentDominion(@NotNull @NotNull org.bukkit.entity.Player player)
      Resolves and updates the dominion currently containing a player.

      The lookup is based on the player's current location. When the result changes, the corresponding enter, leave, or border-crossing events are fired and the cached current-dominion value is updated.

      Parameters:
      player - the Player object representing the player
      Returns:
      the DominionDTO associated with the player's current location, or null if not found

    • resetPlayerCurrentDominionId

      public abstract void resetPlayerCurrentDominionId(@NotNull @NotNull org.bukkit.entity.Player player)
      Resets the current dominion ID for a player.

      This method removes the current dominion ID associated with the player from the cache.

      Parameters:
      player - the Player object representing the player

    • dominionCount

      public abstract Integer dominionCount()
      Retrieves the total number of dominions visible to this server.

      This method calculates the total number of dominions by summing the count of dominions on this server and, if multi-servers mode is enabled, the counts from other servers.

      Returns:
      the total count of dominions

    • groupCount

      public abstract Integer groupCount()
      Retrieves the total number of groups visible to this server.

      This method calculates the total number of groups by summing the count of groups on this server and, if multi-servers mode is enabled, the counts from other servers.

      Returns:
      the total count of groups

    • memberCount

      public abstract Integer memberCount()
      Retrieves the total number of members visible to this server.

      This method calculates the total number of members by summing the count of members on this server and, if multi-servers mode is enabled, the counts from other servers.

      Returns:
      the total count of members

    • checkPrivilegeFlag

      public abstract boolean checkPrivilegeFlag(@NotNull @NotNull org.bukkit.Location location, @NotNull @NotNull PriFlag flag, @NotNull @NotNull org.bukkit.entity.Player player)
      Checks if a player has a specific privilege flag at the given location.

      This method verifies whether the player has permission for the specified privilege flag at the given location, considering the dominion (if any) that covers the location. If the player lacks the required privilege, appropriate messages or events may be triggered.

      Parameters:
      location - the location to check the privilege flag at
      flag - the privilege flag to check
      player - the player whose privileges are being checked
      Returns:
      true if the player has the privilege flag at the location, false otherwise

    • checkPrivilegeFlag

      public abstract boolean checkPrivilegeFlag(@Nullable @Nullable DominionDTO dom, @NotNull @NotNull PriFlag flag, @NotNull @NotNull org.bukkit.entity.Player player)
      Checks if a player has a specific privilege flag for the given dominion.

      This method verifies whether the player has permission for the specified privilege flag within the provided dominion. If the dominion is null, the check may be performed in a global or default context.

      Since 4.5.0 you should use checkPrivilegeFlag(Location, PriFlag, Player) instead, because this method does not check the world-wide privilege flag, which is not recommended to use.

      Parameters:
      dom - the DominionDTO to check the privilege flag in, or null if not applicable
      flag - the privilege flag to check
      player - the player whose privileges are being checked
      Returns:
      true if the player has the privilege flag in the dominion, false otherwise

    • checkPrivilegeFlagSilence

      public abstract boolean checkPrivilegeFlagSilence(@NotNull @NotNull org.bukkit.Location location, @NotNull @NotNull PriFlag flag, @NotNull @NotNull org.bukkit.entity.Player player)
      Checks if a player has a specific privilege flag at the given location without triggering messages or events.

      This method performs the same privilege check as checkPrivilegeFlag(Location, PriFlag, Player) but operates silently, without sending any messages to the player or triggering related events. This is useful for internal checks where user feedback is not desired.

      Parameters:
      location - the location to check the privilege flag at
      flag - the privilege flag to check
      player - the player whose privileges are being checked
      Returns:
      true if the player has the privilege flag at the location, false otherwise

    • checkPrivilegeFlagSilence

      public abstract boolean checkPrivilegeFlagSilence(@Nullable @Nullable DominionDTO dom, @NotNull @NotNull PriFlag flag, @NotNull @NotNull org.bukkit.entity.Player player)
      Checks if a player has a specific privilege flag for the given dominion without triggering messages or events.

      This method performs a silent privilege check for the specified dominion, privilege flag, and player. No messages are sent and no events are triggered, making it suitable for internal permission checks.

      Since 4.5.0 you should use checkPrivilegeFlagSilence(Location, PriFlag, Player) instead, because this method does not check the world-wide privilege flag, which is not recommended to use.

      Parameters:
      dom - the DominionDTO to check the privilege flag in, or null if not applicable
      flag - the privilege flag to check
      player - the player whose privileges are being checked
      Returns:
      true if the player has the privilege flag in the dominion, false otherwise

    • checkEnvironmentFlag

      public abstract boolean checkEnvironmentFlag(@NotNull @NotNull org.bukkit.Location location, @NotNull @NotNull EnvFlag flag)
      Checks if the specified environment flag is set at the given location.

      This method determines whether the provided environment flag is enabled at the specified location, considering the dominion (if any) that covers the location.

      Parameters:
      location - the location to check for the environment flag
      flag - the environment flag to check
      Returns:
      true if the environment flag is set at the location, false otherwise

    • checkEnvironmentFlag

      public abstract boolean checkEnvironmentFlag(@Nullable @Nullable DominionDTO dom, @NotNull @NotNull EnvFlag flag)
      Checks if the specified environment flag is set for the given dominion.

      This method determines whether the provided environment flag is enabled for the specified dominion.

      Since 4.5.0 you should use checkEnvironmentFlag(Location, EnvFlag) instead, because this method does not check the world-wide privilege flag, which is not recommended to use.

      Parameters:
      dom - the DominionDTO to check for the environment flag, or null if not applicable
      flag - the environment flag to check
      Returns:
      true if the environment flag is set for the dominion, false otherwise

    • getDominionProvider

      public static DominionProvider getDominionProvider()
      Retrieves the provider for dominion operations.

      This method provides access to the DominionProvider, which handles dominion-related operations such as creating, updating, and deleting dominions.

      Returns:
      the singleton instance of DominionProvider

    • getGroupProvider

      public static GroupProvider getGroupProvider()
      Retrieves the provider for group operations.

      This method provides access to the GroupProvider, which handles group-related operations such as creating, updating, and deleting groups within dominions.

      Returns:
      the singleton instance of GroupProvider

    • getMemberProvider

      public static MemberProvider getMemberProvider()
      Retrieves the provider for member operations.

      This method provides access to the MemberProvider, which handles member-related operations such as adding, updating, and removing members from dominions and groups.

      Returns:
      the singleton instance of MemberProvider

    • getTemplateProvider

      public static TemplateProvider getTemplateProvider()
      Retrieves the provider for player-owned privilege templates.
      Returns:
      the singleton TemplateProvider instance

    • getCopyProvider

      public static CopyProvider getCopyProvider()
      Retrieves the provider for copying management data between dominions.
      Returns:
      the singleton CopyProvider instance

    • getPlayerProvider

      public static PlayerProvider getPlayerProvider()
      Retrieves the provider for player data and group-title operations.
      Returns:
      the singleton PlayerProvider instance

    • getTeleportProvider

      public static TeleportProvider getTeleportProvider()
      Retrieves the provider for dominion teleportation.
      Returns:
      the singleton TeleportProvider instance

    • reloadCache

      public abstract void reloadCache()
      Reloads the dominion cache.

      This method refreshes all cached dominion data, ensuring the latest state is loaded from the data source. Use this when external changes may have affected the cache.

    • reloadConfig

      public abstract void reloadConfig() throws Exception
      Reloads the Dominion configuration and related runtime state.

      This method reloads configuration files and settings for the dominion system. Use this to apply changes made to configuration files without restarting the server.

      Throws:
      Exception - if configuration or database reloading fails

    • applyFlagChanges

      public abstract CompletableFuture<Void> applyFlagChanges()
      Applies pending custom flag and flag-group changes. Calls made in the same server tick may share one application pass.
      Returns:
      a future completed after the pass containing this request finishes

    • getMcaWhiteListInitiative

      public abstract List<McaRecord> getMcaWhiteListInitiative()
      Exports and retrieves the active MCA whitelist.

      The active whitelist is regenerated by the plugin before it is returned.

      Returns:
      the current list of whitelisted MCA regions

    • getMcaWhiteListPassive

      public abstract List<McaRecord> getMcaWhiteListPassive()
      Retrieves the passive MCA whitelist from the cache.

      This method does not trigger an export. The returned value depends on whether the cache has already been populated, for example by /dom export mca.

      Returns:
      the cached list of whitelisted MCA regions