de.ipcon.db.configuration

Interface DBManConfigurationHelperI

All Known Implementing Classes:

DBManConfigurationHelper

public interface DBManConfigurationHelperI

Interface helper for managing database configuration and access.

This interface acts as a wrapper around the underlying configuration storage (INI files), providing typed access to values and supporting change listeners.

Note: This interface is primarily intended for use in testing environments to facilitate mocking or specific test configurations.

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 lastModified) 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 defaultValue) Legacy method to get a value with a default from the Inifile.
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 defaultValue) 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 defaultValue) 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 defaultValue) 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.
void	removeEventListener(ConfChangeEventListenerI listener) Unregisters an existing configuration change listener.
void	save() Persists the current in-memory configuration to the file system.
void	setval(java.lang.String section, java.lang.String variable, java.lang.String value) Sets a configuration value.

Method Detail

addEventListener

void addEventListener(ConfChangeEventListenerI listener)

Registers a listener to receive notifications when the configuration changes.

Parameters:

listener - The ConfChangeEventListenerI to register.

removeEventListener

void removeEventListener(ConfChangeEventListenerI listener)

Unregisters an existing configuration change listener.

Parameters:

listener - The ConfChangeEventListenerI to remove.

fireConfChangeEvent

void fireConfChangeEvent()

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.

doUpdate

java.lang.String doUpdate(long lastModified)

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

Parameters:

lastModified - 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

java.lang.String doUpdate()

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

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

Returns:

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

getSourceFilePath

java.lang.String getSourceFilePath()

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.

Returns:

The file path of the configuration source as a String.

getInifileName

java.lang.String getInifileName()

Gets the name of the INI file currently being used.

Returns:

The filename of the INI configuration.

getConf

bini getConf()

Retrieves the underlying configuration object.

Returns:

The raw bini configuration object.

getErrorHandler

ErrorHandler getErrorHandler()

Retrieves the error handler associated with this configuration helper.

Returns:

The ErrorHandler instance.

getval

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

Legacy method to get a value from the Inifile.

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

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

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

Parameters:

section - The section name in the configuration file.

variable - The specific key/variable within that section.

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

Returns:

The resolved String value or the provided defaultValue.

getValueAsString

java.lang.String getValueAsString(java.lang.String section,
                                  java.lang.String variable)

Retrieves a configuration value as a String.

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

java.lang.String getValueAsString(java.lang.String section,
                                  java.lang.String variable,
                                  java.lang.String defaultValue)

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

Parameters:

section - The section name in the configuration file.

variable - The specific key/variable within that section.

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

Returns:

The resolved String value or the provided defaultValue.

getValueAsBool

boolean getValueAsBool(java.lang.String section,
                       java.lang.String variable)

Retrieves a configuration value parsed as a boolean.

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

boolean getValueAsBool(java.lang.String section,
                       java.lang.String variable,
                       boolean defaultValue)

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

Parameters:

section - The section name in the configuration file.

variable - The specific key/variable within that section.

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

Returns:

The resolved boolean value.

getValueAsInt

int getValueAsInt(java.lang.String section,
                  java.lang.String variable)

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

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

int getValueAsInt(java.lang.String section,
                  java.lang.String variable,
                  int defaultValue)

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

Parameters:

section - The section name in the configuration file.

variable - The specific key/variable within that section.

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

Returns:

The resolved integer value.

getvalWithUpdateAllowed

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.

Parameters:

section - The section name.

variable - The variable key.

Returns:

The resolved String value.

getSectionAsProperties

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

Gets a complete section wrapped into a Properties object.

Parameters:

section - The section name to retrieve.

Returns:

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

getSectionAsProperties

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

Gets a complete section wrapped into a Properties object.

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

boolean hasSection(java.lang.String section)

Checks if a specific section exists within the configuration.

Parameters:

section - The name of the section to verify.

Returns:

true if the section exists; false otherwise.

setval

void setval(java.lang.String section,
            java.lang.String variable,
            java.lang.String value)

Sets a configuration value.

Parameters:

section - The section name.

variable - The variable key.

value - The value to set.

commentOut

void commentOut(java.lang.String section,
                java.lang.String variable,
                java.lang.String comment)

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

Parameters:

section - The section containing the variable.

variable - The variable to comment out.

comment - The comment text to store (optional).

getCommentedOut

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.

Parameters:

section - The section name.

variable - The variable key.

Returns:

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

save

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

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.

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.

IRuntimeException - If the configuration was loaded from a stream, preventing a file-system write-back.