com.emarsys.ecommon.prefs.config
Class Configuration

java.lang.Object
  extended by com.emarsys.ecommon.prefs.config.Configuration
All Implemented Interfaces:
ConfigurationBackend

public class Configuration
extends java.lang.Object
implements ConfigurationBackend

A Configuration represents a generic storage for settings which hold the configuration of your system, module or some other software artifact.

Introduction

The whole Configuration API is intended to provide a lightweight and easy to (re)use configuration subsystem. Some of the core principles and concepts are:

When you should use Configuration

When you should not use Configuration

Architecture

A Configuration consists of a ConfigurationBackend, that is used to retrieve the actual ISettings and is associated with a ConfigurationDeclaration that defines its String name and Configuration.Type as well as possibly declared default values or fallback settings.

A Configuration might represent an aggregation or chain of ConfigurationBackends, see for instance FallbackConfigurationBackend or DefaultsConfigurationBackend, whilest being a ConfigurationBackend itself that is associated with a Configuration.Type as well as a name.
Furthermore a Configuration serves as an abstract factory for itself or ConfigurationBackends respectively that is driven by its declared Configuration.Type.
The Configuration's factory methods will create its backend by aggregating or chaining several ConfigurationBackends according to its corresponding ConfigurationDeclaration in order to support fallback settings, default values, etc.; see getInstance() as well as Configuration.Type.createConfigBackend() for details.

Author:
Michael "kULO" Kulovits

Nested Class Summary
static class Configuration.Type
           Defines different Configuration.Types of concrete Configuration instances.
 
Field Summary
protected  NamedConfigurationBackend backend
           
protected  ConfigurationDeclaration declaration
           
 
Constructor Summary
protected Configuration(ConfigurationBackend backend, ConfigurationDeclaration declaration)
           
 
Method Summary
 boolean equals(java.lang.Object that)
          Uses the Configuration's type and name but NOT its actual ISettings for comparison.
 ISetting get(java.lang.String name)
          Retrieves the ISetting with the passed name.
 ConfigurationDeclaration getDeclaration()
           
static Configuration getInstance(ConfigurationBackend config, ConfigurationDeclaration declaration)
           Primary factory method for Configuration instances.
static Configuration getInstanceDeclaredBy(ConfigurationBackend config, java.lang.Object declarationObj)
           A factory method for Configurations that uses the passed "declaration object" to get its ConfigurationDeclaration.
static Configuration getInstanceDeclaredBy(ConfigurationBackend config, java.lang.Object declarationObj, Configuration.Type type)
           A factory method for Configurations that uses the passed "declaration object" to get its ConfigurationDeclaration but overrides the declaration objects Configuration.Type with the passed one.
 java.lang.String getName()
           
 java.util.List<ISetting> getSettings()
           Retrieves all ISettings from this backend.
 Configuration.Type getType()
           
 int hashCode()
           
 void set(ISetting setting)
          Sets the passed setting which must not be null in this configuration backend, if a setting with the given name is already present it will be overridden.
 java.lang.String toString()
           
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

backend

protected final NamedConfigurationBackend backend

declaration

protected final ConfigurationDeclaration declaration
Constructor Detail

Configuration

protected Configuration(ConfigurationBackend backend,
                        ConfigurationDeclaration declaration)
Parameters:
backend -
declaration -
Method Detail

getInstance

public static Configuration getInstance(ConfigurationBackend config,
                                        ConfigurationDeclaration declaration)
                                 throws ConfigurationException

Primary factory method for Configuration instances.

Creates a new Configuration instance that uses a backend created by the Configuration.Type that's associated with the passed declaration.

Parameters:
config - - the primary ConfigurationBackend
declaration - - the ConfigurationDeclaration
Returns:
always a valid, new Configuration instance, never null
Throws:
ConfigurationException - - on any error
See Also:
Configuration(ConfigurationBackend, ConfigurationDeclaration)

getInstanceDeclaredBy

public static Configuration getInstanceDeclaredBy(ConfigurationBackend config,
                                                  java.lang.Object declarationObj)
                                           throws ConfigurationException

A factory method for Configurations that uses the passed "declaration object" to get its ConfigurationDeclaration.

This factory method will create Configuration instances that utilize the passed ConfigurationBackend to lookup ISettings and initializes itself according to the ClassConfigurationDeclaration that is held by the passed configuration declarating Object.
NOTE: the passed declaration object's type or supertype have to be annotated with DeclareConfiguration.

Parameters:
config - - the ConfigurationBackend
declarationObj - - the instance specifying a ClassConfigurationDeclaration having a DeclareConfiguration annotation
Returns:
always a valid, new Configuration instance, never null
Throws:
ConfigurationException - - on any error

getInstanceDeclaredBy

public static Configuration getInstanceDeclaredBy(ConfigurationBackend config,
                                                  java.lang.Object declarationObj,
                                                  Configuration.Type type)
                                           throws ConfigurationException

A factory method for Configurations that uses the passed "declaration object" to get its ConfigurationDeclaration but overrides the declaration objects Configuration.Type with the passed one.

This factory method will create Configuration instances that utilize the passed ConfigurationBackend to lookup ISettings and initializes itself according to the ClassConfigurationDeclaration that is held by the passed configuration declarating Object.
NOTE: the passed declaration object's type or supertype have to be annotated with DeclareConfiguration.

Parameters:
config - - the ConfigurationBackend
declarationObj - - the instance specifying a ClassConfigurationDeclaration having a DeclareConfiguration annotation
type - - the Configuration.Type to use instead of the one specified by the DeclareConfiguration annotation of declarationObj
Returns:
always a valid, new Configuration instance, never null
Throws:
ConfigurationException - - on any error

getDeclaration

public ConfigurationDeclaration getDeclaration()
Returns:
the declaration

getType

public Configuration.Type getType()
Returns:
the type

getName

public java.lang.String getName()
Returns:

get

public ISetting get(java.lang.String name)
             throws java.lang.IllegalArgumentException
Description copied from interface: ConfigurationBackend
Retrieves the ISetting with the passed name.

Specified by:
get in interface ConfigurationBackend
Returns:
the ISetting with the passed name or null if not present.
Throws:
java.lang.IllegalArgumentException - - if the passed name is null.
See Also:
com.emarsys.core.setting.backend.ConfigurationBackend#get(java.lang.String)

getSettings

public java.util.List<ISetting> getSettings()
Description copied from interface: ConfigurationBackend

Retrieves all ISettings from this backend.

What exactly "all" means in the context of the concrete ConfigurationBackend is up to the implementation. For instance the List may or may not contain default values or fallbacked ISettings or might even return a cached list.

The only requirement for this method is to be logically in synch with ConfigurationBackend.get(String) and ConfigurationBackend.set(ISetting). Thus if a Setting is inserted/updated/deleted and nothing is changed in the meantime the next call to ConfigurationBackend.getSettings() has to reflect the changes made.

Specified by:
getSettings in interface ConfigurationBackend
Returns:
always a valid List of ISettings, never null.
See Also:
com.emarsys.core.setting.backend.ConfigurationBackend#getSettings()

set

public void set(ISetting setting)
         throws java.lang.IllegalArgumentException
Description copied from interface: ConfigurationBackend
Sets the passed setting which must not be null in this configuration backend, if a setting with the given name is already present it will be overridden. The next call to ConfigurationBackend.get(String) with the passed setting's name will return the passed setting.

Specified by:
set in interface ConfigurationBackend
Throws:
java.lang.IllegalArgumentException - - if the passed setting, its name or value is null.
See Also:
com.emarsys.core.setting.backend.ConfigurationBackend#set(ISetting)

equals

public boolean equals(java.lang.Object that)
Uses the Configuration's type and name but NOT its actual ISettings for comparison. Thus note that equal Configuration's might not represent the same settings.

Overrides:
equals in class java.lang.Object
See Also:
Object.equals(java.lang.Object)

hashCode

public int hashCode()
Overrides:
hashCode in class java.lang.Object
See Also:
Object.hashCode()

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object
See Also:
Object.toString()


Copyright © 2010 emarsys AG. All Rights Reserved.