qflib 0.98.1

de.qfs.lib.config
Class Configuration

java.lang.Object
  |
  +--de.qfs.lib.config.Configuration

public class Configuration
extends java.lang.Object

The Configuration class provides the means for an application to save and restore some of its state, e.g. GUI relevant stuff like window positions, or options that can be customized interactively by the user.

Objects which implement the Configurable interface, can be registered with the Configuration. They will automatically be queried for their state, when the Configuration is saved and have their state restored, when the Configuration is restored.

The Configuration also takes care of restored state for objects that are not registered at the time of the restore. It will call the Configurable.setConfigurableState method on those objects, once they get registered and will even save their state back so it doesn't get lost. Thus e.g. a Frame can be constructed and configured at runtime only when needed and its state won't get lost during an invocation of the application in which the user never opens it.

It is possible to register more than one Configurable under the same name. This makes sence if you have multiple instances of something sharing the same kind of state. The state that will be saved with the Configuration is that of the most recently registered Configurable.

The Configuration follows the Singleton pattern, i.e. there should always be only one Configuration instance per application, which can be obtained via the static instance method. There is however a protected constructor to allow saving or restoring parts of the Configuration in different files through a derived class.

Changes in the state of registered Configurables can be tracked by registering a ConfigurationListener with addConfigurationListener. However it is up to the Configurables themselves to notify the Configuration of a state change.

The Configuration is saved in a human readable and editable format. For each Configurable a section is added that starts with the Configurable's name in brackets, e.g. [SomeConfigurableName], followed by an optional comment and the state of the Configurable in the standard property file format. Comments start with '#' and can be set for the whole file via setComment or for a Configurable via setComment. When the Configuration is restored and from a file then saved again, all comments and the order of the Configurables will be preserved, but the order of the properties inside the section of a Configurable is unpredictable.

Version:
$Revision: 1.7 $
Author:
Gregor Schmid

Field Summary
protected  java.util.Hashtable configurables
          A mapping from names to Configurables.
protected  java.util.Hashtable nameMap
          A mapping from Configurables to names.
protected  java.util.Vector names
          A vector holding all registered names in the sequence they were read or registered.
protected  java.util.Hashtable states
          The current state of all registered Configurables and of objects that have been restored but not registered, indexed by their name.
 
Constructor Summary
protected Configuration()
          The constructor is protected to prevent the creation of more than one Configuration object.
 
Method Summary
 void addConfigurationListener(ConfigurationListener listener)
          Add a ConfigurationListener to the Configuration.
 java.lang.String getComment()
          Get the comment read from the config file.
 java.lang.String getComment(java.lang.String name)
          Get the comment for one Configurable name.
 java.lang.String getRegistrationName(Configurable configurable)
          Get the last name a Configurable was registered under.
static Configuration instance()
          Get the single Configuration instance.
 void register(Configurable configurable)
          Register a Configurable.
 void registerAs(Configurable configurable, java.lang.String name)
          Register a Configurable under a (possibly) different name.
 void removeConfigurationListener(ConfigurationListener listener)
          Remove a ConfigurationListener from the Configuration.
 void restore(java.io.InputStream in)
          Restore the Configuration from an InputStream.
 void save(java.io.OutputStream out)
          Save the complete Configuration to an OutputStream.
 void setComment(java.lang.String comment)
          Set the comment for the header of the config file.
 void setComment(java.lang.String name, java.lang.String comment)
          Set a comment for one Configurable name.
 void stateChanged(Configurable configurable)
          Notify the Configuration of a state change in one of its registered Configurables.
 void unregister(Configurable configurable, boolean keepValues)
          Remove a Configurable from the Configuration.
 void unregisterAll(java.lang.String name, boolean keepValues)
          Remove all Configurables of the same name from the Configuration.
 void unregisterAs(Configurable configurable, java.lang.String name, boolean keepValues)
          Remove a Configurable under a (possibly) different name from the Configuration.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

configurables

protected java.util.Hashtable configurables
A mapping from names to Configurables.

nameMap

protected java.util.Hashtable nameMap
A mapping from Configurables to names.

states

protected java.util.Hashtable states
The current state of all registered Configurables and of objects that have been restored but not registered, indexed by their name.

names

protected java.util.Vector names
A vector holding all registered names in the sequence they were read or registered.
Constructor Detail

Configuration

protected Configuration()
The constructor is protected to prevent the creation of more than one Configuration object.
See Also:
instance()
Method Detail

instance

public static Configuration instance()
Get the single Configuration instance.
Returns:
The instance.

register

public void register(Configurable configurable)
Register a Configurable.

If the state of the Configurable has already been restored, also set its state.

Parameters:
configurable - The Configurable.

registerAs

public void registerAs(Configurable configurable,
                       java.lang.String name)
Register a Configurable under a (possibly) different name. If the state of the Configurable has already been restored, also set its state.
Parameters:
configurable - The Configurable.
name - The name to register under.

unregister

public void unregister(Configurable configurable,
                       boolean keepValues)
Remove a Configurable from the Configuration.
Parameters:
configurable - The Configurable.
keepValues - If true, keep the current state of the Configurable, otherwise forget it.

unregisterAs

public void unregisterAs(Configurable configurable,
                         java.lang.String name,
                         boolean keepValues)
Remove a Configurable under a (possibly) different name from the Configuration.
Parameters:
configurable - The Configurable.
name - The name to use.
keepValues - If true, keep the current state of the Configurable, otherwise forget it.

unregisterAll

public void unregisterAll(java.lang.String name,
                          boolean keepValues)
Remove all Configurables of the same name from the Configuration.
Parameters:
name - The name of the Configurables.
keepValues - If true, keep the current state of the most recently registered Configurable, otherwise forget it.

getRegistrationName

public java.lang.String getRegistrationName(Configurable configurable)
Get the last name a Configurable was registered under. This may be different from the Configurable's name.
Parameters:
configurable - The Configurable whose name to get.
Returns:
The name the Configurable is registered under or null, if it is not registered.

save

public void save(java.io.OutputStream out)
Save the complete Configuration to an OutputStream.
Parameters:
out - The stream to save to.

restore

public void restore(java.io.InputStream in)
             throws java.io.IOException
Restore the Configuration from an InputStream.
Parameters:
in - The stream to restore from.
Throws:
java.io.IOException - If the data from the stream is not in the format generated by save.

setComment

public void setComment(java.lang.String comment)
Set the comment for the header of the config file.
Parameters:
comment - The comment to set.

setComment

public void setComment(java.lang.String name,
                       java.lang.String comment)
Set a comment for one Configurable name.
Parameters:
name - The Configurable name.
comment - The comment to set.

getComment

public java.lang.String getComment()
Get the comment read from the config file.

getComment

public java.lang.String getComment(java.lang.String name)
Get the comment for one Configurable name.
Parameters:
name - The Configurable name.
Returns:
The comment or null.

addConfigurationListener

public void addConfigurationListener(ConfigurationListener listener)
Add a ConfigurationListener to the Configuration.
Parameters:
listener - The ConfigurationListener to add.

removeConfigurationListener

public void removeConfigurationListener(ConfigurationListener listener)
Remove a ConfigurationListener from the Configuration.
Parameters:
listener - The ConfigurationListener to remove.

stateChanged

public void stateChanged(Configurable configurable)
Notify the Configuration of a state change in one of its registered Configurables. It is up to the Configurable whether it notifies the Configuration of changes or not.

If any ConfigurationListeners are registered, the Configuration will compare the Configurables new state to its old state and notify the listeners if anything has changed.

Parameters:
configurable - The Configurable whose state changed.

qflib 0.98.1