nl.chess.it.util.config
Class Config

java.lang.Object
  nl.chess.it.util.config.Config

Direct Known Subclasses:

CustomValidationConfig, SimpleConfig, VersionInformation

public abstract class Config

extends java.lang.Object

Configuration class. It's most important feature is an extensive self-validation call ( validateConfiguration()) that not only makes sure that required properties exists, but also that they are of the correct type and don't cause exceptions.

Partly based on the old Config class by Rolf Heller.

Author:

Guus Bosman (Chess-iT)

Constructor Summary

protected	Config(java.util.Properties properties) Constructs a Config based on an existing Properties.
protected	Config(java.lang.String resourceName) Constructs a Config based on a resource.

Method Summary

protected boolean	getBoolean(java.lang.String key) Gets the value for the given key.
protected java.util.Date	getDate(java.lang.String key)
protected long	getDurationInMs(java.lang.String key) Returns a duration.
protected java.io.File	getExistingReadableFile(java.lang.String key)
protected int	getInt(java.lang.String key)
protected java.lang.String	getMessageFormatPattern(java.lang.String key, java.lang.Object[] testArguments) Checks if the value stored under the given key is a pattern that can be used to construct a MessageFormat.
protected long	getSizeInBytes(java.lang.String key)
protected java.lang.String	getString(java.lang.String key) Gets the String value for the given key.
protected java.lang.String	getString(java.lang.String key, java.lang.String expectedType) Gets the value String for the given key.
protected java.lang.String[]	getStringArrayFromCommaString(java.lang.String key) Gets the value for the given key.
protected java.lang.String[]	getStringArrayFromCommaString(java.lang.String key, java.lang.String itemsDescription) Gets the value for the given key.
protected java.net.URL	getURL(java.lang.String key) Gets the value for the given key.
protected java.lang.String	getValue(java.lang.String key) This method gives access to the underlying Properties this class is wrapped around.
protected java.io.File	getWritableFile(java.lang.String key)
protected boolean	hasValue(java.lang.String key) Indicates whether or not a value is given for this key.
protected void	testMessageFormat(java.lang.String key, java.lang.String pattern, java.lang.Object[] testArguments) Verifies that the given pattern can be used to construct a MessageFormat.
ConfigValidationResult	validateConfiguration() Validates the configuration properties.

Methods inherited from class java.lang.Object

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

Constructor Detail

Config

protected Config(java.util.Properties properties)

Constructs a Config based on an existing Properties. This allows for a custom location of the properties. Also, it makes it possible to change the values of the properties used in this class at runtime. The Properties given is used directly (no defensive copy is made). Do whatever you like, but changing values at run-time this way has not been tested, and may lead to interesting problems.

Parameters:

properties - Cannot be null.

Throws:

java.lang.NullPointerException - If properties is null.

Config

protected Config(java.lang.String resourceName)
          throws ConfigurationException

Constructs a Config based on a resource. This resource will be lookup using this class' classloader, and then be read using an URL.

Parameters:

resourceName - Name of the resource to look for, as used in ClassLoader.getResource(java.lang.String). Cannot be null.

Throws:

java.lang.NullPointerException - If resourceName is null.

ConfigurationException

Method Detail

validateConfiguration

public final ConfigValidationResult validateConfiguration()

Validates the configuration properties. That means that all getters of this class are tested once; any exceptions thrown when calling a getter are reported.

Returns:

ConfigValidationResult the result of the validation. Never null.

getString

protected final java.lang.String getString(java.lang.String key)

Gets the String value for the given key. Note: this method is not the one that gives access to the underlying Properties, see getValue(String)for that.

Parameters:

key - Key to search on.

Returns:

String value. Never null, always trimmed().

Throws:

MissingPropertyException - if the key does not result in a value.

getString

protected final java.lang.String getString(java.lang.String key,
                                           java.lang.String expectedType)

Gets the value String for the given key. Throws an exception that describes the type of the expected value, which is nice to let the user know what kind of value should be filled in.

Parameters:

key - Key to search on.

expectedType - Description of the expected type of the value of the key we're looking for. Used in error messages.

Returns:

String value. Never null, always trimmed().

Throws:

MissingPropertyException - if the key does not result in a value.

getValue

protected java.lang.String getValue(java.lang.String key)

This method gives access to the underlying Properties this class is wrapped around. You could overwrite this to do special tricks for every value that is read from the property-file (Properties object, really).

Returns:

Value for the given key, or null if such a value cannot be found.

getInt

protected final int getInt(java.lang.String key)

getSizeInBytes

protected final long getSizeInBytes(java.lang.String key)

getDurationInMs

protected final long getDurationInMs(java.lang.String key)

Returns a duration.

Parameters:

key - Key to search on.

Returns:

A duration (long) in milliseconds. Never a negative number.

getMessageFormatPattern

protected final java.lang.String getMessageFormatPattern(java.lang.String key,
                                                         java.lang.Object[] testArguments)

Checks if the value stored under the given key is a pattern that can be used to construct a MessageFormat. See testMessageFormat(String, String, Object[])for more information.

Parameters:

key - String Key that will be used to retrieve the messageformat pattern. Cannot be null.

testArguments - Arguments to test the pattern with. Cannot be null.

Returns:

String MessageFormat pattern

testMessageFormat

protected final void testMessageFormat(java.lang.String key,
                                       java.lang.String pattern,
                                       java.lang.Object[] testArguments)

Verifies that the given pattern can be used to construct a MessageFormat. The testArguments array should contains values that represent reasonable values that will be used for this messageFormat.

Example: In your properties file you have the following messageformat pattern: files.description=There {0,choice,0#are no files|1#is one file|1 <are {0,number,integer} files} You could use the following calls in your getXxx() method to testMessageFormat to verify the messageformat deals with a variety of numbers correctly:

 
 public String getFilesDescription() {
     String key = "files.description";
     String value = getString(key, "MessageFormat string");
 
     testMessageFormat(key, value, new Object[] {new Integer(0)}); // tests the {0, choice, 0#} part
     testMessageFormat(key, value, new Object[] {new Integer(1)}); // tests the {0, choice ... |1#} part
     testMessageFormat(key, value, new Object[] {new Integer(10)});// tests the {0, choice ... <1} part
     return value;
 }
 
 

The above code would for example make sure the following entry in a property-file is not accepted: files.description=There {0,choice,0#are no files|1#is one file|1 <are {0,invaliddatatype} files}

Parameters:

key - Key that was used to retrieve the messageformat pattern.

pattern - The messageformat pattern to test.

testArguments - Arguments to test the pattern with.

getDate

protected final java.util.Date getDate(java.lang.String key)

getStringArrayFromCommaString

protected final java.lang.String[] getStringArrayFromCommaString(java.lang.String key,
                                                                 java.lang.String itemsDescription)

Gets the value for the given key. The value is expected to be an String which subvalues are separated using comma's. Empty Strings will not be returned.

Parameters:

key - Key to search on.

itemsDescription - Description of individual values, should be written in plural. Example: "email adresses". Optional, can be null.

Returns:

A String array. Never null, might be empty (zero elements).

getStringArrayFromCommaString

protected final java.lang.String[] getStringArrayFromCommaString(java.lang.String key)

Gets the value for the given key. The value is expected to be an String which subvalues are separated using comma's. Empty Strings will not be returned.

Parameters:

key - Key to search on.

Returns:

A String array. Never null, might be empty (zero elements).

getURL

protected final java.net.URL getURL(java.lang.String key)

Gets the value for the given key. The value is expected to be an URL. A String is an URL if it can be read by the .

Parameters:

key - Key to search on.

Returns:

An URL. Never null.

getBoolean

protected final boolean getBoolean(java.lang.String key)

Gets the value for the given key. The value is boolean, so true or false. The following texts are recognized: on, true, yes and 1, and off, false, no and 0. Any other value causes an exception.

Parameters:

key - Key to search on.

Returns:

boolean

Throws:

InvalidPropertyException - If the value cannot be parsed as a boolean.

getExistingReadableFile

protected final java.io.File getExistingReadableFile(java.lang.String key)

getWritableFile

protected final java.io.File getWritableFile(java.lang.String key)

hasValue

protected final boolean hasValue(java.lang.String key)

Indicates whether or not a value is given for this key.

Parameters:

key - Cannot be null.

Returns:

true if a value has been given; false otherwise.