co.mindus.ip2location

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

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.

Method Summary

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.