Package me.kzlyth.api.history

Klasse HistoryAPI

java.lang.Object
me.kzlyth.api.history.HistoryAPI
public class HistoryAPI extends Object
API for retrieving punishment history entries from Zenith-Mod.

This API provides methods to access history entries (punishment cases) including:

  • Complete history for a user
  • History filtered by punishment type
  • History filtered by date range
  • History entries by case ID
  • Active punishments only
  • History entries by staff member

Database Compatibility: All methods in this API are fully compatible with H2, SQLite, MySQL, and MariaDB databases. The API automatically adapts to the configured database type from the configuration file.

Example usage: 


 ZenithAPI api = ZenithAPI.getInstance();
 if (api != null) {
     HistoryAPI historyAPI = api.getHistoryAPI();
     
     UUID uuid = UUID.fromString("123e4567-e89b-12d3-a456-426614174000");
     
     // Get complete history
     historyAPI.getHistory(uuid).thenAccept(history -> {
         getLogger().info("User has " + history.size() + " history entries");
         for (HistoryEntry entry : history) {
             getLogger().info("Case #" + entry.getCaseId() + ": " + entry.getPunishmentType());
         }
     });
     
     // Get active punishments
     historyAPI.getActiveHistory(uuid).thenAccept(active -> {
         getLogger().info("User has " + active.size() + " active punishments");
     });
     
     // Get history by type
     historyAPI.getHistoryByType(uuid, "BAN").thenAccept(bans -> {
         getLogger().info("User has been banned " + bans.size() + " times");
     });
 }
Seit:
1.2.3
Autor:
Zenith-Studios

  • Konstruktordetails

    • HistoryAPI

      public HistoryAPI(@NotNull @NotNull me.kzlyth.ZenithMod plugin, @NotNull @NotNull ZenithAPI api)
      Constructs a new HistoryAPI instance.
      Parameter:
      plugin - The plugin instance
      api - The main API instance

  • Methodendetails

    • getCaseById

      @NotNull public @NotNull CompletableFuture<HistoryEntry> getCaseById(int caseId)
      Gets a history entry (case) by its case ID.

      This is a convenience method that wraps getHistoryByCaseId(int) for simpler access. Returns the history entry associated with the specified case ID, or null if not found.

      Example: 

      
 historyAPI.getCaseById(123).thenAccept(caseEntry -> {
     if (caseEntry != null) {
         getLogger().info("Case #" + caseEntry.getCaseId() + ": " + caseEntry.getPunishmentType());
         getLogger().info("Target: " + caseEntry.getTargetName());
         getLogger().info("Staff: " + caseEntry.getStaffName());
         getLogger().info("Reason: " + caseEntry.getReason());
     } else {
         getLogger().info("Case not found");
     }
 });
      Parameter:
      caseId - The case ID to retrieve
      Gibt zurück:
      A CompletableFuture that completes with the history entry, or null if not found
      Siehe auch:

    • getHistory

      @NotNull public @NotNull CompletableFuture<List<HistoryEntry>> getHistory(@NotNull @NotNull UUID uuid)
      Gets the complete history list for a user.

      Returns all history entries (punishments, warnings, kicks, etc.) for the specified user, ordered by timestamp (most recent first).

      Example: 

      
 UUID uuid = UUID.fromString("123e4567-e89b-12d3-a456-426614174000");
 historyAPI.getHistory(uuid).thenAccept(history -> {
     getLogger().info("User has " + history.size() + " history entries");
     for (HistoryEntry entry : history) {
         getLogger().info("Case #" + entry.getCaseId() + ": " + 
             entry.getPunishmentType() + " - " + entry.getReason());
     }
 });
      Parameter:
      uuid - The UUID of the user
      Gibt zurück:
      A CompletableFuture that completes with a list of history entries

    • getHistory

      @NotNull public @NotNull CompletableFuture<List<HistoryEntry>> getHistory(@NotNull @NotNull String playerName)
      Gets the complete history list for a user.

      This is an overloaded method that accepts a player name instead of UUID. The player name will be resolved to a UUID first.

      Example: 

      
 historyAPI.getHistory("PlayerName").thenAccept(history -> {
     getLogger().info("User has " + history.size() + " history entries");
 });
      Parameter:
      playerName - The name of the player
      Gibt zurück:
      A CompletableFuture that completes with a list of history entries, or an empty list if the player doesn't exist

    • getHistoryByType

      @NotNull public @NotNull CompletableFuture<List<HistoryEntry>> getHistoryByType(@NotNull @NotNull UUID uuid, @NotNull @NotNull String punishmentType)
      Gets the history entries filtered by punishment type for a user.

      Returns only history entries matching the specified punishment type (e.g., "BAN", "MUTE", "WARN", "KICK").

      Example: 

      
 UUID uuid = UUID.fromString("123e4567-e89b-12d3-a456-426614174000");
 historyAPI.getHistoryByType(uuid, "BAN").thenAccept(bans -> {
     getLogger().info("User has been banned " + bans.size() + " times");
     for (HistoryEntry ban : bans) {
         getLogger().info("Ban #" + ban.getCaseId() + ": " + ban.getReason());
     }
 });
      Parameter:
      uuid - The UUID of the user
      punishmentType - The punishment type to filter by (e.g., "BAN", "MUTE", "WARN", "KICK")
      Gibt zurück:
      A CompletableFuture that completes with a list of history entries matching the type

    • getHistoryByType

      @NotNull public @NotNull CompletableFuture<List<HistoryEntry>> getHistoryByType(@NotNull @NotNull String playerName, @NotNull @NotNull String punishmentType)
      Gets the history entries filtered by punishment type for a user.

      This is an overloaded method that accepts a player name instead of UUID.

      Example: 

      
 historyAPI.getHistoryByType("PlayerName", "BAN").thenAccept(bans -> {
     getLogger().info("User has been banned " + bans.size() + " times");
 });
      Parameter:
      playerName - The name of the player
      punishmentType - The punishment type to filter by (e.g., "BAN", "MUTE", "WARN", "KICK")
      Gibt zurück:
      A CompletableFuture that completes with a list of history entries matching the type, or an empty list if the player doesn't exist

    • getHistoryByCaseId

      @NotNull public @NotNull CompletableFuture<HistoryEntry> getHistoryByCaseId(int caseId)
      Gets a specific history entry by its case ID.

      Example: 

      
 historyAPI.getHistoryByCaseId(123).thenAccept(entry -> {
     if (entry != null) {
         getLogger().info("Case #" + entry.getCaseId() + ": " + entry.getPunishmentType());
         getLogger().info("Target: " + entry.getTargetName());
         getLogger().info("Staff: " + entry.getStaffName());
         getLogger().info("Reason: " + entry.getReason());
     } else {
         getLogger().info("Case not found");
     }
 });
      Parameter:
      caseId - The case ID to retrieve
      Gibt zurück:
      A CompletableFuture that completes with the history entry, or null if not found

    • getActiveHistory

      @NotNull public @NotNull CompletableFuture<List<HistoryEntry>> getActiveHistory(@NotNull @NotNull UUID uuid)
      Gets only the active punishments for a user.

      Returns history entries where the punishment is still active (not expired or removed).

      Example: 

      
 UUID uuid = UUID.fromString("123e4567-e89b-12d3-a456-426614174000");
 historyAPI.getActiveHistory(uuid).thenAccept(active -> {
     getLogger().info("User has " + active.size() + " active punishments");
     for (HistoryEntry entry : active) {
         getLogger().info("Active " + entry.getPunishmentType() + ": " + entry.getReason());
     }
 });
      Parameter:
      uuid - The UUID of the user
      Gibt zurück:
      A CompletableFuture that completes with a list of active history entries

    • getActiveHistory

      @NotNull public @NotNull CompletableFuture<List<HistoryEntry>> getActiveHistory(@NotNull @NotNull String playerName)
      Gets only the active punishments for a user.

      This is an overloaded method that accepts a player name instead of UUID.

      Example: 

      
 historyAPI.getActiveHistory("PlayerName").thenAccept(active -> {
     getLogger().info("User has " + active.size() + " active punishments");
 });
      Parameter:
      playerName - The name of the player
      Gibt zurück:
      A CompletableFuture that completes with a list of active history entries, or an empty list if the player doesn't exist

    • getHistoryByStaff

      @NotNull public @NotNull CompletableFuture<List<HistoryEntry>> getHistoryByStaff(@NotNull @NotNull UUID staffUuid)
      Gets all history entries issued by a specific staff member.

      Returns all punishments, warnings, kicks, etc. that were issued by the specified staff member.

      Example: 

      
 UUID staffUuid = UUID.fromString("123e4567-e89b-12d3-a456-426614174000");
 historyAPI.getHistoryByStaff(staffUuid).thenAccept(history -> {
     getLogger().info("Staff member has issued " + history.size() + " punishments");
     for (HistoryEntry entry : history) {
         getLogger().info("Issued " + entry.getPunishmentType() + " to " + entry.getTargetName());
     }
 });
      Parameter:
      staffUuid - The UUID of the staff member
      Gibt zurück:
      A CompletableFuture that completes with a list of history entries issued by the staff member

    • getHistoryByStaff

      @NotNull public @NotNull CompletableFuture<List<HistoryEntry>> getHistoryByStaff(@NotNull @NotNull String playerName)
      Gets all history entries issued by a specific staff member.

      This is an overloaded method that accepts a player name instead of UUID.

      Example: 

      
 historyAPI.getHistoryByStaff("StaffMember").thenAccept(history -> {
     getLogger().info("Staff member has issued " + history.size() + " punishments");
 });
      Parameter:
      playerName - The name of the staff member
      Gibt zurück:
      A CompletableFuture that completes with a list of history entries issued by the staff member, or an empty list if the player doesn't exist

    • getHistoryByDateRange

      @NotNull public @NotNull CompletableFuture<List<HistoryEntry>> getHistoryByDateRange(@NotNull @NotNull UUID uuid, long fromTimestamp, long toTimestamp)
      Gets history entries for a user within a specific date range.

      Returns only history entries where the timestamp falls between the specified from and to timestamps.

      Example: 

      
 UUID uuid = UUID.fromString("123e4567-e89b-12d3-a456-426614174000");
 long fromTimestamp = System.currentTimeMillis() - (30L * 24 * 60 * 60 * 1000); // 30 days ago
 long toTimestamp = System.currentTimeMillis(); // now
 
 historyAPI.getHistoryByDateRange(uuid, fromTimestamp, toTimestamp).thenAccept(history -> {
     getLogger().info("User has " + history.size() + " punishments in the last 30 days");
 });
      Parameter:
      uuid - The UUID of the user
      fromTimestamp - The start timestamp (inclusive, in milliseconds since epoch)
      toTimestamp - The end timestamp (inclusive, in milliseconds since epoch)
      Gibt zurück:
      A CompletableFuture that completes with a list of history entries in the date range

    • getHistoryByDateRange

      @NotNull public @NotNull CompletableFuture<List<HistoryEntry>> getHistoryByDateRange(@NotNull @NotNull String playerName, long fromTimestamp, long toTimestamp)
      Gets history entries for a user within a specific date range.

      This is an overloaded method that accepts a player name instead of UUID.

      Example: 

      
 long fromTimestamp = System.currentTimeMillis() - (30L * 24 * 60 * 60 * 1000); // 30 days ago
 long toTimestamp = System.currentTimeMillis(); // now
 
 historyAPI.getHistoryByDateRange("PlayerName", fromTimestamp, toTimestamp).thenAccept(history -> {
     getLogger().info("User has " + history.size() + " punishments in the last 30 days");
 });
      Parameter:
      playerName - The name of the player
      fromTimestamp - The start timestamp (inclusive, in milliseconds since epoch)
      toTimestamp - The end timestamp (inclusive, in milliseconds since epoch)
      Gibt zurück:
      A CompletableFuture that completes with a list of history entries in the date range, or an empty list if the player doesn't exist

    • getHistoryCount

      @NotNull public @NotNull CompletableFuture<Integer> getHistoryCount(@NotNull @NotNull UUID uuid)
      Gets the count of history entries for a user.

      Returns the total number of history entries (punishments, warnings, kicks, etc.) for the specified user.

      Example: 

      
 UUID uuid = UUID.fromString("123e4567-e89b-12d3-a456-426614174000");
 historyAPI.getHistoryCount(uuid).thenAccept(count -> {
     getLogger().info("User has " + count + " history entries total");
 });
      Parameter:
      uuid - The UUID of the user
      Gibt zurück:
      A CompletableFuture that completes with the count of history entries

    • getHistoryCount

      @NotNull public @NotNull CompletableFuture<Integer> getHistoryCount(@NotNull @NotNull String playerName)
      Gets the count of history entries for a user.

      This is an overloaded method that accepts a player name instead of UUID.

      Example: 

      
 historyAPI.getHistoryCount("PlayerName").thenAccept(count -> {
     getLogger().info("User has " + count + " history entries");
 });
      Parameter:
      playerName - The name of the player
      Gibt zurück:
      A CompletableFuture that completes with the count of history entries, or 0 if player doesn't exist

    • getHistoryByReason

      @NotNull public @NotNull CompletableFuture<List<HistoryEntry>> getHistoryByReason(@NotNull @NotNull UUID uuid, @NotNull @NotNull String query)
      Gets history entries for a user that match a reason query.

      Returns all history entries where the reason contains the specified query string (case-insensitive partial match).

      Example: 

      
 UUID uuid = UUID.fromString("123e4567-e89b-12d3-a456-426614174000");
 historyAPI.getHistoryByReason(uuid, "cheating").thenAccept(history -> {
     getLogger().info("Found " + history.size() + " entries with 'cheating' in reason");
     for (HistoryEntry entry : history) {
         getLogger().info("Case #" + entry.getCaseId() + ": " + entry.getReason());
     }
 });
      Parameter:
      uuid - The UUID of the user
      query - The search query string to match against reasons
      Gibt zurück:
      A CompletableFuture that completes with a list of matching history entries

    • getHistoryByReason

      @NotNull public @NotNull CompletableFuture<List<HistoryEntry>> getHistoryByReason(@NotNull @NotNull String playerName, @NotNull @NotNull String query)
      Gets history entries for a user that match a reason query.

      This is an overloaded method that accepts a player name instead of UUID.

      Example: 

      
 historyAPI.getHistoryByReason("PlayerName", "cheating").thenAccept(history -> {
     getLogger().info("Found " + history.size() + " matching entries");
 });
      Parameter:
      playerName - The name of the player
      query - The search query string to match against reasons
      Gibt zurück:
      A CompletableFuture that completes with a list of matching history entries, or empty list if player doesn't exist

    • getRecentHistory

      @NotNull public @NotNull CompletableFuture<List<HistoryEntry>> getRecentHistory(int limit)
      Gets the most recent history entries globally (across all players).

      Returns the last N history entries ordered by timestamp (most recent first).

      Example: 

      
 historyAPI.getRecentHistory(10).thenAccept(history -> {
     getLogger().info("Last 10 history entries:");
     for (HistoryEntry entry : history) {
         getLogger().info("Case #" + entry.getCaseId() + ": " + entry.getPunishmentType() + 
                         " for " + entry.getTargetName());
     }
 });
      Parameter:
      limit - The maximum number of entries to return
      Gibt zurück:
      A CompletableFuture that completes with a list of recent history entries

    • getHistorySinceDays

      @NotNull public @NotNull CompletableFuture<List<HistoryEntry>> getHistorySinceDays(@NotNull @NotNull UUID uuid, int days)
      Gets history entries for a user created within the last N days.

      Returns all history entries where the timestamp falls within the specified number of days.

      Example: 

      
 UUID uuid = UUID.fromString("123e4567-e89b-12d3-a456-426614174000");
 historyAPI.getHistorySinceDays(uuid, 7).thenAccept(history -> {
     getLogger().info("User has " + history.size() + " punishments in the last 7 days");
     for (HistoryEntry entry : history) {
         getLogger().info("Case #" + entry.getCaseId() + ": " + entry.getPunishmentType());
     }
 });
      Parameter:
      uuid - The UUID of the user
      days - The number of days to look back
      Gibt zurück:
      A CompletableFuture that completes with a list of history entries within the time range

    • getHistorySinceDays

      @NotNull public @NotNull CompletableFuture<List<HistoryEntry>> getHistorySinceDays(@NotNull @NotNull String playerName, int days)
      Gets history entries for a user created within the last N days.

      This is an overloaded method that accepts a player name instead of UUID.

      Example: 

      
 historyAPI.getHistorySinceDays("PlayerName", 7).thenAccept(history -> {
     getLogger().info("User has " + history.size() + " punishments in the last 7 days");
 });
      Parameter:
      playerName - The name of the player
      days - The number of days to look back
      Gibt zurück:
      A CompletableFuture that completes with a list of history entries within the time range, or empty list if player doesn't exist