co.mindus.ip2location

Interface IInitializationCallback

Functional Interface:

This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.

@FunctionalInterface
public interface IInitializationCallback

Callback interface for asynchronous service initialization.

This interface is used with IP2LocationService.Builder.buildAsync(IInitializationCallback) to receive notification when service initialization completes. The callback is invoked exactly once, either on success or failure.

Thread Safety

The callback is invoked from the initialization thread, not the thread that called buildAsync(). Implementations should be thread-safe if they interact with shared state.

Success Handling

On successful initialization:

• success is true
• error is null
• The service is ready to accept lookups
• Scheduled updates are running

Failure Handling

On initialization failure:

• success is false
• error contains the exception that caused the failure
• The service may be partially initialized (call IP2LocationService.dispose())
• Lookups will return error status until databases are loaded

Usage Example

 IP2LocationService service = new IP2LocationService.Builder()
     .downloadToken("your-token")
     .database(Database.DB11_FULL)
     .buildAsync((svc, success, error) -> {
         if (success) {
             System.out.println("Service ready for lookups!");
         } else {
             System.err.println("Initialization failed: " + error.getMessage());
             // Optionally retry or fall back to alternative
         }
     });
 
 // Service reference is available immediately, but may not be ready
 // Use awaitReady() if you need to block until initialization completes
 service.awaitReady(30, TimeUnit.SECONDS);
 

Lambda Usage

As a functional interface, callbacks can be expressed as lambdas:

 // Simple success check
 builder.buildAsync((svc, ok, err) -> {
     if (ok) startAcceptingRequests();
 });
 
 // With logging
 builder.buildAsync((svc, ok, err) -> {
     if (ok) {
         log.info("IP2Location ready: IPv4={}, IPv6={}", 
                  svc.isIPv4Ready(), svc.isIPv6Ready());
     } else {
         log.error("IP2Location init failed", err);
     }
 });
 

Author:

Christopher Mindus

See Also:

IP2LocationService.Builder.buildAsync(IInitializationCallback), IP2LocationService.awaitReady(long, java.util.concurrent.TimeUnit)

Method Summary

Modifier and Type	Method and Description
default IInitializationCallback	andThen(IInitializationCallback other) Combines this callback with another, invoking both on completion.
static IInitializationCallback	noOp() Returns a callback that does nothing.
void	onInitialized(IP2LocationService service, boolean success, Throwable error) Called when service initialization completes.

Method Detail

onInitialized

void onInitialized(IP2LocationService service,
                   boolean success,
                   Throwable error)

Called when service initialization completes.

This method is called exactly once per buildAsync() invocation, after the service has either successfully loaded its databases or encountered an error during initialization.

The callback runs on the initialization thread. Long-running operations in this callback will delay the thread's availability for other tasks.

Parameters:

service - The service instance that was initialized. This is the same instance returned by buildAsync(). Never null.

success - true if initialization completed successfully and the service is ready for lookups; false if an error occurred during initialization

error - The exception that caused initialization to fail, or null if initialization succeeded. Common errors include:

• IOException - Database file I/O errors
• UnknownHostException - Network errors
• SecurityException - File permission issues

noOp

static IInitializationCallback noOp()

Returns a callback that does nothing.

Useful when you want async initialization but don't need notification:

 IP2LocationService service=builder.buildAsync(IInitializationCallback.noOp());
 // Later: check service.isReady() or call service.awaitReady()
 

Returns:

A callback that ignores the initialization result

andThen

default IInitializationCallback andThen(IInitializationCallback other)

Combines this callback with another, invoking both on completion.

The callbacks are invoked in order: this callback first, then the other. If this callback throws an exception, the other callback is still invoked.

Parameters:

other - The additional callback to invoke

Returns:

A combined callback that invokes both

Throws:

NullPointerException - if other is null