IP2LocationService.Builder (NetPhantom® 8.0 Java API Specification)

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

Enclosing class:: IP2LocationService

public static class IP2LocationService.Builder
extends Object

Builder for creating IP2LocationService instances.

Required Settings

downloadToken(String) - Your IP2Location download token

Optional Settings

Method	Default	Description
`database(Database)`	DB11	Database type
`includeIPv6(boolean)`	false	Enable IPv6 lookups
`directory(Path)`	temp/ip2location	Storage directory
`logger(IEventLogger)`	Console	Event logger
`checkIntervalMs(long)`	6 hours	Update check interval
`useMemoryMappedFile(boolean)`	false	Memory-mapped mode
`threadFactory(IThreadFactory)`	Platform threads	Thread creation
`attemptRecovery()`	false	Clear directory on startup
`enabled(boolean)`	true	Enable/disable service

Build Methods

build() - Blocking initialization, waits until ready
buildAsync() - Returns immediately, initializes in background
buildAsync(IInitializationCallback) - With completion callback

See Also:: IP2LocationService

Constructor Summary

Constructors
Constructor and Description

Builder()
Creates a new Builder with default settings.

Constructors
Constructor and Description
`Builder()` Creates a new Builder with default settings.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`IP2LocationService.Builder`	`attemptRecovery()` Enables recovery mode to clear the directory before initialization.
`IP2LocationService`	`build()` Builds and initializes the service synchronously.
`IP2LocationService`	`buildAsync()` Builds the service with asynchronous initialization.
`IP2LocationService`	`buildAsync(IInitializationCallback callback)` Builds the service with asynchronous initialization and callback.
`IP2LocationService.Builder`	`checkIntervalMs(long intervalMs)` Sets the interval between automatic update checks.
`IP2LocationService.Builder`	`database(Database database)` Sets the database type to use.
`IP2LocationService.Builder`	`directory(Path directory)` Sets the directory for storing database files.
`IP2LocationService.Builder`	`downloadToken(String token)` Sets the download token for IP2Location API authentication.
`IP2LocationService.Builder`	`enabled(boolean enabled)` Sets whether the service is enabled.
`Path`	`getDirectory()` Returns the configured directory path.
`IP2LocationService.Builder`	`includeIPv6(boolean include)` Sets whether to enable IPv6 lookups.
`IP2LocationService.Builder`	`logger(IEventLogger logger)` Sets the event logger for operational messages.
`IP2LocationService.Builder`	`threadFactory(IThreadFactory factory)` Sets the thread factory for creating background threads.
`IP2LocationService.Builder`	`useMemoryMappedFile(boolean useMemoryMapped)` Sets whether to use memory-mapped files for database access.

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

- Constructor Detail
  - Builder
```
public Builder()
```
    Creates a new Builder with default settings.
- Method Detail
  - downloadToken
```
public IP2LocationService.Builder downloadToken(String token)
```
    Sets the download token for IP2Location API authentication.
    Get your token by signing up at lite.ip2location.com and navigating to the download area.
    
    Parameters:
    
    token - The download token (required)
    
    Returns:
    
    This builder for chaining
  - database
```
public IP2LocationService.Builder database(Database database)
```
    Sets the database type to use.
    All database types support both IPv4 and IPv6 lookups. The IPv6 database is automatically downloaded when includeIPv6(boolean) is enabled.
    
    Parameters:
    
    database - The database type (default: DB11)
    
    Returns:
    
    This builder for chaining
  - includeIPv6
```
public IP2LocationService.Builder includeIPv6(boolean include)
```
    Sets whether to enable IPv6 lookups.
    When enabled:
    - Both IPv4 and IPv6 database files are downloaded (in parallel)
    - IPv4 lookups use the smaller IPv4-only database
    - IPv6 lookups use the IPv6 database
    When disabled (default):
    - Only the IPv4 database is downloaded
    - IPv6 lookups return STATUS_IPV6_NOT_SUPPORTED
    Parameters:
    
    include - true to enable IPv6 support (default: false)
    
    Returns:
    
    This builder for chaining
  - directory
```
public IP2LocationService.Builder directory(Path directory)
```
    Sets the directory for storing database files.
    The directory will be created if it doesn't exist.
    
    Parameters:
    
    directory - Path to the storage directory
    
    Returns:
    
    This builder for chaining
  - logger
```
public IP2LocationService.Builder logger(IEventLogger logger)
```
    Sets the event logger for operational messages.
    
    Parameters:
    
    logger - The event logger implementation
    
    Returns:
    
    This builder for chaining
    
    See Also:
    
    IEventLogger
  - checkIntervalMs
```
public IP2LocationService.Builder checkIntervalMs(long intervalMs)
```
    Sets the interval between automatic update checks.
    
    Parameters:
    
    intervalMs - Interval in milliseconds (default: 6 hours, minimum: 1 minute)
    
    Returns:
    
    This builder for chaining
    
    Throws:
    
    IllegalArgumentException - if interval is less than 1 minute
  - useMemoryMappedFile
```
public IP2LocationService.Builder useMemoryMappedFile(boolean useMemoryMapped)
```
    Sets whether to use memory-mapped files for database access.
    Memory-Mapped Mode (true)
    - Uses less JVM heap memory
    - OS manages page caching efficiently
    - May have slightly faster random access
    - Recommended for production servers
    Standard Mode (false, default)
    - More predictable memory behavior
    - Better for containerized environments
    - Easier to monitor memory usage
    Parameters:
    
    useMemoryMapped - true for memory-mapped (default: false)
    
    Returns:
    
    This builder for chaining
  - threadFactory
```
public IP2LocationService.Builder threadFactory(IThreadFactory factory)
```
    Sets the thread factory for creating background threads.
    Use this to integrate with your application's thread management or to use virtual threads in Java 21+.
    
    Parameters:
    
    factory - The thread factory (default: platform threads)
    
    Returns:
    
    This builder for chaining
    
    See Also:
    
    IThreadFactory
  - attemptRecovery
```
public IP2LocationService.Builder attemptRecovery()
```
    Enables recovery mode to clear the directory before initialization.
    When enabled, all existing database files, state files, and temporary files are deleted from the configured directory before initialization. This forces a fresh download of the databases.
    
    Use this when:
    - The database files may be corrupted
    - The state file may be corrupted or inconsistent
    - You want to force a complete refresh
    - Previous initialization attempts failed
    Example
```
 // Normal startup failed, try recovery
 IP2LocationService service = new IP2LocationService.Builder()
     .downloadToken("YOUR_TOKEN")
     .database(Database.DB11)
     .directory(Paths.get("/var/lib/ip2location"))
     .attemptRecovery()
     .build();
 
```
    Returns:
    
    This builder for chaining
  - enabled
```
public IP2LocationService.Builder enabled(boolean enabled)
```
    Sets whether the service is enabled.
    When disabled:
    - No databases are downloaded or loaded
    - No scheduler is started for automatic updates
    - Lookups return STATUS_SERVICE_DISABLED
    - The service consumes minimal resources
    This is useful for:
    - Disabling geolocation in certain environments (dev, test)
    - Feature flags to turn off geolocation without code changes
    - Graceful degradation when IP2Location is not needed
    Example
```
 boolean useGeoLocation = Boolean.parseBoolean(
     System.getProperty("app.geolocation.enabled", "true"));
 
 IP2LocationService service = new IP2LocationService.Builder()
     .downloadToken("YOUR_TOKEN")
     .enabled(useGeoLocation)  // Can be disabled via system property
     .build();
 
```
    Parameters:
    
    enabled - true to enable the service (default), false to disable
    
    Returns:
    
    This builder for chaining
  - getDirectory
```
public Path getDirectory()
```
    Returns the configured directory path.
    Used internally by IP2LocationManager for directory comparison.
    
    Returns:
    
    The configured directory path
  - build
```
public IP2LocationService build()
```
    Builds and initializes the service synchronously.
    This method blocks until:
    - Existing databases are loaded, OR
    - New databases are downloaded (if stale or missing), OR
    - Initialization fails with an error
    If attemptRecovery() was called, the directory is cleared first.
    
    After this method returns, IP2LocationService.isReady() will return true if at least one database was loaded successfully.
    Returns:
    
    A fully initialized IP2LocationService
    
    Throws:
    
    IllegalStateException - if downloadToken is not set
  - buildAsync
```
public IP2LocationService buildAsync()
```
    Builds the service with asynchronous initialization.
    Returns immediately with a service instance. Initialization runs in a background thread. Use IP2LocationService.awaitReady(long, TimeUnit) to wait for completion, or IP2LocationService.isReady() to check status.
    
    If attemptRecovery() was called, the directory is cleared first (during the async initialization).
    
    Returns:
    
    An IP2LocationService (may not be ready yet)
    
    Throws:
    
    IllegalStateException - if downloadToken is not set
  - buildAsync
```
public IP2LocationService buildAsync(IInitializationCallback callback)
```
    Builds the service with asynchronous initialization and callback.
    Returns immediately. The callback is invoked when initialization completes (successfully or with an error).
    
    If attemptRecovery() was called, the directory is cleared first (during the async initialization, before the callback is invoked).
    
    Parameters:
    
    callback - Callback for initialization result (may be null)
    
    Returns:
    
    An IP2LocationService (may not be ready yet)
    
    Throws:
    
    IllegalStateException - if downloadToken is not set

Class IP2LocationService.Builder

Required Settings

Optional Settings

Build Methods

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Builder

Method Detail

downloadToken

database

includeIPv6

directory

logger

checkIntervalMs

useMemoryMappedFile

Memory-Mapped Mode (true)

Standard Mode (false, default)

threadFactory

attemptRecovery

Example

enabled

Example

getDirectory

build

buildAsync

buildAsync