org.openmdx.base.application.configuration
Class AbstractConfiguration

java.lang.Object
  org.openmdx.base.application.configuration.AbstractConfiguration

All Implemented Interfaces:

Configuration

public abstract class AbstractConfiguration
extends Object
implements Configuration

A configuration holds multiple configuration entries, is versioned and has a name. A configuration entry is a name-value pair with with an additional annotation field. The value field is a list of simple objects. The annotation field holds additional describing information on a configuration entry. This class is not threadsafe. Thread safety must be guaranteed by the callers.

Constructor Summary

AbstractConfiguration(String name)
Creates a new configuration object based on version 0.0

AbstractConfiguration(String name, int majorVersion, int minorVersion)
Creates a new configuration object.

Method Summary

void	addAll(AbstractConfiguration configuration, boolean preserve) Add all configuration entries from a configuration.
protected void	addEntryDescription(ConfigurationEntryDescription[] entryDescriptions) Adds configuration entry descriptions to the existing entry descriptions
void	addValue(String name, Object value, int index) Adds a new value at a specified position to a multi-valued configuration entry.
void	applyDefaults() Apply the defaults from the configuration entry descriptions.
boolean	entryExists(String name) Returns true if the entry exists and has at least one value.
Map	getEntryDescriptions() Returns the entry descriptions as an unmodifiable Map of ConfigurationEntryDescription objects.
Set	getEntryNames() Returns the configuration entry names of this configuration
int	getMajorVersion() Returns the configuration's major version.
int	getMinorVersion() Returns the configuration's minor version.
String	getName() Returns the configuration name.
Object	getValue(String name) Returns the value of a configuration entry.
List	getValues(String name) Returns the values of a configuration entry.
void	removeAllEntries() Removes all configuration entries.
void	removeEntry(String name) Remove a configuration entry.
void	setValue(String name, Object value) Sets a new single-valued configuration entry or multi-valued value in a configuration entry.
void	setValues(String name, Object[] values) Adds a new multi-valued configuration entry.
void	setVersion(int majorVersion, int minorVersion) Sets a new version.
String	toString() Returns a multiline, formatted string representation of the configuration.
abstract Report	validate() Validates the configuration.
Report	verify() Verifies the configuration.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

AbstractConfiguration

public AbstractConfiguration(String name,
                             int majorVersion,
                             int minorVersion)

Creates a new configuration object.

Parameters:

name - The name of this configuration

majorVersion - The major version of the configuration [0,1,2,..]

minorVersion - The minor version of the configuration [0,1,2,..]

AbstractConfiguration

public AbstractConfiguration(String name)

Creates a new configuration object based on version 0.0

Parameters:

name - The name of this configuration

Method Detail

getName

public final String getName()

Returns the configuration name.

Returns:

A configuration name string

getMajorVersion

public final int getMajorVersion()

Returns the configuration's major version.

Returns:

A configuration major version

getMinorVersion

public final int getMinorVersion()

Returns the configuration's minor version.

Returns:

A configuration minor version

setVersion

public final void setVersion(int majorVersion,
                             int minorVersion)

Sets a new version. The version information may be changed if the validation process upgrades the configuration to a new version.

Parameters:

majorVersion - The major version of the configuration [0,1,2,..]

minorVersion - The minor version of the configuration [0,1,2,..]

applyDefaults

public void applyDefaults()

Apply the defaults from the configuration entry descriptions. Each entry from the configuration entry descriptions (name and defaultValues) is added to this configuration if the entry does not yet exist. Defaults are not applied to entries that exists but do not have any values.

Note: Applying defaults is not undoable.

addValue

public void addValue(String name,
                     Object value,
                     int index)
              throws IndexOutOfBoundsException

Adds a new value at a specified position to a multi-valued configuration entry. Creates the entry if it does not exist. The specified multi-valued value is added to the entry or replaced if it already exists. If only one value is added to an entry at position 0, the entry is single-valued.

Parameters:

name - A string specifying the name of the configuration entry

value - An object representing the value of the configuration entry. May be null.

index - The index for value the multi-valued entry. Must not be negative. Use 0 for a single-valued entry.

Throws:

IndexOutOfBoundsException - if the specified value index is negative.

addAll

public void addAll(AbstractConfiguration configuration,
                   boolean preserve)

Add all configuration entries from a configuration. Add the entries to this configuration without affecting the configuration version and the configuration entry descriptions.

Parameters:

configuration - The configuration to be added

preserve - Preserve existing entries from beeing overwritten

setValue

public void setValue(String name,
                     Object value)
              throws IndexOutOfBoundsException,
                     IllegalArgumentException

Sets a new single-valued configuration entry or multi-valued value in a configuration entry. If the name ends with an array specifier (e.g. "x.y.z[n]") the referenced configuration entry will be considered as multi-valued and the value is stored at the specified position. If the entry does not exits it is created. The specified multi-valued value is added or replaced if it already exists. If the name does not end with an array specifier (e.g. "x.y.z[n]") the referenced configuration entry will be considered as single-valued.

Parameters:

name - A string specifying the name of the configuration entry

value - An object representing the value of the configuration entry. May be null.

Throws:

IndexOutOfBoundsException - if the specified array index is negative.

IllegalArgumentException - if the specified array index suffix has an invalid format.

setValues

public void setValues(String name,
                      Object[] values)
               throws IllegalArgumentException

Adds a new multi-valued configuration entry.

Parameters:

name - A string specifying the name of the configuration entry. Must not have an have an array specifier

values - An array with 0, 1 or more value objects. All objects must be of identical type. The type must one of the supported value types. May be a null if there are no values at all.

Throws:

IllegalArgumentException - if the specified configuration entry name contains an array specifier.

getValues

public List getValues(String name)

Returns the values of a configuration entry. Works for single-valued and and multi-valued entries.

Parameters:

name - A string specifying the name of the configuration entry

Returns:

A configuration entry value. Returns null if the entry does not exist.

getValue

public Object getValue(String name)
                throws InvalidCardinalityException

Returns the value of a configuration entry. The entry must be single-valued.

Parameters:

name - A string specifying the name of the configuration entry

Returns:

A configuration entry value. Maybe a null object if no value is found.

Throws:

InvalidCardinalityException - if the referenced configuration is multi-valued.

entryExists

public boolean entryExists(String name)

Returns true if the entry exists and has at least one value.

Returns:

true if the entry exists

getEntryNames

public Set getEntryNames()

Returns the configuration entry names of this configuration

Returns:

Returns a Set the configuration entry names of this configuration

removeEntry

public void removeEntry(String name)

Remove a configuration entry.

Parameters:

name - A string specifying the name of the configuration entry

removeAllEntries

public void removeAllEntries()

Removes all configuration entries.

getEntryDescriptions

public Map getEntryDescriptions()

Returns the entry descriptions as an unmodifiable Map of ConfigurationEntryDescription objects. The entry description name builds the map's key. Returns always a Map (that may have no entries).

Returns:

Map

validate

public abstract Report validate()

Validates the configuration. A concrete configuration validates the configuration entries. Validation goes beyond simple verification:

• Detects missing entries and adds its defaults
• Rejects unsupported entries
• Checks the version and possibly upgrades the configuration to the most current version

To accomplish this the validator needs more information than is required for just a simple verification.

Specified by:

validate in interface Configuration

Returns:

A validation report

See Also:

Configuration.verify()

verify

public final Report verify()

Verifies the configuration. All configuration entries are verified with the configuration entry descriptions. A verification requires that the configuration entry descriptions have been set.

The verification process verifies that:

• each entry has an entry description
• multi-valued entries do not have value holes
• the value cardinality is valid
• the value types are valid
• each entry from entry description list is present

Specified by:

verify in interface Configuration

Returns:

A validation report

toString

public String toString()

Returns a multiline, formatted string representation of the configuration.

Produces a multiline string following the sample:

       CfgName: Test                  <-- config name
       Version: 1.0                   <-- version (major,minor)
       port=9100                      <-- single-valued
       filter[0]=Filter01             <-- multi-valued (3 values)
       filter[1]=Filter02                   :
       filter[2]=Filter03                   :
 

Overrides:

toString in class Object

Returns:

A formatted string

addEntryDescription

protected void addEntryDescription(ConfigurationEntryDescription[] entryDescriptions)
                            throws IllegalArgumentException

Adds configuration entry descriptions to the existing entry descriptions

Parameters:

entryDescriptions - The entry descriptions

Throws:

IllegalArgumentException - if one of the specified entry descriptions already exists.