com.samskivert.util
Class ConfigUtil

java.lang.Object
  com.samskivert.util.ConfigUtil

public class ConfigUtil
extends Object

The config util class provides routines for loading configuration information.

See Also:

loadProperties(java.lang.String), getSystemProperty(java.lang.String, int)

Nested Class Summary

protected static class

ConfigUtil.PropRecord Used when parsing inherited properties.

Field Summary

protected static String	EXTENDS_KEY
protected static String	OVERRIDES_KEY
protected static String	PACKAGE_KEY

Constructor Summary

ConfigUtil()

Method Summary

protected static InputStream	getResourceAsStream(String path, ClassLoader loader)
protected static Enumeration<URL>	getResources(String path, ClassLoader loader)
static InputStream	getStream(String path) Returns an input stream referencing a file that exists somewhere in the classpath.
static InputStream	getStream(String path, ClassLoader loader) Returns an input stream referencing a file that exists somewhere in the classpath.
static int	getSystemProperty(String key, int defval) Obtains the specified system property via System.getProperty(java.lang.String), parses it into an integer and returns the value.
static Properties	loadInheritedProperties(String path) Creates a properties instance by combining properties files loaded using the specified classpath-relative property file path.
static Properties	loadInheritedProperties(String path, ClassLoader loader) Like loadInheritedProperties(String) but this method uses the supplied class loader rather than the class loader used to load the ConfigUtil class.
static void	loadInheritedProperties(String path, ClassLoader loader, Properties target) Like loadInheritedProperties(String,ClassLoader) but the properties are loaded into the supplied properties object.
static void	loadInheritedProperties(String path, Properties target) Like loadInheritedProperties(String) but loads the properties into the supplied target object.
static Properties	loadProperties(String path) Loads a properties file from the named file that exists somewhere in the classpath.
static Properties	loadProperties(String path, ClassLoader loader) Like loadProperties(String) but this method uses the supplied class loader rather than the class loader used to load the ConfigUtil class.
static void	loadProperties(String path, ClassLoader loader, Properties target) Like loadProperties(String,ClassLoader) but the properties are loaded into the supplied Properties object.
protected static void	loadPropertiesOverrides(ConfigUtil.PropRecord prec, HashMap<String,ConfigUtil.PropRecord> records, HashMap<String,ConfigUtil.PropRecord> applied, ClassLoader loader, Properties target) loadInheritedProperties(String,ClassLoader,Properties) helper function.
protected static ConfigUtil.PropRecord	parseMetaData(String path, URL sourceURL) Performs simple processing of the supplied input stream to obtain inheritance metadata from the properties file.
protected static String	parseValue(String line) parseMetaData(java.lang.String, java.net.URL) helper function.
protected static String[]	parseValues(String line) parseMetaData(java.lang.String, java.net.URL) helper function.
protected static String	togglePath(String path)

Methods inherited from class java.lang.Object

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

Field Detail

PACKAGE_KEY

protected static final String PACKAGE_KEY

See Also:

Constant Field Values

OVERRIDES_KEY

protected static final String OVERRIDES_KEY

See Also:

Constant Field Values

EXTENDS_KEY

protected static final String EXTENDS_KEY

See Also:

Constant Field Values

Constructor Detail

ConfigUtil

public ConfigUtil()

Method Detail

getSystemProperty

public static int getSystemProperty(String key,
                                    int defval)

Obtains the specified system property via System.getProperty(java.lang.String), parses it into an integer and returns the value. If the property is not set, the default value will be returned. If the property is not a properly formatted integer, an error will be logged and the default value will be returned.

loadProperties

public static Properties loadProperties(String path)
                                 throws IOException

Loads a properties file from the named file that exists somewhere in the classpath.

The classloader that loaded the ConfigUtil class is searched first, followed by the system classpath. If you wish to provide an additional classloader, use the version of this function that takes a classloader as an argument.

Parameters:

path - The path to the properties file, relative to the root of the classpath entry from which it will be loaded (e.g. com/foo/config.properties).

Returns:

A properties object loaded with the contents of the specified file if the file could be found, null otherwise.

Throws:

IOException

loadProperties

public static Properties loadProperties(String path,
                                        ClassLoader loader)
                                 throws IOException

Like loadProperties(String) but this method uses the supplied class loader rather than the class loader used to load the ConfigUtil class.

Throws:

IOException

loadProperties

public static void loadProperties(String path,
                                  ClassLoader loader,
                                  Properties target)
                           throws IOException

Like loadProperties(String,ClassLoader) but the properties are loaded into the supplied Properties object.

Throws:

IOException

loadInheritedProperties

public static Properties loadInheritedProperties(String path)
                                          throws IOException

Creates a properties instance by combining properties files loaded using the specified classpath-relative property file path.

The inheritance works in two ways:

• Overrides

  All properties files with the specified name are located in the classpath and merged into a single set of properties according to an explicit inheritance hierarchy defined by a couple of custom properties. This is best explained with an example:

  com/samskivert/foolib/config.properties contains:

   _package = foolib
  
   config1 = value1
   config2 = value2
   ...
   

  and this is packaged into foolib.jar. Happy Corp writes an application that uses foolib and wants to override some properties in foolib's configuration. They create a properties file in happyapp.jar with the path com/samskivert/foolib/config.properties. It contains:

   _package = happyapp
   _overrides = foolib
  
   config2 = happyvalue
   

  When foolib loads its config.properties the overrides from happyapp.jar will be applied to the properties defined in foolib.jar and foolib will see Happy Corp's overridden properties.

  Note that conflicting overrides must be resolved "by hand" so to speak. For example, if Happy Corp used some other library that also overrode foolib's configuration, say barlib, whose barlib.jar contained:

   _package = barlib
   _overrides = foolib
  
   config1 = barvalue
   

  Happy Corp's config.properties would not be able to override foolib's configuration directly because the config system would not know which overrides to use. It instead must override barlib's configuration, like so:

   _package = happyapp
   _overrides = barlib
   ...
   

  Moreover, if there were yet a third library that also overrode foolib, Happy Corp would have to resolve the conflict between barlib and bazlib explicitly:

   _package = happyapp
   _overrides = barlib, bazlib
   ...
   

  This would force bazlib's overrides to take precedence over barlib's overrides, resolving the inheritance ambiguity created when both barlib and bazlib claimed to override foolib.

  This all certainly seems a bit complicated, but in most cases there is only one user of a library and overriding is very straightforward. The additional functionality is provided to resolve cases where conflicts do arise.

• Extends

  The second type of inheritance, extension, is more straightforward. In this case, a properties file explicitly extends another properties file. For example, com/foocorp/puzzle/config.properties contains:

   # Standard configuration options
   score = 25
   multiplier = 2
   

  com/foocorp/puzzle/footris/config.properties contains:

   _extends = com/foocorp/puzzle/config.properties
  
   # Footris configuration options
   score = 15 # override the default score
   bonus = 55
   

  The Footris configuration will inherit default values from the general puzzle configuration, overriding any that are specified explicitly.

  When resolving a properties file that extends another properties file, first the extended properties are loaded and all _overrides are applied to that properties file. Then all _overrides are applied to the extending properties file and then the extending properties are merged with the extended properties.

A final note: All of the inheritance directives must be grouped together in an uninterrupted sequence of lines. One the parsing code finds the first directive, it stops parsing when it sees a line that does not contain a directive.

Parameters:

path - The path to the properties file, relative to the root of the classpath entries from which it will be loaded (e.g. com/foo/config.properties).

Returns:

A properties object loaded with the contents of the specified file if the file could be found, null otherwise.

Throws:

IOException

loadInheritedProperties

public static void loadInheritedProperties(String path,
                                           Properties target)
                                    throws IOException

Like loadInheritedProperties(String) but loads the properties into the supplied target object.

Throws:

IOException

loadInheritedProperties

public static Properties loadInheritedProperties(String path,
                                                 ClassLoader loader)
                                          throws IOException

Like loadInheritedProperties(String) but this method uses the supplied class loader rather than the class loader used to load the ConfigUtil class.

Throws:

IOException

loadInheritedProperties

public static void loadInheritedProperties(String path,
                                           ClassLoader loader,
                                           Properties target)
                                    throws IOException

Like loadInheritedProperties(String,ClassLoader) but the properties are loaded into the supplied properties object. Properties that already exist in the supplied object will be overwritten by the loaded properties where they have the same key.

Throws:

IOException

loadPropertiesOverrides

protected static void loadPropertiesOverrides(ConfigUtil.PropRecord prec,
                                              HashMap<String,ConfigUtil.PropRecord> records,
                                              HashMap<String,ConfigUtil.PropRecord> applied,
                                              ClassLoader loader,
                                              Properties target)
                                       throws IOException

loadInheritedProperties(String,ClassLoader,Properties) helper function.

Throws:

IOException

parseMetaData

protected static ConfigUtil.PropRecord parseMetaData(String path,
                                                     URL sourceURL)
                                              throws IOException

Performs simple processing of the supplied input stream to obtain inheritance metadata from the properties file.

Throws:

IOException

parseValue

protected static String parseValue(String line)

parseMetaData(java.lang.String, java.net.URL) helper function.

parseValues

protected static String[] parseValues(String line)

parseMetaData(java.lang.String, java.net.URL) helper function.

getStream

public static InputStream getStream(String path)

Returns an input stream referencing a file that exists somewhere in the classpath.

The classloader that loaded the ConfigUtil class is searched first, followed by the system classpath. If you wish to provide an additional classloader, use the version of this function that takes a classloader as an argument.

Parameters:

path - The path to the file, relative to the root of the classpath directory from which it will be loaded (e.g. com/foo/bar/foo.gif).

getStream

public static InputStream getStream(String path,
                                    ClassLoader loader)

Returns an input stream referencing a file that exists somewhere in the classpath.

The supplied classloader is searched first, followed by the system classloader.

Parameters:

path - The path to the file, relative to the root of the classpath directory from which it will be loaded (e.g. com/foo/bar/foo.gif).

getResourceAsStream

protected static InputStream getResourceAsStream(String path,
                                                 ClassLoader loader)

getResources

protected static Enumeration<URL> getResources(String path,
                                               ClassLoader loader)
                                        throws IOException

Throws:

IOException

togglePath

protected static String togglePath(String path)