co.mindus.ip2location.ui

Class AdminIP2LocationPanel

java.lang.Object

se.entra.phantom.server.VirtualPanelAdapter

se.entra.phantom.server.VirtualComponentAdapter

co.mindus.ip2location.ui.AdminIP2LocationPanel

All Implemented Interfaces:

IServiceStatusListener, VirtualComponentListener, VirtualPanelListener

public class AdminIP2LocationPanel
extends VirtualComponentAdapter
implements IServiceStatusListener

NetPhantom panel controller for IP2Location service administration.

This class provides a comprehensive administration interface for the IP2Location geolocation service, allowing administrators to configure, monitor, and manage the service through a NetPhantom-based UI panel.

Features

• Enable/disable the IP2Location service
• Configure API token, database path, and database type
• Select IPv4-only or IPv4+IPv6 mode
• Enable/disable memory-mapped file access
• View real-time service status and database information
• Monitor error counters and recovery status
• Trigger manual database updates
• Access recovery settings and trigger recovery operations

Panel Structure

The panel is organized into three main sections:

1. Configuration - Service enable checkbox, API token, database path, database type combo box, IPv4/IPv6 radio buttons, memory-mapped checkbox
2. Status Display - Service status, next/last update times, database dates, error counters, and recovery status indicator
3. Action Buttons - Reconfigure, Update Now, Settings

Control ID Naming Conventions

NetPhantom control IDs follow these rules:

• Characters: A-Z, 0-9, underscore only
• Length: 1-8 characters maximum
• Cannot start with a digit

Control ID Reference

ID	Type	Description
Configuration Controls
ENABLED	CheckBox	Enable/disable service
TOKEN	TextField	API download token
DBPATH	TextField	Database directory path
DBLIST	ComboBox	Database type selection
IPV4	RadioButton	IPv4 only mode
IPV6	RadioButton	IPv4+IPv6 mode
MEMMAP	CheckBox	Memory-mapped file access
Status Display Controls
STATUS	Label	Service status text
NEXT	Label	Next scheduled update time
LAST	Label	Last successful update month
IP4DATE	Label	IPv4 database date
IP6DATE	Label	IPv6 database date
INITFAIL	Label	Init failure count
LOOKUPER	Label	Lookup error count
DLFAIL	Label	Download failure count
RECSTAT	Label	Recovery status (colored)
Action Buttons
RECONFIG	Button	Apply configuration changes
UPDATE	Button	Trigger immediate update
SETTINGS	Button	Open recovery settings
Context Menu Items
M_UPDATE	MenuItem	"Update Databases Now"
M_RECOV	MenuItem	"Trigger Recovery"
M_CLEAR	MenuItem	"Clear Recovery Alert"
M_HIST	MenuItem	"View Event History"
M_CLRERR	MenuItem	"Clear All Errors"
M_CLINIT	MenuItem	"Clear Init Errors"
M_CLLKUP	MenuItem	"Clear Lookup Errors"
M_CLDL	MenuItem	"Clear Download Error"
M_SET	MenuItem	"Recovery Settings..."

Context Menu

Right-clicking on the recovery status indicator (RECSTAT) shows a context menu with the following options:

1. Update Databases Now (M_UPDATE) - Triggers immediate database download
2. Trigger Recovery (M_RECOV) - Clears databases and re-downloads
3. Clear Recovery Alert (M_CLEAR) - Dismisses recovery recommendation
4. View Event History (M_HIST) - Shows error and event log
5. Clear All Errors (M_CLRERR) - Resets all error counts and download error
6. Clear Init Errors (M_CLINIT) - Resets init failure counter
7. Clear Lookup Errors (M_CLLKUP) - Resets lookup error counter
8. Clear Download Error (M_CLDL) - Resets download counter and RECSTAT error
9. Recovery Settings... (M_SET) - Opens settings dialog

Note: The context menu provides duplicate access to some toolbar button functions (Update Now, Settings) for convenience when the mouse is already over the status area.

Configuration Persistence

Configuration is stored in the server.ini file under the [IP2Location] section:

 [IP2Location]
 enabled=1
 token=YOUR_TOKEN
 dbPath=IP2Location
 dbName=DB11_LITE
 enableIPv6=0
 memoryMappedFile=1
 

Thread Safety

This class implements IServiceStatusListener to receive callbacks from background threads. All VirtualPanel methods are thread-safe and can be called from any thread.

Usage Example

 // In a NetPhantom notebook page initialization:
 VirtualPanel page = notebook.getPage("IP2Location");
 AdminIP2LocationPanel admin = new AdminIP2LocationPanel(page);
 page.setVirtualComponentListener(admin);
 

Author:

Christopher Mindus

See Also:

AdminIP2LocationSettingsPanel, IP2LocationManager, IServiceStatusListener

Nested Class Summary

Nested classes/interfaces inherited from interface co.mindus.ip2location.IServiceStatusListener

IServiceStatusListener.ErrorType

Field Summary

Fields inherited from interface se.entra.phantom.server.VirtualPanelListener

ICON_CRITICAL, ICON_INFORMATION, ICON_NOICON, ICON_QUERY, ICON_QUESTION, ICON_WARNING, MB_ABORTRETRYIGNORE, MB_CANCEL, MB_ENTER, MB_ENTERCANCEL, MB_OK, MB_OKCANCEL, MB_RETRYCANCEL, MB_YESNO, MB_YESNOCANCEL, MBID_CANCEL, MBID_DEFAULT, MBID_ENTER, MBID_IGNORE, MBID_NO, MBID_OK, MBID_RETRY, MBID_YES

Constructor Summary

Constructors

Constructor and Description
AdminIP2LocationPanel(VirtualPanel page) Constructs the panel controller and initializes the UI.

Method Summary

Modifier and Type	Method and Description
boolean	doReconfigure() Validates and applies configuration changes.
void	onAction(VirtualPanel panel, String controlID) Handles button clicks and menu item selections.
void	onCheckedChange(VirtualPanel panel, VirtualControl control, String controlID, int state) Handles checkbox and radio button state changes.
void	onDatabaseLoaded(LocalDate date, boolean isIPv6) Called when a database file has been loaded into memory.
void	onDatabaseUpdated(boolean ipv4Updated, boolean ipv6Updated) Called when databases are reloaded into memory.
void	onDownloadCompleted(boolean success) Called when a database download completes.
void	onDownloadStarted() Called when a database download starts.
void	onError(IServiceStatusListener.ErrorType type, String message, Throwable error) Called when an error occurs in the service.
void	onPanelDestroy(VirtualPanel vp) Called when the panel is being destroyed.
void	onRecoveryCompleted(boolean success, Throwable error) Called when automatic recovery completes.
void	onRecoveryRecommended(String reason, boolean autoRecoveryTriggered) Called when recovery is recommended.
void	onStatusChanged(String newStatus) Called when the service status description changes.
void	refreshStatus() Refreshes all status displays from the current service state.

Methods inherited from class se.entra.phantom.server.VirtualComponentAdapter

onAction, onAction, onContentChanged, onContentChanged, onControlEvent, onFocusGained, onFocusLost, onMenuAction, onPropertyChange, onSelectionChanged

Methods inherited from class se.entra.phantom.server.VirtualPanelAdapter

onModalPanelCreate, onModalPanelProcessing, onPageActivated, onPanelClose, onPanelClosing, onPanelCreate

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface co.mindus.ip2location.IServiceStatusListener

onInitialized, onReconfigurationCompleted, onReconfigurationStarted, onServiceDisposed, onUpdateCheckPerformed

Methods inherited from interface se.entra.phantom.server.VirtualPanelListener

onPageActivated, onPanelClose, onPanelClosing, onPanelCreate

Constructor Detail

AdminIP2LocationPanel

public AdminIP2LocationPanel(VirtualPanel page)

Constructs the panel controller and initializes the UI.

This constructor performs the following initialization:

1. Stores the panel reference
2. Loads saved configuration into UI controls
3. Populates the database combo box with all database types
4. Updates all status displays
5. Registers as a listener for service status updates

Parameters:

page - The VirtualPanel for this administration page (not null)

Method Detail

refreshStatus

public void refreshStatus()

Refreshes all status displays from the current service state.

Updates the following displays:

• Service status text
• Next scheduled update time
• Last successful update month
• IPv4 and IPv6 database dates
• Error counters (init failures, lookup errors, download failures)
• Recovery status indicator (colors and text)

This method is called during initialization and whenever the service status changes.

onCheckedChange

public void onCheckedChange(VirtualPanel panel,
                            VirtualControl control,
                            String controlID,
                            int state)

Handles checkbox and radio button state changes.

Called by NetPhantom when the user changes a checkbox or radio button. Currently handles the service enable checkbox to enable/disable other controls.

Specified by:

onCheckedChange in interface VirtualComponentListener

Overrides:

onCheckedChange in class VirtualComponentAdapter

Parameters:

panel - The panel containing the control (same as this.page)

control - The control that changed

controlID - The control's ID string

state - The new state: 0=unchecked, 1=checked, 2=indeterminate

onAction

public void onAction(VirtualPanel panel,
                     String controlID)

Handles button clicks and menu item selections.

Called by NetPhantom when the user clicks a button or selects a context menu item. Routes to the appropriate action method.

Overrides:

onAction in class VirtualComponentAdapter

Parameters:

panel - The panel containing the control (same as this.page)

controlID - The button or menu item ID string

doReconfigure

public boolean doReconfigure()

Validates and applies configuration changes.

This method performs the following steps:

1. Reads all values from UI controls
2. Validates required fields (token, database path) when enabled
3. Saves all settings to the server.ini file
4. Builds a new IP2LocationService.Builder with the settings
5. Reconfigures the running service via IP2LocationManager

If validation fails, an error message box is shown and focus is set to the offending field.

Returns:

true if configuration was applied successfully, false if validation failed

onPanelDestroy

public void onPanelDestroy(VirtualPanel vp)

Called when the panel is being destroyed.

Unregisters from service status updates to prevent memory leaks and callbacks to a disposed panel.

Specified by:

onPanelDestroy in interface VirtualPanelListener

Overrides:

onPanelDestroy in class VirtualPanelAdapter

Parameters:

vp - The panel being destroyed (same as this.page)

onStatusChanged

public void onStatusChanged(String newStatus)

Called when the service status description changes.

Updates the status label in the UI. This is called from a background thread, but VirtualPanel methods are thread-safe.

Specified by:

onStatusChanged in interface IServiceStatusListener

Parameters:

newStatus - The new status description string

See Also:

IP2LocationManager.getStatusDescription(), IP2LocationService.getStatusDescription()

onDownloadStarted

public void onDownloadStarted()

Called when a database download starts.

Updates the recovery status indicator to show "working" state.

Specified by:

onDownloadStarted in interface IServiceStatusListener

onDownloadCompleted

public void onDownloadCompleted(boolean success)

Called when a database download completes.

Refreshes all status displays to show new database information.

Specified by:

onDownloadCompleted in interface IServiceStatusListener

Parameters:

success - true if the download succeeded

onDatabaseLoaded

public void onDatabaseLoaded(LocalDate date,
                             boolean isIPv6)

Called when a database file has been loaded into memory.

Updates the corresponding database date field in the UI.

Specified by:

onDatabaseLoaded in interface IServiceStatusListener

Parameters:

date - The publication date of the loaded database

isIPv6 - true for IPv6, false for IPv4

onDatabaseUpdated

public void onDatabaseUpdated(boolean ipv4Updated,
                              boolean ipv6Updated)

Called when databases are reloaded into memory.

Refreshes status to show new database dates.

Specified by:

onDatabaseUpdated in interface IServiceStatusListener

Parameters:

ipv4Updated - true if IPv4 database was reloaded

ipv6Updated - true if IPv6 database was reloaded

onRecoveryRecommended

public void onRecoveryRecommended(String reason,
                                  boolean autoRecoveryTriggered)

Called when recovery is recommended.

Updates the status display and shows a notification message if automatic recovery was not triggered.

Specified by:

onRecoveryRecommended in interface IServiceStatusListener

Parameters:

reason - The reason recovery is recommended

autoRecoveryTriggered - true if automatic recovery was initiated

See Also:

IP2LocationManager.isRecoveryRecommended(), IP2LocationManager.triggerRecovery()

onRecoveryCompleted

public void onRecoveryCompleted(boolean success,
                                Throwable error)

Called when automatic recovery completes.

Refreshes status and shows result to user.

Specified by:

onRecoveryCompleted in interface IServiceStatusListener

Parameters:

success - true if recovery succeeded

error - The error that occurred, or null if successful

onError

public void onError(IServiceStatusListener.ErrorType type,
                    String message,
                    Throwable error)

Called when an error occurs in the service.

Updates error counters display. Severe errors may trigger recovery recommendation which is handled separately by onRecoveryRecommended(String, boolean).

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:

IServiceStatusListener.ErrorType