Interface IServiceStatusListener

public interface IServiceStatusListener
Listener interface for receiving status updates from IP2LocationService and IP2LocationManager.

Implement this interface to receive notifications about service lifecycle events, database updates, configuration changes, and error conditions.

Usage Example

IServiceStatusListener listener = new IServiceStatusListener() {
    @Override
    public void onDatabaseUpdated(boolean ipv4, boolean ipv6) {
        System.out.println("Database updated: IPv4=" + ipv4 + ", IPv6=" + ipv6);
    }

    @Override
    public void onDownloadStarted() {
        System.out.println("Download started...");
    }

    @Override
    public void onDownloadCompleted(boolean success) {
        System.out.println("Download " + (success ? "succeeded" : "failed"));
    }

    @Override
    public void onStatusChanged(String newStatus) {
        SwingUtilities.invokeLater(() -> statusLabel.setText(newStatus));
    }

    @Override
    public void onRecoveryRecommended(String reason, boolean autoRecoveryTriggered) {
        if (!autoRecoveryTriggered) {
            // Show dialog to user
            SwingUtilities.invokeLater(() -> showRecoveryDialog(reason));
        }
    }

    @Override
    public void onError(ErrorType type, String message, Throwable error) {
        logger.error("IP2Location error [" + type + "]: " + message, error);
    }
};

IP2LocationManager manager = IP2LocationManager.getInstance();
manager.addStatusListener(listener);

Thread Safety

Listener methods are called from background threads. Implementations must be thread-safe if they access shared state. For UI updates, use appropriate mechanisms like SwingUtilities.invokeLater() or Platform.runLater(). Avoid performing long-running operations in listener callbacks as they may block the update scheduler.

Default Methods

All methods have empty default implementations, so you only need to override the events you're interested in.

Author:
Christopher Mindus
See Also:

  • Method Details

    • onInitialized

      default void onInitialized(boolean success, Throwable error)
      Called when service initialization completes.

      This is called once when the service finishes its initial startup, whether successful or not.

      Parameters:
      success - true if initialization succeeded, false if it failed
      error - The error that occurred, or null if successful

    • onServiceDisposed

      default void onServiceDisposed()
      Called when the service is disposed.

      This is called when IP2LocationService.dispose() is invoked, either directly or through the manager during reconfiguration.

    • onDownloadStarted

      default void onDownloadStarted()
      Called when a database download is about to start.

      This is called before each download attempt, including automatic scheduled updates and forced updates.

    • onDownloadCompleted

      default void onDownloadCompleted(boolean success)
      Called when a database download completes.

      This is called after each download attempt finishes, whether successful or not.

      Parameters:
      success - true if at least one database was downloaded

    • onDatabaseUpdated

      default void onDatabaseUpdated(boolean ipv4Updated, boolean ipv6Updated)
      Called when databases are reloaded into memory.

      This is called after new database files are loaded, either from a fresh download or when the service starts with existing files.

      Parameters:
      ipv4Updated - true if the IPv4 database was reloaded
      ipv6Updated - true if the IPv6 database was reloaded

    • onDatabaseLoaded

      default void onDatabaseLoaded(LocalDate date, boolean isIPv6)
      Called when a database file has been loaded into memory.

      This is called after each individual database file is successfully opened, during initial load, reconfiguration, download, or recovery. It provides the publication date embedded in the database file.

      Parameters:
      date - The publication date of the loaded database, or null if the date could not be determined
      isIPv6 - true if the IPv6 database was loaded, false for IPv4

    • onUpdateCheckPerformed

      default void onUpdateCheckPerformed(boolean downloadNeeded)
      Called periodically during scheduled update checks.

      This is called each time the scheduler runs its update check, regardless of whether a download is actually performed.

      Parameters:
      downloadNeeded - true if a download was determined to be needed

    • onReconfigurationStarted

      default void onReconfigurationStarted()
      Called when the manager starts reconfiguration.

      This is called at the beginning of a reconfiguration operation, before the new service is created.

      See Also:

    • onReconfigurationCompleted

      default void onReconfigurationCompleted(boolean success, Throwable error)
      Called when the manager completes reconfiguration.

      This is called after reconfiguration finishes, whether successful or not. The old service has been disposed at this point.

      Parameters:
      success - true if the new service initialized successfully
      error - The error that occurred, or null if successful
      See Also:

    • onStatusChanged

      default void onStatusChanged(String newStatus)
      Called when the status description changes.

      This is called whenever any component of the status changes, such as: initialization completing, downloads starting/stopping, databases loading, reconfiguration events, etc.

      The status string is the same format returned by IP2LocationManager.getStatusDescription() or IP2LocationService.getStatusDescription().

      Example

      @Override
public void onStatusChanged(String newStatus) {
    SwingUtilities.invokeLater(() -> statusLabel.setText(newStatus));
}
      Parameters:
      newStatus - The new status description string
      See Also:

    • onError

      default void onError(IServiceStatusListener.ErrorType type, String message, Throwable error)
      Called when an error occurs in the service.

      This provides detailed error information for logging, monitoring, or automated handling. The error type can be used to determine appropriate responses:

      Example

      @Override
public void onError(ErrorType type, String message, Throwable error) {
    // Log the error
    logger.error("IP2Location [" + type + "]: " + message, error);

    // Alert administrator for critical errors
    if (type.requiresUserAction()) {
        alertAdmin("IP2Location requires attention: " + message);
    }
}
      Parameters:
      type - The category of error
      message - A human-readable error message
      error - The underlying exception, or null if not applicable
      See Also:

    • onRecoveryRecommended

      default void onRecoveryRecommended(String reason, boolean autoRecoveryTriggered)
      Called when recovery is recommended or automatic recovery is triggered.

      This event is fired when error thresholds are exceeded and recovery action should be considered. The event indicates whether automatic recovery has been triggered (if enabled) or if manual intervention is needed.

      Example

      @Override
public void onRecoveryRecommended(String reason, boolean autoRecoveryTriggered) {
    if (autoRecoveryTriggered) {
        logger.info("Automatic recovery initiated: " + reason);
    } else {
        // Prompt user for action
        SwingUtilities.invokeLater(() -> {
            boolean confirmed = showConfirmDialog(
                "Recovery Recommended",
                reason + "\n\nAttempt recovery now?");
            if (confirmed) {
                manager.triggerRecovery();
            }
        });
    }
}
      Parameters:
      reason - Human-readable explanation of why recovery is recommended
      autoRecoveryTriggered - true if automatic recovery has been initiated, false if manual action is needed
      See Also:

    • onRecoveryCompleted

      default void onRecoveryCompleted(boolean success, Throwable error)
      Called when automatic recovery completes.

      This is only called when automatic recovery is enabled and was triggered. It indicates whether the recovery attempt succeeded.

      Parameters:
      success - true if recovery succeeded and service is operational
      error - The error that occurred during recovery, or null if successful