Class IP2LocationEventLog

java.lang.Object
co.mindus.ip2location.IP2LocationEventLog
public class IP2LocationEventLog extends Object
Manages event and error logging for IP2Location service.

Events are persisted to a JSON-lines file for durability across restarts. The log file uses a simple format with one JSON object per line, making it easy to append and parse incrementally.

File Format

Each line is a JSON object:

{"ts":"2026-02-04T10:30:00Z","type":"ERROR","cat":"INIT_FAILURE","msg":"Database file not found","detail":"..."}
{"ts":"2026-02-04T10:31:00Z","type":"INFO","cat":"RECOVERY_STARTED","msg":"Manual recovery triggered"}

Thread Safety

All operations are thread-safe using read-write locks.

Usage Example

IP2LocationEventLog log = IP2LocationEventLog.getInstance();

// Log an error
log.logError(EventCategory.INIT_FAILURE, "Database corrupted", exception);

// Log an info event
log.logInfo(EventCategory.RECOVERY_COMPLETED, "Service restored successfully");

// Retrieve recent events
List<LogEntry> entries = log.getEntries(50);

// Clear the log
log.clear();
Author:
Christopher Mindus

  • Field Details

  • Method Details

    • getInstance

      public static IP2LocationEventLog getInstance()
      Gets the singleton instance.
      Returns:
      The event log instance

    • setLogFile

      public void setLogFile(Path path)
      Sets the log file path and loads existing entries.

      This should be called during application startup, typically with a path in the server's root directory.

      Parameters:
      path - The path to the log file

    • setLogDirectory

      public void setLogDirectory(Path directory)
      Sets the log file using a directory path.
      Parameters:
      directory - The directory containing the log file

    • isInitialized

      public boolean isInitialized()
      Returns whether the log has been initialized with a file path.
      Returns:
      true if setLogFile(Path) has been called

    • logInfo

      public void logInfo(IP2LocationEventLog.EventCategory category, String message)
      Logs an informational event.
      Parameters:
      category - The event category
      message - The event message

    • logWarning

      public void logWarning(IP2LocationEventLog.EventCategory category, String message)
      Logs a warning event.
      Parameters:
      category - The event category
      message - The event message

    • logError

      public void logError(IP2LocationEventLog.EventCategory category, String message)
      Logs an error event.
      Parameters:
      category - The event category
      message - The event message

    • logError

      public void logError(IP2LocationEventLog.EventCategory category, String message, Throwable throwable)
      Logs an error event with exception detail.
      Parameters:
      category - The event category
      message - The event message
      throwable - The exception (may be null)

    • log

      public void log(IP2LocationEventLog.EventType type, IP2LocationEventLog.EventCategory category, String message, String detail)
      Logs an event.
      Parameters:
      type - The event type
      category - The event category
      message - The event message
      detail - Optional detail text

    • getInitFailureCount

      public int getInitFailureCount()
      Gets the current init failure count (consecutive failures this session).
      Returns:
      The number of consecutive initialization failures

    • getLookupErrorCount

      public int getLookupErrorCount()
      Gets the current lookup error count (consecutive errors this session).
      Returns:
      The number of consecutive lookup errors

    • getDownloadFailureCount

      public int getDownloadFailureCount()
      Gets the current download failure count (consecutive failures this session).
      Returns:
      The number of consecutive download failures

    • getRecoveryAttemptCount

      public int getRecoveryAttemptCount()
      Gets the total recovery attempt count for this session.
      Returns:
      The number of recovery attempts made

    • getTotalErrorCount

      public int getTotalErrorCount()
      Gets the total error count across all categories.
      Returns:
      Sum of init failures, lookup errors, and download failures

    • resetErrorCounters

      public void resetErrorCounters()
      Resets all error counters.

      This also logs a RECOVERY_CLEARED event.

    • resetInitFailureCount

      public void resetInitFailureCount()
      Resets the init failure counter.

    • resetLookupErrorCount

      public void resetLookupErrorCount()
      Resets the lookup error counter.

    • resetDownloadFailureCount

      public void resetDownloadFailureCount()
      Resets the download failure counter.

    • getEntries

      public List<IP2LocationEventLog.LogEntry> getEntries()
      Gets all cached entries.
      Returns:
      Unmodifiable list of entries (most recent last)

    • getEntries

      public List<IP2LocationEventLog.LogEntry> getEntries(int maxCount)
      Gets the most recent entries.
      Parameters:
      maxCount - Maximum number of entries to return
      Returns:
      List of entries (most recent last)

    • getEntriesByType

      public List<IP2LocationEventLog.LogEntry> getEntriesByType(IP2LocationEventLog.EventType type)
      Gets entries of a specific type.
      Parameters:
      type - The event type to filter by
      Returns:
      List of matching entries

    • getErrors

      public List<IP2LocationEventLog.LogEntry> getErrors()
      Gets only error entries.
      Returns:
      List of error entries

    • getEntryCount

      public int getEntryCount()
      Gets the number of cached entries.
      Returns:
      The number of log entries currently in cache

    • refresh

      public void refresh()
      Refreshes the cache from the file.

      Use this to pick up entries written by other processes.

    • clear

      public void clear()
      Clears all entries from cache and file.