Interface FPlayerService

public interface FPlayerService
Central service for managing player data across the FlectonePulse plugin. Provides methods for retrieving, caching, and updating player information. Acts as a facade layer between platform-specific player adapters and data repositories, handling cache management and data synchronization.

Players can be retrieved using various identifiers such as UUID, name, IP address, database ID, or platform-specific player objects. The service maintains separate caches for online and offline players to optimize performance.

Since:
0.0.1
See Also:

  • Method Details

    • invalidate

      void invalidate()
      Invalidates all cached player data and reloads from scratch. Clears console player, all platform players, and empties the cache. Typically used during plugin reload or initialization.

    • invalidate

      void invalidate(@NonNull UUID uuid)
      Invalidates a specific player from all caches.
      Parameters:
      uuid - the UUID of the player to invalidate

    • invalidateCache

      void invalidateCache()
      Clears all cached player data from both online and offline caches. This operation removes all players from memory but does not affect the database.

    • loadOnlineCache

      void loadOnlineCache()
      Loads all online players from the database into the cache.

    • addConsole

      void addConsole()
      Adds the console player to the cache with configured console name. Creates a new console FPlayer if it doesn't exist, or ignores if already present.

    • saveOrUpdate

      @NonNull FPlayer saveOrUpdate(@NonNull UUID uuid, @NonNull String name, @Nullable String ip, boolean online)
      Saves or updates a player in the database.
      Parameters:
      uuid - the player's UUID
      name - the player's name
      ip - the player's IP address, can be null
      online - whether the player is currently online
      Returns:
      the created or updated FPlayer object with assigned database ID

    • addCache

      @NonNull FPlayer addCache(@NonNull FPlayer fPlayer)
      Adds a player to the online cache.
      Parameters:
      fPlayer - the player to add to cache
      Returns:
      the same player instance that was added

    • updateCache

      @NonNull FPlayer updateCache(FPlayer fPlayer)
      Updates an existing player in the cache. Preserves online/offline status based on which cache the player is in.
      Parameters:
      fPlayer - the player data to update in cache
      Returns:
      the same player instance that was updated

    • initialize

      void initialize(SocialService socialService, boolean reload)
      Initializes all online platform players by loading their data and dispatching PlayerLoadEvent. Players with cancelled events are invalidated from cache.
      Parameters:
      reload - whether this is a reload operation or initial startup

    • invalidateOfflineCache

      void invalidateOfflineCache(@NonNull UUID uuid)
      Removes a player from offline cache and optionally ensures online status for proxy players.
      Parameters:
      uuid - the UUID of the player to remove from offline cache

    • invalidateOnlineCache

      void invalidateOnlineCache(@NonNull UUID uuid)
      Removes a player from online cache.
      Parameters:
      uuid - the UUID of the player to remove from online cache

    • clearAndSave

      @NonNull FPlayer clearAndSave(@NonNull FPlayer fPlayer)
      Clears a player's online status and saves them to offline cache and database. Sets online to false, removes from online cache, updates database, and adds to offline cache.
      Parameters:
      fPlayer - the player to clear and save as offline
      Returns:
      the updated player with online=false

    • getFPlayer

      @NonNull FPlayer getFPlayer(int id)
      Gets a player by database ID. Returns console player if ID is -1.
      Parameters:
      id - the database ID of the player
      Returns:
      the player or console player if ID is -1

    • getConsole

      @NonNull FPlayer getConsole()
      Gets the console player instance.
      Returns:
      the console FPlayer

    • getFPlayer

      @NonNull FPlayer getFPlayer(@NonNull String name)
      Gets a player by name.
      Parameters:
      name - the player's name
      Returns:
      the player or UNKNOWN if not found

    • getFPlayer

      @NonNull FPlayer getFPlayer(InetAddress inetAddress)
      Gets a player by IP address.
      Parameters:
      inetAddress - the player's IP address
      Returns:
      the player or UNKNOWN if not found

    • getFPlayer

      @NonNull FPlayer getFPlayer(UUID uuid)
      Gets a player by UUID.
      Parameters:
      uuid - the player's UUID
      Returns:
      the player or UNKNOWN if not found

    • getFPlayer

      @NonNull FPlayer getFPlayer(FEntity fEntity)
      Gets a player from an FEntity by extracting its UUID.
      Parameters:
      fEntity - the entity to get the player for
      Returns:
      the player associated with the entity's UUID

    • getFPlayer

      @NonNull FPlayer getFPlayer(@NonNull Object platformPlayer)
      Gets a player from a platform-specific player object (Bukkit, Fabric, etc.). Handles console detection and creates temporary FPlayer for unknown players.
      Parameters:
      platformPlayer - the platform-specific player object
      Returns:
      the FPlayer, console player, or a temporary player if not found

    • getRandomFPlayer

      @NonNull FPlayer getRandomFPlayer()
      Gets a random online player from platform players.
      Returns:
      a random FPlayer or UNKNOWN if no players are online

    • getFPlayersByIp

      @NonNull List<FPlayer> getFPlayersByIp(String ip)
      Gets the list of players with the specified IP address.
      Parameters:
      ip - the IP address to filter players by
      Returns:
      list of players matching the IP, ordered by ID descending

    • findAllFPlayers

      @NonNull List<FPlayer> findAllFPlayers()
      Gets all players from the database.
      Returns:
      list of all FPlayers in the database

    • getOnlineFPlayers

      @NonNull List<FPlayer> getOnlineFPlayers()
      Gets all online players from the cache.
      Returns:
      list of online FPlayers from cache

    • getPlatformFPlayers

      @NonNull List<FPlayer> getPlatformFPlayers()
      Gets all online players that are actually connected to the platform. Filters cached online players by checking their actual platform online status.
      Returns:
      list of platform-verified online FPlayers

    • getFPlayersWithConsole

      @NonNull List<FPlayer> getFPlayersWithConsole()
      Gets all online players including the console player.
      Returns:
      list of online FPlayers plus console