Configuration variables

Configuration data is stored as a set of variables organised in sections. A typical variable name is: section.subsection.name where:

• section and subsection are both sections.
• name is the variable's name.

Configuration data is stored in instances of {@link com.mucommander.conf.Configuration}, which offers a set of methods manipulate variables:

• {@link com.mucommander.conf.Configuration#getVariable(String) Basic retrieval}, which returns a variable's value if known.
• {@link com.mucommander.conf.Configuration#getVariable(String,String) Advanced retrieval}, which returns a variable's value and set it to a default value if not known.
• Existence {@link com.mucommander.conf.Configuration#isVariableSet(String) checking}, which checks whether a variable exists or not.
• {@link com.mucommander.conf.Configuration#renameVariable(String,String) Renaming}, which changes a variable's name as well as the section it belongs to.
• {@link com.mucommander.conf.Configuration#removeVariable(String) Removal}, which deletes a variable from the configuration.
• {@link com.mucommander.conf.Configuration#setVariable(String,String) Setting}, which sets a variable's value.

Loading and storing configuration

The com.mucommander.conf package offers various ways of loading and storing configuration.
The most obvious way is by using the {@link com.mucommander.conf.Configuration#read(InputStream) read} and {@link com.mucommander.conf.Configuration#write(OutputStream) write} methods, but this has the disadvantage of forcing application writers to manage streams themselves.
The preferred method is to create a dedicated {@link com.mucommander.conf.ConfigurationSource} class and register it through {@link com.mucommander.conf.Configuration#setSource(ConfigurationSource) setSource}. This allows an instance of {@link com.mucommander.conf.Configuration} to know how to read from and write to its configuration file (or socket or any other medium that provides input and output streams).

Changing the default configuration format

The default configuration format is described in {@link com.mucommander.conf.XmlConfigurationReader}. Application writers who wish to change this can do so by:

• Creating custom {@link com.mucommander.conf.ConfigurationWriter writers} and {@link com.mucommander.conf.ConfigurationReader readers}.
• Creating associated {@link com.mucommander.conf.ConfigurationWriterFactory writer factories} and {@link com.mucommander.conf.ConfigurationReaderFactory reader factories}.
• Registering them through {@link com.mucommander.conf.Configuration#setWriterFactory(ConfigurationWriterFactory) setWriterFactory} and {@link com.mucommander.conf.Configuration#setReaderFactory(ConfigurationReaderFactory) setReaderFactory}.

Listening to the configuration

Classes that need to be notified when the configuration has changed can do so by:

• Implementing the {@link com.mucommander.conf.ConfigurationListener} interface.
• Registering themselves through {@link com.mucommander.conf.Configuration#addConfigurationListener(ConfigurationListener) addConfigurationLister}.