Class IP2LocationAdmin

java.lang.Object
com.iizix.server.geo.ip2location.IP2LocationAdmin
All Implemented Interfaces:
IServiceStatusListener

public final class IP2LocationAdmin extends Object implements IServiceStatusListener
What an administration UI needs of the IP2Location service, in one place and without a type of the co.mindus.ip2location library: the status of the running service as the NetPhantom IP2Location page shows it (getStatus(ServerSettings)), the actions of its buttons and of the context menu of its status indicator, the recent events, and a IP2LocationAdmin.Listener told when something changed. ServerAdmin's IP2Location dialog is built on it (CC-IP2LOCATION-SERVERADMIN); NetPhantom's AdminIP2LocationPanel read the manager and the event log directly.

One instance per JVM, like the manager it wraps. It registers itself with the manager as a status listener once, at first use, and keeps the last download error the way the NetPhantom panel did, so that the status indicator can say "Download failed: ..." until a download succeeds or the counters are cleared. The listeners of this class are called on the library's threads; a UI posts to its own worker.

Author:
Christopher Mindus
  • Method Details

    • getInstance

      public static IP2LocationAdmin getInstance()
      Gets the instance, registered with the manager.
      Returns:
      The instance.
    • getStatus

      public IP2LocationAdmin.Status getStatus(ServerSettings settings)
      Reads the status of the service.
      Parameters:
      settings - The server settings, for the switch.
      Returns:
      The status.
    • getRecentEvents

      public List<String> getRecentEvents(int max)
      Gets the recent events of the JSON-lines history, newest last, as one line each.
      Parameters:
      max - The maximum count.
      Returns:
      The summaries, empty for none.
    • apply

      public boolean apply(ServerSettings settings)
      Applies the server settings to the running service: the module reconfigures the manager from them (IP2LocationModule.reconfigure(ServerSettings, java.io.File)). The caller has validated and written the settings and saved the configuration file.
      Parameters:
      settings - The server settings.
      Returns:
      false when there is no module (no server) or the manager is shut down, true otherwise.
    • canUpdateNow

      public boolean canUpdateNow()
      Checks if the databases can be updated now (the service is enabled and ready, no update is running).
      Returns:
      true when updateNow() would start an update.
    • updateNow

      public void updateNow()
      Starts an immediate database update check.
    • canTriggerRecovery

      public boolean canTriggerRecovery()
      Checks if a recovery can be triggered (the service is configured, none is running).
      Returns:
      true when triggerRecovery() would start one.
    • triggerRecovery

      public void triggerRecovery()
      Triggers a recovery: the database files are cleared and downloaded again.
    • clearRecoveryRecommendation

      public void clearRecoveryRecommendation()
      Clears the recovery recommendation without recovering.
    • clearErrorCounters

      public void clearErrorCounters()
      Resets every error counter, the recovery recommendation and the last download error.
    • clearInitFailures

      public void clearInitFailures()
      Resets the initialization failure counter.
    • clearLookupErrors

      public void clearLookupErrors()
      Resets the lookup error counter.
    • clearDownloadError

      public void clearDownloadError()
      Resets the download failure counter and the last download error.
    • addListener

      public void addListener(IP2LocationAdmin.Listener listener)
      Adds a listener.
      Parameters:
      listener - The listener.
    • removeListener

      public boolean removeListener(IP2LocationAdmin.Listener listener)
      Removes a listener.
      Parameters:
      listener - The listener.
      Returns:
      true if it was registered.
    • onStatusChanged

      public void onStatusChanged(String newStatus)
      --- IServiceStatusListener (the manager's threads) ---
      Specified by:
      onStatusChanged in interface IServiceStatusListener
      Parameters:
      newStatus - The new status description string
      See Also:
    • onDownloadStarted

      public void onDownloadStarted()
      Description copied from interface: IServiceStatusListener
      Called when a database download is about to start.

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

      Specified by:
      onDownloadStarted in interface IServiceStatusListener
    • onDownloadCompleted

      public void onDownloadCompleted(boolean success)
      Description copied from interface: IServiceStatusListener
      Called when a database download completes.

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

      Specified by:
      onDownloadCompleted in interface IServiceStatusListener
      Parameters:
      success - true if at least one database was downloaded
    • onDatabaseLoaded

      public void onDatabaseLoaded(LocalDate date, boolean isIPv6)
      Description copied from interface: IServiceStatusListener
      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.

      Specified by:
      onDatabaseLoaded in interface IServiceStatusListener
      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
    • onDatabaseUpdated

      public void onDatabaseUpdated(boolean ipv4Updated, boolean ipv6Updated)
      Description copied from interface: IServiceStatusListener
      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.

      Specified by:
      onDatabaseUpdated in interface IServiceStatusListener
      Parameters:
      ipv4Updated - true if the IPv4 database was reloaded
      ipv6Updated - true if the IPv6 database was reloaded
    • onReconfigurationCompleted

      public void onReconfigurationCompleted(boolean success, Throwable error)
      Description copied from interface: IServiceStatusListener
      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.

      Specified by:
      onReconfigurationCompleted in interface IServiceStatusListener
      Parameters:
      success - true if the new service initialized successfully
      error - The error that occurred, or null if successful
      See Also:
    • onInitialized

      public void onInitialized(boolean success, Throwable error)
      Description copied from interface: IServiceStatusListener
      Called when service initialization completes.

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

      Specified by:
      onInitialized in interface IServiceStatusListener
      Parameters:
      success - true if initialization succeeded, false if it failed
      error - The error that occurred, or null if successful
    • onError

      public void onError(IServiceStatusListener.ErrorType type, String message, Throwable error)
      Description copied from interface: IServiceStatusListener
      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);
          }
      }
      
      Specified by:
      onError in interface IServiceStatusListener
      Parameters:
      type - The category of error
      message - A human-readable error message
      error - The underlying exception, or null if not applicable
      See Also:
    • onRecoveryRecommended

      public void onRecoveryRecommended(String reason, boolean autoRecoveryTriggered)
      Description copied from interface: IServiceStatusListener
      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();
                  }
              });
          }
      }
      
      Specified by:
      onRecoveryRecommended in interface IServiceStatusListener
      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

      public void onRecoveryCompleted(boolean success, Throwable error)
      Description copied from interface: IServiceStatusListener
      Called when automatic recovery completes.

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

      Specified by:
      onRecoveryCompleted in interface IServiceStatusListener
      Parameters:
      success - true if recovery succeeded and service is operational
      error - The error that occurred during recovery, or null if successful