Package de.marcely.bedwars.api.player

Interface PlayerDataAPI

public interface PlayerDataAPI

  • Method Details

    • getStats

      default void getStats(OfflinePlayer player, Consumer<PlayerStats> callback)
      Tries to fetch the stats of the player.

      Result may gets cached for quick access in the future. Callback will never return a null value.

      Parameters:
      player - The player who owns the stats
      callback - Stats will be given to this callback

    • getStats

      void getStats(UUID id, Consumer<PlayerStats> callback)
      Tries to fetch the stats of the player.

      Result may gets cached for quick access in the future. Callback will never return a null value.

      Parameters:
      id - The UUID of the player who owns the stats
      callback - Stats will be given to this callback

    • getStatsByName

      void getStatsByName(String name, Consumer<Optional<PlayerStats>> callback)
      Tries to fetch the stats of the player given by its name.

      Casing of the name doesn't have to be exactly equally. Result may gets cached for quick access in the future. Callback might return a null value in case there is no info about a player with that given name.

      Parameters:
      name - The name of the player
      callback - Stats will be given to this callback

    • getStatsCached

      default Optional<PlayerStats> getStatsCached(OfflinePlayer player)
      Tries to get stats from the cache.

      Returns an empty optional when they haven't been loaded yet. This method also does not automatically load them, you must call getStats(OfflinePlayer, Consumer) to explicitly load them.

      Parameters:
      player - The player who owns the properties
      Returns:
      The stats of the player. Maybe empty if they aren't being cached

    • getStatsCached

      Optional<PlayerStats> getStatsCached(UUID id)
      Tries to get stats from the cache.

      Returns an empty optional when they haven't been loaded yet. This method also does not automatically load them, you must call getStats(UUID, Consumer) to explicitly load them.

      Parameters:
      id - The UUID of the player who owns the properties
      Returns:
      The stats of the player. Maybe empty if they aren't being cached

    • getCachedStats

      Collection<PlayerStats> getCachedStats()
      Gets a collection of all currently cached player stats.
      Returns:
      An immutable collection of currently cached achievements

    • getAchievements

      default void getAchievements(OfflinePlayer player, Consumer<PlayerAchievements> callback)
      Tries to fetch the achievements info of the player.

      Result may gets cached for quick access in the future. Callback will never return a null value.

      Parameters:
      player - The player who owns the achievements
      callback - Result will be given to this callback

    • getAchievements

      void getAchievements(UUID id, Consumer<PlayerAchievements> callback)
      Tries to fetch the achievement info of the player.

      Result may gets cached for quick access in the future. Callback will never return a null value.

      Parameters:
      id - The UUID of the player who owns the achievements
      callback - Result will be given to this callback

    • getAchievementsCached

      default Optional<PlayerAchievements> getAchievementsCached(OfflinePlayer player)
      Tries to get achievements from the cache.

      Returns an empty optional when they haven't been loaded yet. This method also does not automatically load them, you must call getAchievements(OfflinePlayer, Consumer) to explicitly load them.

      Parameters:
      player - The player who owns the properties
      Returns:
      The achievements of the player. Maybe empty if they aren't being cached

    • getAchievementsCached

      Optional<PlayerAchievements> getAchievementsCached(UUID id)
      Tries to get achievements from the cache.

      Returns an empty optional when they haven't been loaded yet. This method also does not automatically load them, you must call getAchievements(UUID, Consumer) to explicitly load them.

      Parameters:
      id - The UUID of the player who owns the properties
      Returns:
      The achievements of the player. Maybe empty if they aren't being cached

    • getCachedAchievements

      Collection<PlayerAchievements> getCachedAchievements()
      Gets a collection of all currently cached properties achievements.
      Returns:
      An immutable collection of currently cached achievements

    • getProperties

      default void getProperties(OfflinePlayer player, Consumer<PlayerProperties> callback)
      Tries to fetch the properties of the player.

      Result may gets cached for quick access in the future. Callback will never return a null value.

      Parameters:
      player - The player who owns the properties
      callback - Result will be given to this callback

    • getProperties

      void getProperties(UUID id, Consumer<PlayerProperties> callback)
      Tries to fetch the properties of the player.

      Result may gets cached for quick access in the future. Callback will never return a null value.

      Parameters:
      id - The UUID of the player who owns the properties
      callback - Result will be given to this callback

    • getPropertiesCached

      default Optional<PlayerProperties> getPropertiesCached(OfflinePlayer player)
      Tries to get properties from the cache.

      Returns an empty optional when they haven't been loaded yet. This method also does not automatically load them, you must call getProperties(OfflinePlayer, Consumer) to explicitly load them.

      Parameters:
      player - The player who owns the properties
      Returns:
      The properties of the player. Maybe empty if they aren't being cached

    • getPropertiesCached

      Optional<PlayerProperties> getPropertiesCached(UUID id)
      Tries to get properties from the cache.

      Returns an empty optional when they haven't been loaded yet. This method also does not automatically load them, you must call getProperties(UUID, Consumer) to explicitly load them.

      Parameters:
      id - The UUID of the player who owns the properties
      Returns:
      The properties of the player. Maybe empty if they aren't being cached

    • getCachedProperties

      Collection<PlayerProperties> getCachedProperties()
      Gets a collection of all currently cached player properties.
      Returns:
      An immutable collection of currently cached properties

    • getRegisteredStatSets

      Collection<PlayerStatSet> getRegisteredStatSets()
      Returns all registered data sets for stats.
      Returns:
      All registered data sets

    • getStatsDataSet

      Optional<PlayerStatSet> getStatsDataSet(String id)
      Searches for the data set with that id and returns it.
      Parameters:
      id - The id of that data set
      Returns:
      Its instance

    • registerStatSet

      void registerStatSet(PlayerStatSet dataSet)
      Tries to register this data set and make it display everywhere in the plugin.
      Parameters:
      dataSet - The data set that shall be added
      Throws:
      IllegalStateException - If there's already a data set with the same id

    • unregisterStatSet

      boolean unregisterStatSet(PlayerStatSet dataSet)
      Tries to register this data set.
      Parameters:
      dataSet - The data set that shall be removed
      Returns:
      true if it has been unregistered/removed, otherwise false

    • getStatsSet

      @Nullable @Nullable PlayerStatSet getStatsSet(String id)
      Returns the stats set with the given id.
      Parameters:
      id - This id of the stats set we are trying to get
      Returns:
      the stats set with the corresponding id. Returns null if there is no stats set with the given id

    • fetchAllStoredUUIDs

      CloseableIterator<UUID> fetchAllStoredUUIDs()
      Fetches all uuids of players that are known for this plugin.

      This method may not match the OfflinePlayer ones and likely contains less or more than there. MBedwars only stores uuids of relevant players. A player is relevant in case there is any info available that needs to be stored for either of its stats, achievements or properties.

      This fetch is not being executed async on a separate thread. It will be done in the same thread in which this method is being called!!

      Also it is very important that you call Closeable.close() once you are done.

      Returns:
      An iterator for going through all known uuids

    • purgePlayerData

      void purgePlayerData(UUID uuid, boolean stats, boolean achievements, boolean properties, boolean cacheOnly, @Nullable @Nullable Consumer<Boolean> callback)
      Purges stored and cached data from a certain player. DANGEROUS METHOD!

      Calls PlayerDataPurgeEvent. Plugins using the API may cancel it if they want to.

      Parameters:
      uuid - The uuid of the player
      stats - Whether stats shall be purged
      achievements - Whether achievements shall be purged
      properties - Whether properties shall be purged
      cacheOnly - true: Only local cache updated, false: Local cache of all servers, permanent database get affected
      callback - Optional callback. Gets called on the main thread. Includes info whether it was successful or not

    • purgeAllPlayerData

      void purgeAllPlayerData(boolean stats, boolean achievements, boolean properties, boolean cacheOnly, @Nullable @Nullable Consumer<Boolean> callback)
      Purges stored and cached data from ALL (!!) players. VERY DANGEROUS METHOD!

      Calls PlayerDataPurgeEvent. Plugins using the API may cancel it if they want to.

      Parameters:
      stats - Whether stats shall be purged
      achievements - Whether achievements shall be purged
      properties - Whether properties shall be purged
      cacheOnly - true: Only local cache updated, false: Local cache of all servers, permanent database get affected
      callback - Optional callback. Gets called on the main thread. Includes info whether it was successful or not

    • purgeAllPlayerData

      void purgeAllPlayerData(Set<String> statSetIds, boolean achievements, boolean properties, boolean cacheOnly, @Nullable @Nullable Consumer<Boolean> callback)
      Purges stored and cached data from ALL (!!) players. VERY DANGEROUS METHOD!

      Calls PlayerDataPurgeEvent. Plugins using the API may cancel it if they want to.

      Parameters:
      statSetIds - The ids of the stat sets that shall be purged
      achievements - Whether achievements shall be purged
      properties - Whether properties shall be purged
      cacheOnly - true: Only local cache updated, false: Local cache of all servers, permanent database get affected
      callback - Optional callback. Gets called on the main thread. Includes info whether it was successful or not

    • fetchLeaderboard

      void fetchLeaderboard(PlayerStatSet statSet, int minRank, int maxRank, Consumer<LeaderboardFetchResult> callback)
      Fetches players at the given ranks at the leaderboard.

      This causes a direct call to the database. It only makes use of what it is currently saved. Meaning that the rank might be slightly off due to temporal factors, as the local cache of all players possibly hasn't been pushed yet to the database.

      Parameters:
      statSet - The stat set according to which we want to order the players
      minRank - The minimum rank that we want to fetch. Must be at least 1
      maxRank - The maximum rank that we want to fetch
      callback - The callback that is being used to deliver the result. Always on the main thread
      Throws:
      IllegalArgumentException - In case minRank is less than 1 or greater than maxRank
      IllegalArgumentException - If the stat set is not registered

    • fetchLeaderboardPosition

      void fetchLeaderboardPosition(UUID playerUUID, PlayerStatSet statSet, Consumer<Integer> callback)
      Fetches the position of a player on the leaderboard.

      This causes a direct call to the database. It only makes use of what it is currently saved. Meaning that the rank might be slightly off due to temporal factors, as the local cache of all players possibly hasn't been pushed yet to the database.

      Parameters:
      playerUUID - The UUID of the player
      statSet - The stat set according to which we want to order the players
      callback - The callback that is being used to deliver the result. Always on the main thread

    • fetchLeaderboardPosition

      default void fetchLeaderboardPosition(OfflinePlayer player, PlayerStatSet statSet, Consumer<Integer> callback)
      Fetches the position of a player on the leaderboard.

      This causes a direct call to the database. It only makes use of what it is currently saved. Meaning that the rank might be slightly off due to temporal factors, as the local cache of all players possibly hasn't been pushed yet to the database.

      Parameters:
      player - Tthe player
      statSet - The stat set according to which we want to order the players
      callback - The callback that is being used to deliver the result. Always on the main thread

    • isSQLServiceActive

      boolean isSQLServiceActive()
      Returns whether the plugin is currently connected to a SQL database.
      Returns:
      true when a stable database connection exists

    • openSQLConnection

      @Nullable @Nullable Connection openSQLConnection() throws SQLException
      Opens a new database connection (or takes one from the connection pool).

      Make sure to close it!

      Returns:
      null when it isn't connected to any database, otherwise the connection
      Throws:
      SQLException - An error that possibly occurred during that

    • getAchievementTypeById

      @Nullable @Nullable PlayerAchievement getAchievementTypeById(String id)
      Get an achievement by its id.
      Parameters:
      id - The id of the achievement
      Returns:
      The achievement with the given id. Returns null if there is no achievement with the given id

    • getRegisteredAchievementTypes

      Collection<PlayerAchievement> getRegisteredAchievementTypes()
      Get all existing achievements.
      Returns:
      A collection of all existing achievements

    • get

      static PlayerDataAPI get()
      Returns the global PlayerDataAPI instance.
      Returns:
      The global PlayerDataAPI instance