Configuration (muCommander API)

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

com.mucommander.conf
Class Configuration

java.lang.Object
  com.mucommander.conf.Configuration

public class Configuration
extends java.lang.Object
extends java.lang.Object

Base class for all configuration related tasks.

A Configuration instance's main goal is to act as a configuration data repository. Once created, it can be used to retrieve, delete and set configuration variables.

Naming conventions

Configuration variable names follow the same convention as Java System properties: a serie of strings separated by periods. By convention, all but the last string are called configuration sections, while the last one is the variable's name. When we refer to a variable's fully qualified name, we're talking about the whole period-separated name.
For example, startup_folder.right.last_folder is interpreted as a variable called last_folder contained in a section called right, itself contained in another section called startup_folder.

Variable types

While the com.mucommander.conf really only handles one type of variables, strings, it offers tools to cast them as primitive Java types (int, long, float, double, boolean). This is done through the use of the various primitive types' class implementation parseXXX method.
When a variable hasn't been set but ant attempt is made to cast it, the standard Java default value will be returned:

String: null
Integer: 0
Long: 0
Float: 0
Double: 0
Boolean: false

Configuration file format

By default, configuration data is assumed to be in the standard muCommander file format (described in XmlConfigurationReader). However, application writers can modify that to any format they want through the setReaderFactory and setWriterFactory methods.

Configuration data location

While Configuration provides read and write methods that accept streams as parameters, it's also possible to set the data source once and for all and let the API deal with the details. This can be achieved through the setSource method.
Note that a default implementation, FileConfigurationSource, is provided. It covers the most common case of configuration sources, a local configuration file.
For application writers who wish to be able to retrieve configuration files through a variety of file systems, we suggest creating a source using the com.mucommander.file API.

Monitoring configuration changes

Classes that need to monitor the state of the configuration in order, for example, to react to changes dynamically rather than wait for an application reboot can implement the ConfigurationListener interface and register themselves through addConfigurationListener. This guarantees that they will receive configuration events whenever a modification occurs.
Note that listeners are stored as weak references, meaning that application writers must ensure that they keep direct references to the listener instances they register if they do not want them to be garbaged collected out of existence randomly.

Author:: Nicolas Rinaudo

Constructor Summary
`Configuration()` Creates a new instance of `Configuration`.
`Configuration(ConfigurationReaderFactory reader, ConfigurationWriterFactory writer)` Creates a new instance of `Configuration` using the specified format.
`Configuration(ConfigurationSource source)` Creates a new instance of `Configuration` using the specified source.
`Configuration(ConfigurationSource source, ConfigurationReaderFactory reader, ConfigurationWriterFactory writer)` Creates a new instance of `Configuration` using the specified source and format.

Method Summary
`static void`	`addConfigurationListener(ConfigurationListener listener)` Adds the specified object to the list of registered configuration listeners.
`void`	`build(ConfigurationBuilder builder)` Explores the whole configuration tree and invokes the specified builder's callback methods.
`boolean`	`getBooleanVariable(java.lang.String name)` Returns the value of the specified variable as a boolean.
`double`	`getDoubleVariable(java.lang.String name)` Returns the value of the specified variable as a double.
`float`	`getFloatVariable(java.lang.String name)` Returns the value of the specified variable as a float.
`int`	`getIntegerVariable(java.lang.String name)` Returns the value of the specified variable as an integer.
`ValueList`	`getListVariable(java.lang.String name, java.lang.String separator)` Returns the value of the specified variable as a `ValueList`.
`long`	`getLongVariable(java.lang.String name)` Returns the value of the specified variable as a long.
`ConfigurationReader`	`getReader()` Returns an instance of the class that will be used to read configuration data.
`ConfigurationReaderFactory`	`getReaderFactory()` Returns the factory that is being used to create `reader` instances.
`ConfigurationSource`	`getSource()` Returns the current configuration source.
`java.lang.String`	`getVariable(java.lang.String name)` Returns the value of the specified variable.
`boolean`	`getVariable(java.lang.String name, boolean defaultValue)` Retrieves the value of the specified variable as a boolean.
`double`	`getVariable(java.lang.String name, double defaultValue)` Retrieves the value of the specified variable as a double.
`float`	`getVariable(java.lang.String name, float defaultValue)` Retrieves the value of the specified variable as a float.
`int`	`getVariable(java.lang.String name, int defaultValue)` Retrieves the value of the specified variable as an integer.
`ValueList`	`getVariable(java.lang.String name, java.util.List defaultValue, java.lang.String separator)` Retrieves the value of the specified variable as a `ValueList`.
`long`	`getVariable(java.lang.String name, long defaultValue)` Retrieves the value of the specified variable as a long.
`java.lang.String`	`getVariable(java.lang.String name, java.lang.String defaultValue)` Retrieves the value of the specified variable.
`ConfigurationWriter`	`getWriter()` Returns an instance of the class that will be used to write configuration data.
`ConfigurationWriterFactory`	`getWriterFactory()` Returns the factory that is being used to create `writer` instances.
`boolean`	`isVariableSet(java.lang.String name)` Checks whether the specified variable has been set.
`void`	`read()` Loads configuration.
`void`	`read(ConfigurationReader reader)` Loads configuration using the specified configuration reader.
`void`	`read(java.io.InputStream in)` Loads configuration from the specified input stream.
`boolean`	`removeBooleanVariable(java.lang.String name)` Deletes the specified variable from the configuration.
`static void`	`removeConfigurationListener(ConfigurationListener listener)` Removes the specified object from the list of registered configuration listeners.
`double`	`removeDoubleVariable(java.lang.String name)` Deletes the specified variable from the configuration.
`float`	`removeFloatVariable(java.lang.String name)` Deletes the specified variable from the configuration.
`int`	`removeIntegerVariable(java.lang.String name)` Deletes the specified variable from the configuration.
`ValueList`	`removeListVariable(java.lang.String name, java.lang.String separator)` Deletes the specified variable from the configuration.
`long`	`removeLongVariable(java.lang.String name)` Deletes the specified variable from the configuration.
`java.lang.String`	`removeVariable(java.lang.String name)` Deletes the specified variable from the configuration.
`void`	`renameVariable(java.lang.String fromVar, java.lang.String toVar)` Moves the value of `fromVar` to `toVar`.
`void`	`setReaderFactory(ConfigurationReaderFactory f)` Sets the factory that will be used to create `reader` instances.
`void`	`setSource(ConfigurationSource s)` Sets the source that will be used to read and write configuration information.
`boolean`	`setVariable(java.lang.String name, boolean value)` Sets the value of the specified variable.
`boolean`	`setVariable(java.lang.String name, double value)` Sets the value of the specified variable.
`boolean`	`setVariable(java.lang.String name, float value)` Sets the value of the specified variable.
`boolean`	`setVariable(java.lang.String name, int value)` Sets the value of the specified variable.
`boolean`	`setVariable(java.lang.String name, java.util.List value, java.lang.String separator)` Sets the value of the specified variable.
`boolean`	`setVariable(java.lang.String name, long value)` Sets the value of the specified variable.
`boolean`	`setVariable(java.lang.String name, java.lang.String value)` Sets the value of the specified variable.
`void`	`setWriterFactory(ConfigurationWriterFactory f)` Sets the factory that will be used to create `writer` instances.
`void`	`write()` Writes configuration.
`void`	`write(ConfigurationWriter writer)` Writes configuration using the specified writer.
`void`	`write(java.io.OutputStream out)` Writes configuration to the specified output stream.
`void`	`write(java.io.OutputStream out, ConfigurationWriter writer)` Writes configuration to the specified output stream using the specified writer.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

Configuration

public Configuration()

Creates a new instance of Configuration.

The resulting instance will use the default reader and writer factories, XmlConfigurationReaderFactory and XmlConfigurationWriterFactory.

Note that until the setSource method has been invoked, calls to read or write methods without a stream parameter will fail.

Configuration

public Configuration(ConfigurationSource source)

Creates a new instance of Configuration using the specified source.

The resulting instance will use the default reader and writer factories, XmlConfigurationReaderFactory and XmlConfigurationWriterFactory.

Parameters:: source - where the resulting instance will look for its configuration data.

Configuration

public Configuration(ConfigurationReaderFactory reader,
                     ConfigurationWriterFactory writer)

Creates a new instance of Configuration using the specified format.

Note that until the setSource method has been invoked, calls to read or write methods without a stream parameter will fail.

Parameters:: reader - object that will be used to create ConfigurationReader instances.; writer - object that will be used to create ConfigurationWriter instances.

Configuration

public Configuration(ConfigurationSource source,
                     ConfigurationReaderFactory reader,
                     ConfigurationWriterFactory writer)

Creates a new instance of Configuration using the specified source and format.

Parameters:: source - where the resulting instance will look for its configuration data.; reader - object that will be used to create ConfigurationReader instances.; writer - object that will be used to create ConfigurationWriter instances.

Method Detail

setSource

public void setSource(ConfigurationSource s)

Sets the source that will be used to read and write configuration information.

Parameters:: s - new configuration source.
See Also:: getSource()

getSource

public ConfigurationSource getSource()

Returns the current configuration source.

Returns:: the current configuration source, or null if it hasn't been set.
See Also:: setSource(ConfigurationSource)

setReaderFactory

public void setReaderFactory(ConfigurationReaderFactory f)

Sets the factory that will be used to create reader instances.

In order to reset the configuration to its default reader factory (XmlConfigurationReaderFactory), application writers can call setReaderFactory(null);.

Parameters:: f - factory that will be used to create reader instances.
See Also:: getReader(), getReaderFactory()

getReaderFactory

public ConfigurationReaderFactory getReaderFactory()

Returns the factory that is being used to create reader instances.

By default, this method will return an instance of XmlConfigurationReaderFactory. However, this can be modified by calling setReaderFactory.

Returns:: the factory that is being used to create reader instances.
See Also:: getReader(), setReaderFactory(ConfigurationReaderFactory)

getReader

public ConfigurationReader getReader()
                              throws ReaderConfigurationException

Returns an instance of the class that will be used to read configuration data.

By default, this method will return an instance of XmlConfigurationReader. However, this can be modified by calling setReaderFactory.

Returns:: an instance of the class that will be used to read configuration data.
Throws:: ReaderConfigurationException - any configuration reader error, possibly wrapping another exception.
See Also:: setReaderFactory(ConfigurationReaderFactory), getReaderFactory()

setWriterFactory

public void setWriterFactory(ConfigurationWriterFactory f)

Sets the factory that will be used to create writer instances.

In order to reset the configuration to its default writer factory (XmlConfigurationWriterFactory), application writers can call setWriterFactory(null);.

Parameters:: f - factory that will be used to create writer instances.
See Also:: getWriterFactory(), getWriter()

getWriterFactory

public ConfigurationWriterFactory getWriterFactory()

Returns the factory that is being used to create writer instances.

By default, this method will return an instance of XmlConfigurationWriterFactory. However, this can be modified by calling setWriterFactory.

Returns:: the factory that is being used to create writer instances.
See Also:: setWriterFactory(ConfigurationWriterFactory), getWriter()

getWriter

public ConfigurationWriter getWriter()
                              throws WriterConfigurationException

Returns an instance of the class that will be used to write configuration data.

By default, this method will return an instance of XmlConfigurationWriter. However, this can be modified by setWriterFactory.

Returns:: an instance of the class that will be used to read configuration data.
Throws:: WriterConfigurationException - any configuration writer error, possibly wrapping another exception.
See Also:: setWriterFactory(ConfigurationWriterFactory), getWriterFactory()

read

public void read(java.io.InputStream in)
          throws ConfigurationException,
                 java.io.IOException

Loads configuration from the specified input stream.

This method will use the configuration reader set by setReaderFactory(ConfigurationReaderFactory) if any, or an XmlConfigurationReader instance if not.

Parameters:: in - where to read the configuration from.
Throws:: ConfigurationException - if a configuration error occurs.; ConfigurationFormatException - if a syntax error occurs in the configuration data.; ConfigurationStructureException - if the configuration data doesn't describe a valid configuration tree.; ReaderConfigurationException - if the ConfigurationReaderFactory isn't properly configured.; java.io.IOException - if an I/O error occurs.
See Also:: write(OutputStream), read(), read(ConfigurationReader), read(InputStream,ConfigurationReader)

read

public void read(ConfigurationReader reader)
          throws java.io.IOException,
                 ConfigurationException

Loads configuration using the specified configuration reader.

This method will use the input stream provided by setSource(ConfigurationSource) if any, or fail otherwise.

Parameters:: reader - reader that will be used to interpret the content of in.
Throws:: java.io.IOException - if an I/O error occurs.; ConfigurationException - if a configuration error occurs.; SourceConfigurationException - if no ConfigurationSource has been set.; ConfigurationFormatException - if a syntax error occurs in the configuration data.; ConfigurationStructureException - if the configuration data doesn't describe a valid configuration tree.
See Also:: write(ConfigurationWriter), read(InputStream), read(), read(InputStream,ConfigurationReader)

read

public void read()
          throws ConfigurationException,
                 java.io.IOException

Loads configuration.

If a reader has been specified through setReaderFactory(ConfigurationReaderFactory), it will be used to analyse the configuration. Otherwise, an XmlConfigurationReader instance will be used.

If a configuration source has been specified through setSource(ConfigurationSource), it will be used. Otherwise, this method will fail.

Throws:: java.io.IOException - if an I/O error occurs.; ConfigurationException - if a configuration error occurs.; SourceConfigurationException - if no ConfigurationSource hasn been set.; ConfigurationFormatException - if a syntax error occurs in the configuration data.; ConfigurationStructureException - if the configuration data doesn't describe a valid configuration tree.; ReaderConfigurationException - if the ConfigurationReaderFactory isn't properly configured.
See Also:: write(), read(InputStream), read(ConfigurationReader), read(InputStream,ConfigurationReader)

write

public void write(java.io.OutputStream out,
                  ConfigurationWriter writer)
           throws ConfigurationException

Writes configuration to the specified output stream using the specified writer.

Parameters:: out - where to write the configuration to.; writer - writer that will be used to format the configuration.
Throws:: ConfigurationException - if any error occurs.; ConfigurationFormatException - if a syntax error occurs in the configuration data.; ConfigurationStructureException - if the configuration data doesn't describe a valid configuration tree.
See Also:: read(InputStream,ConfigurationReader), write(OutputStream), write(ConfigurationWriter), write()

write

public void write(java.io.OutputStream out)
           throws ConfigurationException

Writes configuration to the specified output stream.

If a writer was specified through setWriterFactory(ConfigurationWriterFactory), this will be used to format the configuration. Otherwise, an XmlConfigurationWriter will be used.

Parameters:: out - where to write the configuration to.
Throws:: ConfigurationException - if any error occurs.; ConfigurationFormatException - if a syntax error occurs in the configuration data.; ConfigurationStructureException - if the configuration data doesn't describe a valid configuration tree.; WriterConfigurationException - if the ConfigurationWriterFactory isn't properly configured.
See Also:: read(InputStream), write(OutputStream,ConfigurationWriter), write(ConfigurationWriter), write()

write

public void write(ConfigurationWriter writer)
           throws java.io.IOException,
                  ConfigurationException

Writes configuration using the specified writer.

If a configuration source was specified through setSource(ConfigurationSource), it will be used to open an output stream. Otherwise, this method will fail.

Parameters:: writer - writer that will be used to format the configuration.
Throws:: ConfigurationException - if any error occurs.; SourceConfigurationException - if no ConfigurationSource has been set.; ConfigurationFormatException - if a syntax error occurs in the configuration data.; ConfigurationStructureException - if the configuration data doesn't describe a valid configuration tree.; java.io.IOException - if any I/O error occurs.
See Also:: read(ConfigurationReader), write(OutputStream,ConfigurationWriter), write(OutputStream), write()

write

public void write()
           throws java.io.IOException,
                  ConfigurationException

Writes configuration.

If a writer was specified through setWriterFactory(ConfigurationWriterFactory), this will be used to format the configuration. Otherwise, an XmlConfigurationWriter will be used.

If a configuration source was specified through setSource(ConfigurationSource), it will be used to open an output stream. Otherwise, this method will fail.

Throws:: SourceConfigurationException - if a ConfigurationSource hasn't been set.; ConfigurationException - if any error occurs.; ConfigurationFormatException - if a syntax error occurs in the configuration data.; ConfigurationStructureException - if the configuration data doesn't describe a valid configuration tree.; WriterConfigurationException - if the ConfigurationWriterFactory isn't properly configured.; java.io.IOException - if any I/O error occurs.
See Also:: read(), write(OutputStream,ConfigurationWriter), write(OutputStream), write(ConfigurationWriter)

build

public void build(ConfigurationBuilder builder)
           throws ConfigurationException

Explores the whole configuration tree and invokes the specified builder's callback methods.

Parameters:: builder - object that will receive configuration building messages.
Throws:: ConfigurationException - if any error occurs while going through the configuration tree.

renameVariable

public void renameVariable(java.lang.String fromVar,
                           java.lang.String toVar)

Moves the value of fromVar to toVar.

At the end of this call, fromVar will have been deleted. Note that if fromVar doesn't exist, but toVar does, toVar will be deleted.

This method might trigger as many as two events:

One when fromVar is removed.
One when toVar is set.

The removal event will always be triggered first.

Parameters:: fromVar - fully qualified name of the variable to rename.; toVar - fully qualified name of the variable that will receive fromVar's value.

setVariable

public boolean setVariable(java.lang.String name,
                           java.lang.String value)

Sets the value of the specified variable.

This method will return false if it didn't modify name's value. Note that this doesn't mean the call failed, but that name's value was already equal to value.

If the value of the specified variable is actually modified, an event will be passed to all listeners.

Parameters:: name - fully qualified name of the variable to set.; value - new value for the variable.
Returns:: true if this call resulted in a modification of the variable's value, false otherwise.
See Also:: getVariable(String), getVariable(String,String)

setVariable

public boolean setVariable(java.lang.String name,
                           int value)

Sets the value of the specified variable.

This method will return false if it didn't modify name's value. This, however, is not a way of indicating that the call failed: false is only ever returned if the previous value is equal to the new value.

If the value of the specified variable is actually modified, an event will be passed to all listeners.

Parameters:: name - fully qualified name of the variable to set.; value - new value for the variable.
Returns:: true if this call resulted in a modification of the variable's value, false otherwise.
See Also:: getIntegerVariable(String), getVariable(String,int)

setVariable

public boolean setVariable(java.lang.String name,
                           java.util.List value,
                           java.lang.String separator)

Sets the value of the specified variable.

If the value of the specified variable is actually modified, an event will be passed to all listeners.

Parameters:: name - fully qualified name of the variable to set.; value - new value for the variable.; separator - string used to separate each element of the list.
Returns:: true if this call resulted in a modification of the variable's value, false otherwise.
See Also:: getListVariable(String,String), getVariable(String,List,String)

setVariable

public boolean setVariable(java.lang.String name,
                           float value)

Sets the value of the specified variable.

If the value of the specified variable is actually modified, an event will be passed to all listeners.

Parameters:: name - fully qualified name of the variable to set.; value - new value for the variable.
Returns:: true if this call resulted in a modification of the variable's value, false otherwise.
See Also:: getFloatVariable(String), getVariable(String,float)

setVariable

public boolean setVariable(java.lang.String name,
                           boolean value)

Sets the value of the specified variable.

If the value of the specified variable is actually modified, an event will be passed to all listeners.

Parameters:: name - fully qualified name of the variable to set.; value - new value for the variable.
Returns:: true if this call resulted in a modification of the variable's value, false otherwise.
See Also:: getBooleanVariable(String), getVariable(String,boolean)

setVariable

public boolean setVariable(java.lang.String name,
                           long value)

Sets the value of the specified variable.

If the value of the specified variable is actually modified, an event will be passed to all listeners.

Parameters:: name - fully qualified name of the variable to set.; value - new value for the variable.
Returns:: true if this call resulted in a modification of the variable's value, false otherwise.
See Also:: getLongVariable(String), getVariable(String,long)

setVariable

public boolean setVariable(java.lang.String name,
                           double value)

Sets the value of the specified variable.

If the value of the specified variable is actually modified, an event will be passed to all listeners.

Parameters:: name - fully qualified name of the variable to set.; value - new value for the variable.
Returns:: true if this call resulted in a modification of the variable's value, false otherwise.
See Also:: getDoubleVariable(String), getVariable(String,double)

getVariable

public java.lang.String getVariable(java.lang.String name)

Returns the value of the specified variable.

Parameters:: name - fully qualified name of the variable whose value should be retrieved.
Returns:: the variable's value if set, null otherwise.
See Also:: setVariable(String,String), getVariable(String,String)

getListVariable

public ValueList getListVariable(java.lang.String name,
                                 java.lang.String separator)

Returns the value of the specified variable as a ValueList.

Parameters:: name - fully qualified name of the variable whose value should be retrieved.; separator - character used to split the variable's value into a list.
Returns:: the variable's value if set, null otherwise.
See Also:: setVariable(String,List,String), getVariable(String,List,String)

getIntegerVariable

public int getIntegerVariable(java.lang.String name)

Returns the value of the specified variable as an integer.

Parameters:: name - fully qualified name of the variable whose value should be retrieved.
Returns:: the variable's value if set, 0 otherwise.
Throws:: java.lang.NumberFormatException - if the variable's value cannot be cast to an integer.
See Also:: setVariable(String,int), getVariable(String,int)

getLongVariable

public long getLongVariable(java.lang.String name)

Returns the value of the specified variable as a long.

Parameters:: name - fully qualified name of the variable whose value should be retrieved.
Returns:: the variable's value if set, 0 otherwise.
Throws:: java.lang.NumberFormatException - if the variable's value cannot be cast to a long.
See Also:: setVariable(String,long), getVariable(String,long)

getFloatVariable

public float getFloatVariable(java.lang.String name)

Returns the value of the specified variable as a float.

Parameters:: name - fully qualified name of the variable whose value should be retrieved.
Returns:: the variable's value if set, 0 otherwise.
Throws:: java.lang.NumberFormatException - if the variable's value cannot be cast to a float.
See Also:: setVariable(String,float), getVariable(String,float)

getDoubleVariable

public double getDoubleVariable(java.lang.String name)

Returns the value of the specified variable as a double.

Parameters:: name - fully qualified name of the variable whose value should be retrieved.
Returns:: the variable's value if set, 0 otherwise.
Throws:: java.lang.NumberFormatException - if the variable's value cannot be cast to a double.
See Also:: setVariable(String,double), getVariable(String,double)

getBooleanVariable

public boolean getBooleanVariable(java.lang.String name)

Returns the value of the specified variable as a boolean.

Parameters:: name - fully qualified name of the variable whose value should be retrieved.
Returns:: the variable's value if set, false otherwise.
See Also:: setVariable(String,boolean), getVariable(String,boolean)

isVariableSet

public boolean isVariableSet(java.lang.String name)

Checks whether the specified variable has been set.

Parameters:: name - fully qualified name of the variable to check for.
Returns:: true if the variable is set, false otherwise.