IP2LocationEventLog (NetPhantom® 8.0 Java API Specification)

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
See Also:: AdminIP2LocationPanel, IP2LocationConfig

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`IP2LocationEventLog.EventCategory` Event category for classification.
`static class`	`IP2LocationEventLog.EventType` Event severity level.
`static class`	`IP2LocationEventLog.LogEntry` Represents a single log entry.

Field Summary
Fields
Modifier and Type Field and Description
static String DEFAULT_LOG_FILE
Default log file name.

Fields
Modifier and Type	Field and Description
`static String`	`DEFAULT_LOG_FILE` Default log file name.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`clear()` Clears all entries from cache and file.
`int`	`getDownloadFailureCount()` Gets the current download failure count (consecutive failures this session).
`List<IP2LocationEventLog.LogEntry>`	`getEntries()` Gets all cached entries.
`List<IP2LocationEventLog.LogEntry>`	`getEntries(int maxCount)` Gets the most recent entries.
`List<IP2LocationEventLog.LogEntry>`	`getEntriesByType(IP2LocationEventLog.EventType type)` Gets entries of a specific type.
`int`	`getEntryCount()` Gets the number of cached entries.
`List<IP2LocationEventLog.LogEntry>`	`getErrors()` Gets only error entries.
`int`	`getInitFailureCount()` Gets the current init failure count (consecutive failures this session).
`static IP2LocationEventLog`	`getInstance()` Gets the singleton instance.
`int`	`getLookupErrorCount()` Gets the current lookup error count (consecutive errors this session).
`int`	`getRecoveryAttemptCount()` Gets the total recovery attempt count for this session.
`int`	`getTotalErrorCount()` Gets the total error count across all categories.
`boolean`	`isInitialized()` Returns whether the log has been initialized with a file path.
`void`	`log(IP2LocationEventLog.EventType type, IP2LocationEventLog.EventCategory category, String message, String detail)` Logs an event.
`void`	`logError(IP2LocationEventLog.EventCategory category, String message)` Logs an error event.
`void`	`logError(IP2LocationEventLog.EventCategory category, String message, Throwable throwable)` Logs an error event with exception detail.
`void`	`logInfo(IP2LocationEventLog.EventCategory category, String message)` Logs an informational event.
`void`	`logWarning(IP2LocationEventLog.EventCategory category, String message)` Logs a warning event.
`void`	`refresh()` Refreshes the cache from the file.
`void`	`resetDownloadFailureCount()` Resets the download failure counter.
`void`	`resetErrorCounters()` Resets all error counters.
`void`	`resetInitFailureCount()` Resets the init failure counter.
`void`	`resetLookupErrorCount()` Resets the lookup error counter.
`void`	`setLogDirectory(Path directory)` Sets the log file using a directory path.
`void`	`setLogFile(Path path)` Sets the log file path and loads existing entries.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - DEFAULT_LOG_FILE
```
public static final String DEFAULT_LOG_FILE
```
    Default log file name.
    See Also:
    Constant Field Values
- Method Detail
  - 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.

Class IP2LocationEventLog

File Format

Thread Safety

Usage Example

Nested Class Summary

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_LOG_FILE

Method Detail

getInstance

setLogFile

setLogDirectory

isInitialized

logInfo

logWarning

logError

logError

log

getInitFailureCount

getLookupErrorCount

getDownloadFailureCount

getRecoveryAttemptCount

getTotalErrorCount

resetErrorCounters

resetInitFailureCount

resetLookupErrorCount

resetDownloadFailureCount

getEntries

getEntries

getEntriesByType

getErrors

getEntryCount

refresh

clear