IP2LocationService (NetPhantom® 8.0 Java API Specification)

java.lang.Object
- co.mindus.ip2location.IP2LocationService

All Implemented Interfaces:

AutoCloseable
```
public class IP2LocationService
extends Object
implements AutoCloseable
```
High-level service for IP geolocation lookups with automatic database updates.
This service provides a complete solution for IP geolocation including:
- Automatic monthly database downloads from IP2Location
- Support for both IPv4 and IPv6 lookups
- Thread-safe concurrent lookups
- Hot-reload of databases without service restart
- Configurable memory-mapped file support
- Proxy support via system ProxySelector
- Asynchronous initialization with callbacks
- Custom thread factory for virtual thread support (Java 21+)
- Parallel download of IPv4 and IPv6 databases
- Recovery mode for corrupted state or databases
- Disabled mode for dev/test environments or feature flags
- Human-readable status descriptions for UI display
Quick Start (Blocking)
```
 IP2LocationService service = new IP2LocationService.Builder()
     .downloadToken("YOUR_TOKEN")
     .database(Database.DB11)
     .includeIPv6(true)
     .directory(Paths.get("/var/lib/ip2location"))
     .build();  // Blocks until databases are loaded
 
 GeoLocation loc = service.lookup("8.8.8.8");
 if (loc.isOk()) {
     System.out.println("Country: " + loc.getCountryCode());
     System.out.println("Location: " + loc.getLocationDescription());
 }
 
 // Display service status in UI
 statusLabel.setText(service.getStatusDescription());
 // "IPv4+IPv6, IPv4 ready, IPv6 ready"
 
 service.dispose();
 
```
Async Initialization
```
 IP2LocationService service = new IP2LocationService.Builder()
     .downloadToken("YOUR_TOKEN")
     .database(Database.DB11)
     .buildAsync((svc, success, error) -> {
         if (success) {
             System.out.println("Service ready!");
         } else {
             System.err.println("Init failed: " + error);
         }
     });
 
 // Service returned immediately, initialization runs in background
 // Wait for initialization if needed:
 boolean ready = service.awaitReady(30, TimeUnit.SECONDS);
 
```
Recovery Mode

If the database or state files become corrupted, use recovery mode to clear everything and start fresh:
```
 IP2LocationService service = new IP2LocationService.Builder()
     .downloadToken("YOUR_TOKEN")
     .database(Database.DB11)
     .directory(Paths.get("/var/lib/ip2location"))
     .attemptRecovery()  // Clears directory before initialization
     .build();
 
```
For manual recovery without creating a new service:
```
 // Clear directory manually (service must be disposed first!)
 Path dir = Paths.get("/var/lib/ip2location");
 int deleted = IP2LocationService.clearDirectory(dir, IEventLogger.consoleLogger());
 System.out.println("Deleted " + deleted + " files");
 
```
Disabled Mode

The service can be started disabled for environments where geolocation is not needed:
```
 boolean useGeoLocation = Boolean.parseBoolean(
     System.getProperty("app.geolocation.enabled", "true"));
 
 IP2LocationService service = new IP2LocationService.Builder()
     .downloadToken("YOUR_TOKEN")
     .enabled(useGeoLocation)  // Disable via configuration
     .build();
 
 if (service.isEnabled()) {
     GeoLocation loc = service.lookup("8.8.8.8");
 }
 
```
Virtual Threads (Java 21+)
```
 IP2LocationService service = new IP2LocationService.Builder()
     .downloadToken("YOUR_TOKEN")
     .threadFactory((task, name, daemon) -> 
         Thread.ofVirtual().name(name).unstarted(task))
     .buildAsync();
 
```
Database Update Schedule

IP2Location LITE databases are updated on the 1st of each calendar month. This service follows IP2Location's recommendation to download during days 1-7 of each month. The service also forces a download on startup if the existing database is from a previous month.

IPv6 Support

When IP2LocationService.Builder.includeIPv6(boolean) is set to true:
- Both IPv4 and IPv6 databases are downloaded (in parallel for speed)
- IPv4 lookups use the smaller IPv4-only database for efficiency
- IPv6 lookups use the IPv6 database (which also contains IPv4 ranges)
Memory-Mapped Files

The service supports two database access modes:
- Memory-mapped (useMemoryMappedFile=true): Uses less heap memory, OS manages page caching. Best for production servers with adequate RAM.
- Standard (useMemoryMappedFile=false, default): More predictable memory behavior. Better for containers or memory-constrained environments.
Reconfiguration

This service is immutable after construction. To change configuration:
1. Call dispose() on the existing instance
2. Create a new instance with IP2LocationService.Builder
For seamless reconfiguration without downtime, use IP2LocationManager.

Thread Safety

This class is thread-safe. Multiple threads can safely call lookup(String) concurrently. Database reloads are performed atomically using read-write locks.

This class now defaults to using a Builder instance with Virtual Threads when running on Java 21 or better.
Author:

Christopher Mindus

See Also:

IP2LocationManager, Database, GeoLocation, IInitializationCallback, IThreadFactory

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class IP2LocationService.Builder
Builder for creating IP2LocationService instances.

Nested Classes
Modifier and Type	Class and Description
`static class`	`IP2LocationService.Builder` Builder for creating `IP2LocationService` instances.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`awaitReady(long timeout, TimeUnit unit)` Waits for the service to become ready.
`static int`	`clearDirectory(Path directory, IEventLogger logger)` Clears an IP2Location directory, removing all database and state files.
`void`	`close()` Alias for `dispose()` to support try-with-resources.
`void`	`dispose()` Disposes of the service, releasing all resources.
`void`	`forceUpdate()` Forces an immediate database update check and download.
`Database`	`getDatabase()` Returns the configured database type.
`Path`	`getDirectory()` Returns the configured storage directory.
`Throwable`	`getInitializationError()` Returns the error that occurred during initialization.
`LocalDate`	`getIPv4DatabaseDate()` Returns the date of the currently loaded IPv4 database.
`LocalDate`	`getIPv6DatabaseDate()` Returns the date of the currently loaded IPv6 database.
`YearMonth`	`getLastUpdateMonth()` Returns the month of the last successful database update.
`Instant`	`getNextScheduledUpdate()` Returns the instant when the next scheduled update check will occur.
`String`	`getStatusDescription()` Returns the current status as a human-readable string for UI display.
`static boolean`	`hasValidDatabases(Path directory, boolean requireIPv6)` Checks if an IP2Location directory contains valid database files.
`boolean`	`isEnabled()` Returns whether the service is enabled.
`boolean`	`isIPv4Ready()` Returns whether an IPv4 database is loaded and ready.
`boolean`	`isIPv6Enabled()` Returns whether IPv6 support is enabled.
`boolean`	`isIPv6Ready()` Returns whether an IPv6 database is loaded and ready.
`boolean`	`isReady()` Returns whether the service is ready to handle lookups.
`boolean`	`isRunning()` Returns whether the service is currently running.
`boolean`	`isUsingMemoryMappedFile()` Returns whether memory-mapped file mode is enabled.
`GeoLocation`	`lookup(String ip)` Looks up geolocation information for an IP address.
`void`	`setDatabaseLoadCallback(BiConsumer<LocalDate,Boolean> callback)` Sets a callback invoked when a database file is loaded into memory.
`void`	`setDownloadCallback(IInitializationCallback callback)` Sets a callback invoked after each download attempt (forced or scheduled).

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

- Method Detail
  - clearDirectory
```
public static int clearDirectory(Path directory,
                                 IEventLogger logger)
                          throws IOException
```
    Clears an IP2Location directory, removing all database and state files.
    This is a recovery utility that can be used when the database or state files become corrupted. It deletes:
    - All *.BIN and *.bin database files
    - The state file (.ip2location-state.properties)
    - All *.tmp temporary files
    - All *.zip download files
    Important: All IP2LocationService instances using this directory must be disposed before calling this method. Otherwise, the service may hold file locks that prevent deletion, or may become unstable.
    
    Usage Example
```
 // First, dispose the service
 service.dispose();
 
 // Clear the directory
 Path dir = Paths.get("/var/lib/ip2location");
 int deleted = IP2LocationService.clearDirectory(dir, IEventLogger.consoleLogger());
 System.out.println("Deleted " + deleted + " files");
 
 // Create a new service (will download fresh databases)
 service = new IP2LocationService.Builder()
     .downloadToken("YOUR_TOKEN")
     .directory(dir)
     .build();
 
```
    Parameters:
    
    directory - The directory to clear
    
    logger - Logger for reporting progress (may be null for silent operation)
    
    Returns:
    
    The number of files deleted
    
    Throws:
    
    IOException - if the directory cannot be accessed or files cannot be deleted
  - hasValidDatabases
```
public static boolean hasValidDatabases(Path directory,
                                        boolean requireIPv6)
```
    Checks if an IP2Location directory contains valid database files.
    This method can be used to determine if recovery might be needed before creating a service instance.
    
    Parameters:
    
    directory - The directory to check
    
    requireIPv6 - Whether to require both IPv4 and IPv6 databases
    
    Returns:
    
    true if the directory contains the required database files
  - dispose
```
public void dispose()
```
    Disposes of the service, releasing all resources.
    This method:
    1. Cancels all scheduled update tasks
    2. Closes all loaded database readers
    3. Releases any memory-mapped file mappings
    After calling this method, the service cannot be restarted. This method is idempotent.
  - close
```
public void close()
```
    Alias for dispose() to support try-with-resources.
    
    Specified by:
    
    close in interface AutoCloseable
  - isReady
```
public boolean isReady()
```
    Returns whether the service is ready to handle lookups.
    A service is ready when at least one database has been loaded. This method returns immediately without blocking.
    
    Returns:
    
    true if at least one database is loaded
  - awaitReady
```
public boolean awaitReady(long timeout,
                          TimeUnit unit)
                   throws InterruptedException
```
    Waits for the service to become ready.
    Blocks until initialization completes or the timeout expires.
    
    Parameters:
    
    timeout - The maximum time to wait
    
    unit - The time unit
    
    Returns:
    
    true if the service is ready, false if timeout expired
    
    Throws:
    
    InterruptedException - if the current thread was interrupted
  - getInitializationError
```
public Throwable getInitializationError()
```
    Returns the error that occurred during initialization.
    
    Returns:
    
    The initialization error, or null if successful
  - lookup
```
public GeoLocation lookup(String ip)
```
    Looks up geolocation information for an IP address.
    This method automatically detects whether the IP is IPv4 or IPv6 and routes to the appropriate database.
    
    Parameters:
    
    ip - The IP address to look up (e.g., "8.8.8.8" or "2001:4860:4860::8888")
    
    Returns:
    
    A GeoLocation containing the result (check GeoLocation.isOk())
  - isEnabled
```
public boolean isEnabled()
```
    Returns whether the service is enabled.
    When disabled, the service does not download or load databases, does not start the update scheduler, and lookups return STATUS_SERVICE_DISABLED.
    
    A disabled service consumes minimal resources and can be used as a placeholder when geolocation is not needed in certain environments (e.g., development, testing).
    
    Returns:
    
    true if the service is enabled, false if disabled
    
    See Also:
    
    IP2LocationService.Builder.enabled(boolean)
  - isRunning
```
public boolean isRunning()
```
    Returns whether the service is currently running.
    
    Returns:
    
    true if started and not disposed
  - isIPv4Ready
```
public boolean isIPv4Ready()
```
    Returns whether an IPv4 database is loaded and ready.
    
    Returns:
    
    true if IPv4 lookups are available
  - isIPv6Ready
```
public boolean isIPv6Ready()
```
    Returns whether an IPv6 database is loaded and ready.
    
    Returns:
    
    true if IPv6 lookups are available
  - getLastUpdateMonth
```
public YearMonth getLastUpdateMonth()
```
    Returns the month of the last successful database update.
    
    Returns:
    
    The year-month of last update, or null if never updated
  - isUsingMemoryMappedFile
```
public boolean isUsingMemoryMappedFile()
```
    Returns whether memory-mapped file mode is enabled.
    
    Returns:
    
    true if using memory-mapped files
  - getDirectory
```
public Path getDirectory()
```
    Returns the configured storage directory.
    
    Returns:
    
    Path to the database storage directory
  - getDatabase
```
public Database getDatabase()
```
    Returns the configured database type.
    
    Returns:
    
    The database type being used
  - isIPv6Enabled
```
public boolean isIPv6Enabled()
```
    Returns whether IPv6 support is enabled.
    
    Returns:
    
    true if IPv6 lookups are enabled
  - getIPv4DatabaseDate
```
public LocalDate getIPv4DatabaseDate()
```
    Returns the date of the currently loaded IPv4 database.
    The date reflects when the database was published by IP2Location, typically the 1st of the month.
    
    Returns:
    
    The database date, or null if no IPv4 database is loaded
  - getIPv6DatabaseDate
```
public LocalDate getIPv6DatabaseDate()
```
    Returns the date of the currently loaded IPv6 database.
    The date reflects when the database was published by IP2Location, typically the 1st of the month.
    
    Returns:
    
    The database date, or null if no IPv6 database is loaded or IPv6 support is not enabled
  - getNextScheduledUpdate
```
public Instant getNextScheduledUpdate()
```
    Returns the instant when the next scheduled update check will occur.
    This reflects the scheduler's next planned execution, not necessarily when a download will occur (which depends on the current month and whether an update is needed).
    
    Returns:
    
    The instant of the next scheduled check, or null if the scheduler is not running (service disabled, not started, or disposed)
  - getStatusDescription
```
public String getStatusDescription()
```
    Returns the current status as a human-readable string for UI display.
    The status components are concatenated in order of importance, separated by ", " (comma and space). Possible components include:
    - Disposed - Service has been disposed
    - Disabled - Service is disabled
    - Initializing - Service is starting up
    - IPv4 only - Only IPv4 lookups enabled
    - IPv4+IPv6 - Both IPv4 and IPv6 lookups enabled
    - Downloading IPv4 - IPv4 database download in progress
    - Downloading IPv6 - IPv6 database download in progress
    - IPv4 ready - IPv4 database loaded
    - IPv6 ready - IPv6 database loaded
    - IPv4 not loaded - IPv4 database not available
    - IPv6 not loaded - IPv6 database not available
    Example outputs:
    - "Disabled"
    - "IPv4 only, IPv4 ready"
    - "IPv4+IPv6, Downloading IPv4, Downloading IPv6"
    - "IPv4+IPv6, IPv4 ready, IPv6 ready"
    - "Disposed"
    Returns:
    
    A comma-separated status string, never null
  - setDownloadCallback
```
public void setDownloadCallback(IInitializationCallback callback)
```
    Sets a callback invoked after each download attempt (forced or scheduled).
    
    Parameters:
    
    callback - The callback, or null to remove
  - setDatabaseLoadCallback
```
public void setDatabaseLoadCallback(BiConsumer<LocalDate,Boolean> callback)
```
    Sets a callback invoked when a database file is loaded into memory.
    
    Parameters:
    
    callback - The callback receiving (date, isIPv6), or null to remove
  - forceUpdate
```
public void forceUpdate()
```
    Forces an immediate database update check and download.
    This bypasses the normal scheduling logic and attempts to download the latest database immediately. The operation runs asynchronously.
    
    Throws:
    
    IllegalStateException - if the service is not running

Class IP2LocationService

Quick Start (Blocking)

Async Initialization

Recovery Mode

Disabled Mode

Virtual Threads (Java 21+)

Database Update Schedule

IPv6 Support

Memory-Mapped Files

Reconfiguration

Thread Safety

Nested Class Summary

Method Summary

Methods inherited from class java.lang.Object

Method Detail

clearDirectory

Usage Example

hasValidDatabases

dispose

close

isReady

awaitReady

getInitializationError

lookup

isEnabled

isRunning

isIPv4Ready

isIPv6Ready

getLastUpdateMonth

isUsingMemoryMappedFile

getDirectory

getDatabase

isIPv6Enabled

getIPv4DatabaseDate

getIPv6DatabaseDate

getNextScheduledUpdate

getStatusDescription

Example outputs:

setDownloadCallback

setDatabaseLoadCallback

forceUpdate