Package net.joseplay.allianceutils.api.playerProfile.data

Class PlayerProfileManager

java.lang.Object
net.joseplay.allianceutils.api.playerProfile.data.PlayerProfileManager
public class PlayerProfileManager extends Object
Manages PlayerProfile lifecycle, including caching, synchronization, persistence, and cross-server updates.

Core design principles:

  • Profiles are never exposed directly (only immutable snapshots)
  • All mutations must go through modify(UUID, Consumer)
  • Thread-safety is enforced via per-profile locks
  • Persistence is asynchronous and batched

Caching:

  • Backed by Caffeine LoadingCache
  • Entries expire after inactivity
  • Maximum size is bounded

Concurrency model:

  • Each profile has its own ReentrantReadWriteLock
  • Reads use snapshots (no shared mutable state)
  • Writes are exclusive and rate-limited

Data integrity:

  • Changes are detected via JSON diff
  • Only modified profiles are persisted
  • Dirty flag ensures retry on failure

Warning:

  • Snapshots are deep-copied via JSON (performance cost)
  • No strong consistency across servers (eventual consistency)

  • Constructor Details

    • PlayerProfileManager

      public PlayerProfileManager()

  • Method Details

    • getPlayer

      @Deprecated @NotNull public @NotNull PlayerProfile getPlayer(@NotNull @NotNull UUID uuid)
      Deprecated.
      Retorna apenas SNAPSHOT (somente leitura)

    • getSnapshot

      @NotNull public @NotNull PlayerProfile getSnapshot(@NotNull @NotNull UUID uuid)
      Returns an immutable snapshot of the player's profile.

      The returned object is a deep copy and must not be used for mutations.

      Parameters:
      uuid - player UUID
      Returns:
      immutable snapshot

    • modify

      public void modify(@NotNull @NotNull UUID uuid, @NotNull @NotNull Consumer<PlayerProfile> modifier)
      Applies a mutation to the player's profile in a thread-safe manner.

      Execution flow:

      1. Global rate limit check
      2. Acquire write lock
      3. Apply mutation
      4. Detect changes via JSON comparison
      5. Mark as dirty if changed
      6. Dispatch async update to other servers
      7. Schedule async persistence

      Failure cases:

      • Rate limit exceeded → modification is ignored
      • Lock not acquired → modification is skipped
      Parameters:
      uuid - player UUID
      modifier - mutation logic

    • shutdown

      public void shutdown()
      Flushes all dirty profiles and shuts down the persistence executor.

      Warning: Failure here may result in data loss.

    • applyRemoteUpdate

      public void applyRemoteUpdate(@NotNull @NotNull UUID uuid, @NotNull @NotNull String json)
      Applies a remote update received from another server.

      This overwrites the local profile state.

      Parameters:
      uuid - player UUID
      json - serialized profile

    • saveNow

      public void saveNow(@NotNull @NotNull UUID uuid)
      Forces immediate persistence of a profile if present in cache.

      This operation is synchronous and blocks the current thread.

      Parameters:
      uuid - player UUID

    • loadOnJoin

      public void loadOnJoin(UUID uuid)
      Preloads a profile into cache (typically on player join).
      Parameters:
      uuid - player UUID

    • unloadOnQuit

      public void unloadOnQuit(UUID uuid)
      Saves and removes a profile from active usage (typically on player quit).
      Parameters:
      uuid - player UUID