de.ipcon.db.configuration

Class DBManConfigurationHelper

java.lang.Object

de.ipcon.db.configuration.DBManConfigurationHelper

All Implemented Interfaces:

DBManConfigurationHelperI

public final class DBManConfigurationHelper
extends java.lang.Object
implements DBManConfigurationHelperI

Monitors a configuration file for changes and triggers updates.

This class provides functionality to watch a specified configuration file for any modifications. When a change is detected, it initiates an update process by notifying the registered ConfChangeEventListenerI-s to ensure that the application's configuration remains consistent with the latest changes in the file.

Constructor Summary

Constructors

Constructor and Description
DBManConfigurationHelper(java.io.File _confFile) Constructs a DBManConfigurationHelper to monitor the specified configuration file.

Method Summary

Modifier and Type	Method and Description
void	addEventListener(ConfChangeEventListenerI listener) Registers a listener to receive notifications when the configuration changes.
void	commentOut(java.lang.String _section, java.lang.String _variable, java.lang.String _comment) Comments out a specific variable in memory only.
java.lang.String	doUpdate() Checks for updates using the internal last-modified timestamp stored in the properties.
java.lang.String	doUpdate(long l) Performs a semi-automatic reload if the configuration file on disk is newer than the specified timestamp.
void	fireConfChangeEvent() Fires a configuration change event to all registered listeners.
java.lang.String	getCommentedOut(java.lang.String _section, java.lang.String _variable) Retrieves the comment text of a commented-out value of a variable, if it exists.
bini	getConf() Retrieves the underlying configuration object.
ErrorHandler	getErrorHandler() Retrieves the error handler associated with this configuration helper.
java.lang.String	getInifileName() Gets the name of the INI file currently being used.
java.util.Properties	getSectionAsProperties(java.lang.String section) Gets a complete section wrapped into a Properties object.
java.util.Properties	getSectionAsProperties(java.lang.String section, java.util.Properties props) Gets a complete section wrapped into a Properties object.
java.lang.String	getSourceFilePath() Returns the absolute path where the configuration file is located.
java.lang.String	getval(java.lang.String section, java.lang.String variable) Legacy method to get a value from the Inifile.
java.lang.String	getval(java.lang.String section, java.lang.String variable, java.lang.String $default) Legacy method to get a value with a default from the Inifile.
java.lang.String	getvalAndVerify(java.lang.String section, java.lang.String variable, java.lang.String $default, netrexx.lang.Rexx props)
boolean	getValueAsBool(java.lang.String _section, java.lang.String _variable) Retrieves a configuration value parsed as a boolean.
boolean	getValueAsBool(java.lang.String _section, java.lang.String _variable, boolean _default) Retrieves a configuration value parsed as a boolean, falling back to a default.
int	getValueAsInt(java.lang.String _section, java.lang.String _variable) Retrieves a configuration value parsed as an integer, falling back to a default.
int	getValueAsInt(java.lang.String _section, java.lang.String _variable, int _default) Retrieves a configuration value parsed as an integer, falling back to a default.
java.lang.String	getValueAsString(java.lang.String _section, java.lang.String _variable) Retrieves a configuration value as a String.
java.lang.String	getValueAsString(java.lang.String _section, java.lang.String _variable, java.lang.String _default) Retrieves a configuration value as a String, falling back to a default.
java.lang.String	getvalWithUpdateAllowed(java.lang.String section, java.lang.String variable) Gets a value from the INI file, reloading it if necessary before retrieval.
boolean	hasSection(java.lang.String section) Checks if a specific section exists within the configuration.
java.lang.String	mergeStateWithSource(java.io.BufferedReader _reader)
void	removeEventListener(ConfChangeEventListenerI listener) Unregisters an existing configuration change listener.
void	save() Persists the current in-memory configuration to the file system.
java.lang.String	save(java.io.BufferedReader _reader) Deprecated. use mergeStateWithSource(BufferedReader)
void	setSourceFilePath(java.lang.String $14)
void	setval(java.lang.String _section, java.lang.String _variable, java.lang.String _value) Sets a configuration value.
java.nio.file.WatchService	startWatchService() Starts a WatchService for the watched path.
void	stopWatchService(java.nio.file.WatchService watcher) Stops the WatchService.

Methods inherited from class java.lang.Object

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

Constructor Detail

DBManConfigurationHelper

public DBManConfigurationHelper(java.io.File _confFile)
                         throws java.io.IOException,
                                java.io.FileNotFoundException

Constructs a DBManConfigurationHelper to monitor the specified configuration file.

Parameters:

_confFile - The configuration file to monitor.

Throws:

IOException - If an I/O error occurs while accessing the file.

FileNotFoundException - If the specified file does not exist.

Method Detail

startWatchService

public java.nio.file.WatchService startWatchService()
                                             throws java.io.IOException

Starts a WatchService for the watched path.

Returns:

The WatchService instance.

Throws:

IOException - If an I/O error occurs.

stopWatchService

public void stopWatchService(java.nio.file.WatchService watcher)

Stops the WatchService.

Parameters:

watcher - The WatchService instance to stop.

addEventListener

public void addEventListener(ConfChangeEventListenerI listener)

Description copied from interface: DBManConfigurationHelperI

Registers a listener to receive notifications when the configuration changes.

Specified by:

addEventListener in interface DBManConfigurationHelperI

Parameters:

listener - The ConfChangeEventListenerI to register.

removeEventListener

public void removeEventListener(ConfChangeEventListenerI listener)

Description copied from interface: DBManConfigurationHelperI

Unregisters an existing configuration change listener.

Specified by:

removeEventListener in interface DBManConfigurationHelperI

Parameters:

listener - The ConfChangeEventListenerI to remove.

fireConfChangeEvent

public void fireConfChangeEvent()

Description copied from interface: DBManConfigurationHelperI

Fires a configuration change event to all registered listeners.

This method creates a new ConfChangeEvent with the current last modified time of the configuration file and notifies all registered listeners by calling their ConfChangeEventListenerI.processConfChangeEvent(ConfChangeEvent) method. If a listener throws an exception, it is logged as an error.

Specified by:

fireConfChangeEvent in interface DBManConfigurationHelperI

doUpdate

public java.lang.String doUpdate(long l)

Description copied from interface: DBManConfigurationHelperI

Performs a semi-automatic reload if the configuration file on disk is newer than the specified timestamp.

Specified by:

doUpdate in interface DBManConfigurationHelperI

Parameters:

l - The timestamp (in milliseconds) of the current configuration to check against.

Returns:

A String containing the new modification timestamp if an update occurred, or "0" if the file has not changed.

doUpdate

public java.lang.String doUpdate()

Description copied from interface: DBManConfigurationHelperI

Checks for updates using the internal last-modified timestamp stored in the properties.

This behaves similarly to DBManConfigurationHelperI.doUpdate(long), but automatically uses the current known timestamp of the loaded configuration.

Specified by:

doUpdate in interface DBManConfigurationHelperI

Returns:

"1" if an update occurred, or "0" if the update was not necessary.

getInifileName

public java.lang.String getInifileName()

Description copied from interface: DBManConfigurationHelperI

Gets the name of the INI file currently being used.

Specified by:

getInifileName in interface DBManConfigurationHelperI

Returns:

The filename of the INI configuration.

getConf

public bini getConf()

Description copied from interface: DBManConfigurationHelperI

Retrieves the underlying configuration object.

Specified by:

getConf in interface DBManConfigurationHelperI

Returns:

The raw bini configuration object.

getErrorHandler

public ErrorHandler getErrorHandler()

Description copied from interface: DBManConfigurationHelperI

Retrieves the error handler associated with this configuration helper.

Specified by:

getErrorHandler in interface DBManConfigurationHelperI

Returns:

The ErrorHandler instance.

getvalAndVerify

public java.lang.String getvalAndVerify(java.lang.String section,
                                        java.lang.String variable,
                                        java.lang.String $default,
                                        netrexx.lang.Rexx props)
                                 throws java.lang.IllegalArgumentException

Throws:

java.lang.IllegalArgumentException

getval

public java.lang.String getval(java.lang.String section,
                               java.lang.String variable)

Description copied from interface: DBManConfigurationHelperI

Legacy method to get a value from the Inifile.

Specified by:

getval in interface DBManConfigurationHelperI

Parameters:

section - The section name in the configuration file.

variable - The specific key/variable within that section.

Returns:

The resolved String value, or null if not found.

getval

public java.lang.String getval(java.lang.String section,
                               java.lang.String variable,
                               java.lang.String $default)

Description copied from interface: DBManConfigurationHelperI

Legacy method to get a value with a default from the Inifile.

Specified by:

getval in interface DBManConfigurationHelperI

Parameters:

section - The section name in the configuration file.

variable - The specific key/variable within that section.

$default - The value to return if the section or variable is missing.

Returns:

The resolved String value or the provided defaultValue.

getValueAsString

public java.lang.String getValueAsString(java.lang.String _section,
                                         java.lang.String _variable)

Description copied from interface: DBManConfigurationHelperI

Retrieves a configuration value as a String.

Specified by:

getValueAsString in interface DBManConfigurationHelperI

Parameters:

_section - The section name in the configuration file.

_variable - The specific key/variable within that section.

Returns:

The resolved String value, or null if not found.

getValueAsString

public java.lang.String getValueAsString(java.lang.String _section,
                                         java.lang.String _variable,
                                         java.lang.String _default)

Description copied from interface: DBManConfigurationHelperI

Retrieves a configuration value as a String, falling back to a default.

Specified by:

getValueAsString in interface DBManConfigurationHelperI

Parameters:

_section - The section name in the configuration file.

_variable - The specific key/variable within that section.

_default - The value to return if the section or variable is missing.

Returns:

The resolved String value or the provided defaultValue.

getValueAsBool

public boolean getValueAsBool(java.lang.String _section,
                              java.lang.String _variable)

Description copied from interface: DBManConfigurationHelperI

Retrieves a configuration value parsed as a boolean.

Specified by:

getValueAsBool in interface DBManConfigurationHelperI

Parameters:

_section - The section name in the configuration file.

_variable - The specific key/variable within that section.

Returns:

The resolved boolean value, or false if not found.

getValueAsBool

public boolean getValueAsBool(java.lang.String _section,
                              java.lang.String _variable,
                              boolean _default)

Description copied from interface: DBManConfigurationHelperI

Retrieves a configuration value parsed as a boolean, falling back to a default.

Specified by:

getValueAsBool in interface DBManConfigurationHelperI

Parameters:

_section - The section name in the configuration file.

_variable - The specific key/variable within that section.

_default - The boolean value to return if the entry is missing or cannot be parsed.

Returns:

The resolved boolean value.

getValueAsInt

public int getValueAsInt(java.lang.String _section,
                         java.lang.String _variable)

Description copied from interface: DBManConfigurationHelperI

Retrieves a configuration value parsed as an integer, falling back to a default.

Specified by:

getValueAsInt in interface DBManConfigurationHelperI

Parameters:

_section - The section name in the configuration file.

_variable - The specific key/variable within that section.

Returns:

The resolved integer value, or 0 if not found.

getValueAsInt

public int getValueAsInt(java.lang.String _section,
                         java.lang.String _variable,
                         int _default)

Description copied from interface: DBManConfigurationHelperI

Retrieves a configuration value parsed as an integer, falling back to a default.

Specified by:

getValueAsInt in interface DBManConfigurationHelperI

Parameters:

_section - The section name in the configuration file.

_variable - The specific key/variable within that section.

_default - The integer value to return if the entry is missing or cannot be parsed.

Returns:

The resolved integer value.

getvalWithUpdateAllowed

public java.lang.String getvalWithUpdateAllowed(java.lang.String section,
                                                java.lang.String variable)

Description copied from interface: DBManConfigurationHelperI

Gets a value from the INI file, reloading it if necessary before retrieval.

Specified by:

getvalWithUpdateAllowed in interface DBManConfigurationHelperI

Parameters:

section - The section name.

variable - The variable key.

Returns:

The resolved String value.

getSectionAsProperties

public java.util.Properties getSectionAsProperties(java.lang.String section)

Description copied from interface: DBManConfigurationHelperI

Gets a complete section wrapped into a Properties object.

Specified by:

getSectionAsProperties in interface DBManConfigurationHelperI

Parameters:

section - The section name to retrieve.

Returns:

A Properties object containing the section's key-value pairs.

getSectionAsProperties

public java.util.Properties getSectionAsProperties(java.lang.String section,
                                                   java.util.Properties props)

Description copied from interface: DBManConfigurationHelperI

Gets a complete section wrapped into a Properties object.

Specified by:

getSectionAsProperties in interface DBManConfigurationHelperI

Parameters:

section - The section name to retrieve.

props - An existing Properties object to populate, or null to create a new one.

Returns:

A Properties object containing the section's key-value pairs.

hasSection

public boolean hasSection(java.lang.String section)

Description copied from interface: DBManConfigurationHelperI

Checks if a specific section exists within the configuration.

Specified by:

hasSection in interface DBManConfigurationHelperI

Parameters:

section - The name of the section to verify.

Returns:

true if the section exists; false otherwise.

setval

public void setval(java.lang.String _section,
                   java.lang.String _variable,
                   java.lang.String _value)

Description copied from interface: DBManConfigurationHelperI

Sets a configuration value.

Specified by:

setval in interface DBManConfigurationHelperI

Parameters:

_section - The section name.

_variable - The variable key.

_value - The value to set.

commentOut

public void commentOut(java.lang.String _section,
                       java.lang.String _variable,
                       java.lang.String _comment)

Description copied from interface: DBManConfigurationHelperI

Comments out a specific variable in memory only. Will be written to the file once is called.

Specified by:

commentOut in interface DBManConfigurationHelperI

Parameters:

_section - The section containing the variable.

_variable - The variable to comment out.

_comment - The comment text to store (optional).

getCommentedOut

public java.lang.String getCommentedOut(java.lang.String _section,
                                        java.lang.String _variable)

Description copied from interface: DBManConfigurationHelperI

Retrieves the comment text of a commented-out value of a variable, if it exists.

Specified by:

getCommentedOut in interface DBManConfigurationHelperI

Parameters:

_section - The section name.

_variable - The variable key.

Returns:

The comment text of a commented-out value, or null if not found.

save

public void save()
          throws java.io.IOException,
                 java.io.FileNotFoundException

Description copied from interface: DBManConfigurationHelperI

Persists the current in-memory configuration to the file system.

This method reads the original configuration file to preserve formatting and comments, merges the current values, and overwrites the current configuration file.

Specified by:

save in interface DBManConfigurationHelperI

Throws:

java.io.IOException - If an I/O error occurs while reading the template or writing the file.

java.io.FileNotFoundException - If the source file cannot be found.

save

@Deprecated
public java.lang.String save(java.io.BufferedReader _reader)

Deprecated. use mergeStateWithSource(BufferedReader)

mergeStateWithSource

public java.lang.String mergeStateWithSource(java.io.BufferedReader _reader)

getSourceFilePath

public java.lang.String getSourceFilePath()

Description copied from interface: DBManConfigurationHelperI

Returns the absolute path where the configuration file is located.

This is particularly useful for generating detailed error messages, logging, and debugging configuration loading issues.

Specified by:

getSourceFilePath in interface DBManConfigurationHelperI

Returns:

The file path of the configuration source as a String.

setSourceFilePath

public void setSourceFilePath(java.lang.String $14)