org.mycore.common
Class MCRConfiguration

java.lang.Object
  org.mycore.common.MCRConfiguration

public class MCRConfiguration
extends Object

Provides methods to manage and read all configuration properties from the MyCoRe configuration files. The class is implemented using the singleton pattern. Using this class is very easy, here is an example:

 // Get a configuration property as a String: 
 String driver = MCRConfiguration.instance().getString( "MCR.JDBC.Driver" ); 
 // Get a configuration property as an int, use 500 as default if not set: 
 int max = MCRConfiguration.instance().getInt( "MCR.Cache.Size", 500 );
 

As you see, the class provides methods to get configuration properties as different data types and allows you to specify defaults. All MyCoRe configuration properties should start with "MCR." When instance() is called the first time, the file mycore.properties is read. It can be located somewhere in the CLASSPATH, even in a jar or zip file. The properties file may have a property called MCR.Configuration.Include that contains a comma-separated list of other configuration files to read subsequently. The class also reads any Java system properties that start with "MCR." and that are set when the application starts. System properties will override properties read from the configuration files. Furthermore, the name of the main configuration file can be altered by specifying the system property MCR.Configuration.File . Here is an example:

 java -DMCR.Configuration.File=some_other.properties -DMCR.foo=bar MyCoReSample
 

Property values may include the values of other properties, recursively, by referencing the other property. Example:

 MCR.Foo1=FooValue
 MCR.Foo2=Some %MCR.Foo1% more information
 

The class also provides methods for listing or saving all properties to an OutputStream and for reloading all configuration properties at runtime. This allows servlets that run a long time to re-read the configuration files when client code tells them to do so, for example. Using the set methods allows client code to set new configuration properties or overwrite existing ones with new values. Finally, applications could also subclass MCRConfiguration to change or add behavior and use an instance of the subclass instead of this class. This is transparent for client code, they would still use MCRConfiguration.instance() to get the subclass instance. To use a subclass instead of MCRConfiguration itself, specify the system property MCR.Configuration.Class, e. g.

 java -DMCR.Configuration.Class=MCRConfigurationSubclass MyCoReSample
 

Version:

$Revision: 15619 $ $Date: 2009-07-25 08:28:03 +0200 (Sat, 25 Jul 2009) $

Author:

Frank Lützenkirchen

See Also:

loadFromFile(java.lang.String), reload(boolean), list(PrintStream), store(java.io.OutputStream, java.lang.String)

Field Summary

protected Properties	depr List of deprecated properties with their new name
(package private) static File	lastModifiedFile
protected Properties	properties The properties instance that stores the values that have been read from every configuration file
protected static MCRConfiguration	singleton The single instance of this class that will be used at runtime

Constructor Summary

protected

MCRConfiguration() Protected constructor to create the singleton instance

Method Summary

void	configureLogging() Configures Log4J based on the log4j properties
protected static void	createSingleton() Instantiates the singleton by calling the protected constructor.
boolean	getBoolean(String name) Returns the configuration property with the specified name as a boolean value.
boolean	getBoolean(String name, boolean defaultValue) Returns the configuration property with the specified name as a boolean value, or returns a given default value if the property is not set.
double	getDouble(String name) Returns the configuration property with the specified name as a double value.
double	getDouble(String name, double defaultValue) Returns the configuration property with the specified name as a double value, or returns a given default value if the property is not set.
float	getFloat(String name) Returns the configuration property with the specified name as a float value.
float	getFloat(String name, float defaultValue) Returns the configuration property with the specified name as a float value, or returns a given default value if the property is not set.
Object	getInstanceOf(String name) Returns a new instance of the class specified in the configuration property with the given name.
Object	getInstanceOf(String name, String defaultname) Returns a new instance of the class specified in the configuration property with the given name.
int	getInt(String name) Returns the configuration property with the specified name as an int value.
int	getInt(String name, int defaultValue) Returns the configuration property with the specified name as an int value, or returns a given default value if the property is not set.
long	getLong(String name) Returns the configuration property with the specified name as a long value.
long	getLong(String name, long defaultValue) Returns the configuration property with the specified name as a long value, or returns a given default value if the property is not set.
Properties	getProperties() Returns all the properties
Properties	getProperties(String startsWith) Returns all the properties beginning with the specified string
Object	getSingleInstanceOf(String name) Returns a instance of the class specified in the configuration property with the given name.
Object	getSingleInstanceOf(String name, String defaultname) Returns a instance of the class specified in the configuration property with the given name.
String	getString(String name) Returns the configuration property with the specified name as a String.
String	getString(String name, String defaultValue) Returns the configuration property with the specified name as a String, or returns a given default value if the property is not set.
long	getSystemLastModified() returns the last point in time when the MyCoRe system was last modified.
static MCRConfiguration	instance() Returns the single instance of this class that can be used to read and manage the configuration properties.
void	list(PrintStream out) Lists all configuration properties currently set to a PrintStream.
void	list(PrintWriter out) Lists all configuration properties currently set to a PrintWriter.
void	reload(boolean clear) Reloads all properties from the configuration files.
void	set(String name, boolean value) Sets the configuration property with the specified name to a new boolean value.
void	set(String name, double value) Sets the configuration property with the specified name to a new double value.
void	set(String name, float value) Sets the configuration property with the specified name to a new float value.
void	set(String name, int value) Sets the configuration property with the specified name to a new int value.
void	set(String name, long value) Sets the configuration property with the specified name to a new long value.
void	set(String name, String value) Sets the configuration property with the specified name to a new String value.
void	store(OutputStream out, String header) Stores all configuration properties currently set to an OutputStream.
void	systemModified() signalize that the system state has changed.
String	toString() Returns a String containing the configuration properties currently set.

Methods inherited from class java.lang.Object

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

Field Detail

singleton

protected static MCRConfiguration singleton

The single instance of this class that will be used at runtime

lastModifiedFile

static File lastModifiedFile

properties

protected Properties properties

The properties instance that stores the values that have been read from every configuration file

depr

protected Properties depr

List of deprecated properties with their new name

Constructor Detail

MCRConfiguration

protected MCRConfiguration()

Protected constructor to create the singleton instance

Method Detail

instance

public static MCRConfiguration instance()

Returns the single instance of this class that can be used to read and manage the configuration properties.

Returns:

the single instance of MCRConfiguration to be used

createSingleton

protected static void createSingleton()

Instantiates the singleton by calling the protected constructor. If the system property MCR.Configuration.Class is set when the system starts, the class specified in that property will be instantiated instead. This allows for subclassing MCRConfiguration to change behaviour and use the subclass instead of MCRConfiguration .

getSystemLastModified

public final long getSystemLastModified()

returns the last point in time when the MyCoRe system was last modified. This method can help you to validate caches not under your controll, e.g. client caches.

See Also:

System.currentTimeMillis()

systemModified

public final void systemModified()

signalize that the system state has changed. Call this method when ever you changed the persistency layer.

reload

public void reload(boolean clear)

Reloads all properties from the configuration files. If the system property MCR.Configuration.File is set, the file specified in this property will be used as main configuration file, otherwise the default file mycore.properties will be read. If the parameter clear is true, all properties currently set will be deleted first, otherwise the properties read from the configuration files will be added to the properties currently set and they will overwrite existing properties with the same name.

Parameters:

clear - if true, properties currently set will be deleted first

Throws:

MCRConfigurationException - if the config files can not be loaded

getProperties

public Properties getProperties()

Returns all the properties

Returns:

the list of properties

getProperties

public Properties getProperties(String startsWith)

Returns all the properties beginning with the specified string

Parameters:

startsWith - the string all the returned properties start with

Returns:

the list of properties

configureLogging

public void configureLogging()

Configures Log4J based on the log4j properties

getInstanceOf

public Object getInstanceOf(String name,
                            String defaultname)
                     throws MCRConfigurationException

Returns a new instance of the class specified in the configuration property with the given name.

Parameters:

name - the non-null and non-empty name of the configuration property

Returns:

the value of the configuration property as a String, or null

Throws:

MCRConfigurationException - if the property is not set or the class can not be loaded or instantiated

getInstanceOf

public Object getInstanceOf(String name)
                     throws MCRConfigurationException

Returns a new instance of the class specified in the configuration property with the given name.

Parameters:

name - the non-null and non-empty name of the configuration property

Returns:

the value of the configuration property as a String, or null

Throws:

MCRConfigurationException - if the property is not set or the class can not be loaded or instantiated

getSingleInstanceOf

public Object getSingleInstanceOf(String name,
                                  String defaultname)
                           throws MCRConfigurationException

Returns a instance of the class specified in the configuration property with the given name. If the class was prevously instantiated by this method this instance is returned.

Parameters:

name - the non-null and non-empty name of the configuration property

Returns:

the instance of the class named by the value of the configuration propertyl

Throws:

MCRConfigurationException - if the property is not set or the class can not be loaded or instantiated

getSingleInstanceOf

public Object getSingleInstanceOf(String name)

Returns a instance of the class specified in the configuration property with the given name. If the class was prevously instantiated by this method this instance is returned.

Parameters:

name - non-null and non-empty name of the configuration property

Returns:

the instance of the class named by the value of the configuration propertyl

Throws:

MCRConfigurationException - if the property is not set or the class can not be loaded or instantiated

getString

public String getString(String name)

Returns the configuration property with the specified name as a String.

Parameters:

name - the non-null and non-empty name of the configuration property

Returns:

the value of the configuration property as a String

Throws:

MCRConfigurationException - if the property with this name is not set

getString

public String getString(String name,
                        String defaultValue)

Returns the configuration property with the specified name as a String, or returns a given default value if the property is not set.

Parameters:

name - the non-null and non-empty name of the configuration property

defaultValue - the value to return if the configuration property is not set

Returns:

the value of the configuration property as a String

getInt

public int getInt(String name)
           throws NumberFormatException

Returns the configuration property with the specified name as an int value.

Parameters:

name - the non-null and non-empty name of the configuration property

Returns:

the value of the configuration property as an int value

Throws:

NumberFormatException - if the configuration property is not an int value

MCRConfigurationException - if the property with this name is not set

getInt

public int getInt(String name,
                  int defaultValue)
           throws NumberFormatException

Returns the configuration property with the specified name as an int value, or returns a given default value if the property is not set.

Parameters:

name - the non-null and non-empty name of the configuration property /** Returns the configuration property with the specified name as an int value, or returns a given default value if the property is not set.

defaultValue - the value to return if the configuration property is not set

Returns:

the value of the specified property as an int value

Throws:

NumberFormatException - if the configuration property is set but is not an int value

getLong

public long getLong(String name)
             throws NumberFormatException

Returns the configuration property with the specified name as a long value.

Parameters:

name - the non-null and non-empty name of the configuration property

Returns:

the value of the configuration property as a long value

Throws:

NumberFormatException - if the configuration property is not a long value

MCRConfigurationException - if the property with this name is not set

getLong

public long getLong(String name,
                    long defaultValue)
             throws NumberFormatException

Returns the configuration property with the specified name as a long value, or returns a given default value if the property is not set.

Parameters:

name - the non-null and non-empty name of the configuration property

defaultValue - the value to return if the configuration property is not set

Returns:

the value of the specified property as a long value

Throws:

NumberFormatException - if the configuration property is set but is not a long value

getFloat

public float getFloat(String name)
               throws NumberFormatException

Returns the configuration property with the specified name as a float value.

Parameters:

name - the non-null and non-empty name of the configuration property

Returns:

the value of the configuration property as a float value

Throws:

NumberFormatException - if the configuration property is not a float value

MCRConfigurationException - if the property with this name is not set

getFloat

public float getFloat(String name,
                      float defaultValue)
               throws NumberFormatException

Returns the configuration property with the specified name as a float value, or returns a given default value if the property is not set.

Parameters:

name - the non-null and non-empty name of the configuration property

defaultValue - the value to return if the configuration property is not set

Returns:

the value of the specified property as a float value

Throws:

NumberFormatException - if the configuration property is set but is not a float value

getDouble

public double getDouble(String name)
                 throws NumberFormatException

Returns the configuration property with the specified name as a double value.

Parameters:

name - the non-null and non-empty name of the configuration property

Returns:

the value of the configuration property as a double value

Throws:

NumberFormatException - if the configuration property is not a double value

MCRConfigurationException - if the property with this name is not set

getDouble

public double getDouble(String name,
                        double defaultValue)
                 throws NumberFormatException

Returns the configuration property with the specified name as a double value, or returns a given default value if the property is not set.

Parameters:

name - the non-null and non-empty name of the configuration property

defaultValue - the value to return if the configuration property is not set

Returns:

the value of the specified property as a double value

Throws:

NumberFormatException - if the configuration property is set but is not a double value

getBoolean

public boolean getBoolean(String name)

Returns the configuration property with the specified name as a boolean value.

Parameters:

name - the non-null and non-empty name of the configuration property

Returns:

true, if and only if the specified property has the value true

Throws:

MCRConfigurationException - if the property with this name is not set

getBoolean

public boolean getBoolean(String name,
                          boolean defaultValue)

Returns the configuration property with the specified name as a boolean value, or returns a given default value if the property is not set. If the property is set and its value is not true , then false is returned.

Parameters:

name - the non-null and non-empty name of the configuration property

defaultValue - the value to return if the configuration property is not set

Returns:

the value of the specified property as a boolean value

set

public void set(String name,
                String value)

Sets the configuration property with the specified name to a new String value. If the parameter value is null, the property will be deleted.

Parameters:

name - the non-null and non-empty name of the configuration property

value - the new value of the configuration property, possibly null

set

public void set(String name,
                int value)

Sets the configuration property with the specified name to a new int value.

Parameters:

name - the non-null and non-empty name of the configuration property

value - the new value of the configuration property

set

public void set(String name,
                long value)

Sets the configuration property with the specified name to a new long value.

Parameters:

name - the non-null and non-empty name of the configuration property

value - the new value of the configuration property

set

public void set(String name,
                float value)

Sets the configuration property with the specified name to a new float value.

Parameters:

name - the non-null and non-empty name of the configuration property

value - the new value of the configuration property

set

public void set(String name,
                double value)

Sets the configuration property with the specified name to a new double value.

Parameters:

name - the non-null and non-empty name of the configuration property

value - the new value of the configuration property

set

public void set(String name,
                boolean value)

Sets the configuration property with the specified name to a new boolean value.

Parameters:

name - the non-null and non-empty name of the configuration property

value - the new value of the configuration property

list

public void list(PrintStream out)

Lists all configuration properties currently set to a PrintStream. Useful for debugging, e. g. by calling

MCRConfiguration.instance().list( System.out );

Parameters:

out - the PrintStream to list the configuration properties on

See Also:

Properties.list( PrintStream )

list

public void list(PrintWriter out)

Lists all configuration properties currently set to a PrintWriter. Useful for debugging.

Parameters:

out - the PrintWriter to list the configuration properties on

See Also:

Properties.list( PrintWriter )

store

public void store(OutputStream out,
                  String header)
           throws IOException

Stores all configuration properties currently set to an OutputStream.

Parameters:

out - the OutputStream to write the configuration properties to

header - the header to prepend before writing the list of properties

Throws:

IOException - if writing to the OutputStream throws an IOException

See Also:

Properties.store(java.io.OutputStream, java.lang.String)

toString

public String toString()

Returns a String containing the configuration properties currently set. Useful for debugging, e. g. by calling

System.out.println( MCRConfiguration.instance() );

Overrides:

toString in class Object

Returns:

a String containing the configuration properties currently set