IServiceStatusListener (NetPhantom® 8.0 Java API Specification)

All Known Implementing Classes:: AdminIP2LocationPanel

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:: IP2LocationManager.addStatusListener(IServiceStatusListener), IP2LocationManager.removeStatusListener(IServiceStatusListener), IP2LocationManager.getStatusDescription(), IP2LocationService.getStatusDescription()

Nested Class Summary

Nested Classes
Modifier and Type Interface and Description

static class IServiceStatusListener.ErrorType
Categories of errors that can occur in the IP2Location service.

Nested Classes
Modifier and Type	Interface and Description
`static class`	`IServiceStatusListener.ErrorType` Categories of errors that can occur in the IP2Location service.

Method Summary

All Methods Instance Methods Default Methods
Modifier and Type	Method and Description
`default void`	`onDatabaseLoaded(LocalDate date, boolean isIPv6)` Called when a database file has been loaded into memory.
`default void`	`onDatabaseUpdated(boolean ipv4Updated, boolean ipv6Updated)` Called when databases are reloaded into memory.
`default void`	`onDownloadCompleted(boolean success)` Called when a database download completes.
`default void`	`onDownloadStarted()` Called when a database download is about to start.
`default void`	`onError(IServiceStatusListener.ErrorType type, String message, Throwable error)` Called when an error occurs in the service.
`default void`	`onInitialized(boolean success, Throwable error)` Called when service initialization completes.
`default void`	`onReconfigurationCompleted(boolean success, Throwable error)` Called when the manager completes reconfiguration.
`default void`	`onReconfigurationStarted()` Called when the manager starts reconfiguration.
`default void`	`onRecoveryCompleted(boolean success, Throwable error)` Called when automatic recovery completes.
`default void`	`onRecoveryRecommended(String reason, boolean autoRecoveryTriggered)` Called when recovery is recommended or automatic recovery is triggered.
`default void`	`onServiceDisposed()` Called when the service is disposed.
`default void`	`onStatusChanged(String newStatus)` Called when the status description changes.
`default void`	`onUpdateCheckPerformed(boolean downloadNeeded)` Called periodically during scheduled update checks.

- Method Detail
  - 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:
    
    IP2LocationManager.reconfigure(IP2LocationService.Builder)
  - 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:
    
    IP2LocationManager.reconfigure(IP2LocationService.Builder)
  - 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:
    
    IP2LocationManager.getStatusDescription(), IP2LocationService.getStatusDescription()
  - 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:
    - IServiceStatusListener.ErrorType.isRecoverable() - Recovery might help
    - IServiceStatusListener.ErrorType.requiresUserAction() - User intervention needed
    - IServiceStatusListener.ErrorType.isTransient() - May resolve on retry
    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:
    
    IServiceStatusListener.ErrorType
  - 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:
    
    IP2LocationManager.isRecoveryRecommended(), IP2LocationManager.triggerRecovery()
  - 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

Interface IServiceStatusListener

Usage Example

Thread Safety

Default Methods

Nested Class Summary

Method Summary

Method Detail

onInitialized

onServiceDisposed

onDownloadStarted

onDownloadCompleted

onDatabaseUpdated

onDatabaseLoaded

onUpdateCheckPerformed

onReconfigurationStarted

onReconfigurationCompleted

onStatusChanged

Example

onError

Example

onRecoveryRecommended

Example

onRecoveryCompleted