net.sf.eBus.util

Class Properties

java.lang.Object

java.util.Dictionary<K,V>

java.util.Hashtable<Object,Object>

java.util.Properties

net.sf.eBus.util.Properties

All Implemented Interfaces:

Serializable, Cloneable, Map<Object,Object>

public final class Properties
extends Properties

Properties extends java.util.Properties to include:

• Loading properties from a named file and returning a net.sf.eBus.util.Properties object.
• Storing a Properties object into a named file.
• Returning property values as a boolean, int, double and String array.
• Setting property values as a boolean, int, double and String array.
• Informs registered PropertiesListeners when the underlying properties file has changed and been automatically reloaded.

  Note: automatic properties file reloading is done only if there is a registered properties listener. If there are no registered listeners, then Properties does not watch the underlying file for changes and so does not automatically reload the properties file if it should change.

Author:

Charles Rapp

See Also:

Serialized Form

Field Summary

Fields inherited from class java.util.Properties

defaults

Constructor Summary

Constructors

Constructor and Description
Properties() Creates an empty property list with no default values.
Properties(Properties defaults) Creates an empty property list with default values.

Method Summary

Modifier and Type	Method and Description
void	addListener(PropertiesListener listener) Adds a properties listener.
boolean	equals(Object o)
String[]	getArrayProperty(String key, char ifs) Returns the named property value as a String[].
boolean	getBooleanProperty(String key) Returns the named property value as a boolean.
boolean	getBooleanProperty(String key, boolean defaultValue) Returns the named property value as a boolean.
double	getDoubleProperty(String key) Returns the named property value as a double.
double	getDoubleProperty(String key, double defaultValue) Returns the named property value as a double.
int	getIntProperty(String key) Returns the named property value as an int.
int	getIntProperty(String key, int defaultValue) Returns the named property value as an int.
int	hashCode()
void	load() Reloads properties from the properties file.
static Properties	loadProperties(File file) Returns a properties list loaded with the values found in the properties file.
static Properties	loadProperties(String fileName) Returns a properties list loaded with the values found in the named properties file.
void	removeListener(PropertiesListener listener) Removes a properties listener.
void	setArrayProperty(String key, String[] value, char ifs) Sets the named property value to the string array.
void	setBooleanProperty(String key, boolean value) Sets the named property value to the specified boolean.
void	setDoubleProperty(String key, double value) Sets the named property value to the specified double.
void	setIntProperty(String key, int value) Sets the named property value to the specified integer.
void	store(File file, String header) Stores properties in the named properties file using the provided header comment.
void	store(String header) Stores properties in properties file using the provided header comment.
void	store(String fileName, String header) Stores properties in the named properties file using the provided header comment.
Set<String>	stringPropertyNames(Pattern p) Returns a set of keys in this property list whose key matches the given regular expression pattern p and the corresponding values are strings.

Methods inherited from class java.util.Properties

getProperty, getProperty, list, list, load, load, loadFromXML, propertyNames, save, setProperty, store, store, storeToXML, storeToXML, stringPropertyNames

Methods inherited from class java.util.Hashtable

clear, clone, compute, computeIfAbsent, computeIfPresent, contains, containsKey, containsValue, elements, entrySet, forEach, get, getOrDefault, isEmpty, keys, keySet, merge, put, putAll, putIfAbsent, rehash, remove, remove, replace, replace, replaceAll, size, toString, values

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Properties

public Properties()

Creates an empty property list with no default values. Because there is no associated file, property listening is not allowed.

Properties

public Properties(Properties defaults)

Creates an empty property list with default values. Because there is no associated file, property listening is not allowed.

Parameters:

defaults - the default property values.

Method Detail

equals

public boolean equals(Object o)

Specified by:

equals in interface Map<Object,Object>

Overrides:

equals in class Hashtable<Object,Object>

hashCode

public int hashCode()

Specified by:

hashCode in interface Map<Object,Object>

Overrides:

hashCode in class Hashtable<Object,Object>

getBooleanProperty

public boolean getBooleanProperty(String key)

Returns the named property value as a boolean. If key is an unknown property or is neither "true" nor "false" then returns false.

Parameters:

key - The property key.

Returns:

the named property value as a boolean. If the value is "true", then true is returned, otherwise returns false.

See Also:

getBooleanProperty(String, boolean), setBooleanProperty(String, boolean)

getIntProperty

public int getIntProperty(String key)

Returns the named property value as an int. If key is an unknown property or is not a valid integer, then returns 0.

Parameters:

key - The property key.

Returns:

the named property value as an int.

See Also:

getIntProperty(String, int), setIntProperty(String, int)

getDoubleProperty

public double getDoubleProperty(String key)

Returns the named property value as a double. If key is an unknown property or is not a value double, then returns 0.0.

Parameters:

key - The property key.

Returns:

the named property value as a double.

Throws:

NumberFormatException - if the property value is not a valid double.

See Also:

getDoubleProperty(String, double), setDoubleProperty(String, double)

getArrayProperty

public String[] getArrayProperty(String key,
                                 char ifs)

Returns the named property value as a String[]. ifs is used as the interfield separator character. If the property value does not exist, then returns an empty array.

Parameters:

key - The property key.

ifs - The interfield separator.

Returns:

the named property value as a String[]. If the property value does not exist, then returns an empty array.

See Also:

setArrayProperty(String, String[], char)

getBooleanProperty

public boolean getBooleanProperty(String key,
                                  boolean defaultValue)

Returns the named property value as a boolean. If key is an unknown property or an invalid boolean string, then returns the default value.

Parameters:

key - The property key.

defaultValue - The default value.

Returns:

the named property value as a boolean. If key is an unknown property or an invalid boolean string, then returns defaultValue.

See Also:

getBooleanProperty(String), setBooleanProperty(String, boolean)

getIntProperty

public int getIntProperty(String key,
                          int defaultValue)

Returns the named property value as an int. If either the property does not exist or does exist but is not an integer, then returns the default value.

Parameters:

key - The property key.

defaultValue - The default value.

Returns:

the named property value as an int or defaultValue.

See Also:

getIntProperty(String), setIntProperty(String, int)

getDoubleProperty

public double getDoubleProperty(String key,
                                double defaultValue)

Returns the named property value as a double. If the property value does not exist or is not a valid double, then returns the default value.

Parameters:

key - The property key.

defaultValue - The default value.

Returns:

the named property value as a double. If the property value does not exist or is not a valid double, then returns defaultValue.

See Also:

getDoubleProperty(String), setDoubleProperty(String, double)

stringPropertyNames

public Set<String> stringPropertyNames(Pattern p)

Returns a set of keys in this property list whose key matches the given regular expression pattern p and the corresponding values are strings. Includes distinct keys in the default property list if a key of the same name is not in the main properties list. Properties whose key or value is not of type String are omitted.

The returned set is not backed by the Properties object. Changes to this Properties are not reflected in the set or vice versa.

Parameters:

p - match property keys against this pattern.

Returns:

String property keys matching the regular expression pattern.

See Also:

Properties.stringPropertyNames(), Properties.defaults

setBooleanProperty

public void setBooleanProperty(String key,
                               boolean value)

Sets the named property value to the specified boolean.

Parameters:

key - The property key.

value - The boolean value.

See Also:

getBooleanProperty(String), getBooleanProperty(String, boolean)

setIntProperty

public void setIntProperty(String key,
                           int value)

Sets the named property value to the specified integer.

Parameters:

key - The property key.

value - The integer value.

See Also:

getIntProperty(String), getIntProperty(String, int)

setDoubleProperty

public void setDoubleProperty(String key,
                              double value)

Sets the named property value to the specified double.

Parameters:

key - The property key.

value - The double value.

See Also:

getDoubleProperty(String), getDoubleProperty(String, double)

setArrayProperty

public void setArrayProperty(String key,
                             String[] value,
                             char ifs)

Sets the named property value to the string array. The array is converted into a single string by concatenating the strings together separated by ifs.

Parameters:

key - The property key.

value - The string array.

ifs - The interfield separator.

See Also:

getArrayProperty(java.lang.String, char)

load

public void load()
          throws IOException

Reloads properties from the properties file.

Throws:

IOException - if there are errors reading in the properties file.

See Also:

store(String), loadProperties(String), loadProperties(File)

store

public void store(String header)
           throws FileNotFoundException,
                  IOException

Stores properties in properties file using the provided header comment. The header comment is placed at the property file's start.

Parameters:

header - File header comment. May be null.

Throws:

FileNotFoundException - if the properties file could not be created.

IOException - if there is an error storing the properties into the file.

See Also:

load(), loadProperties(String), loadProperties(File)

store

public void store(String fileName,
                  String header)
           throws IllegalArgumentException,
                  FileNotFoundException,
                  IOException

Stores properties in the named properties file using the provided header comment. The header comment is placed at the property file's start.

Parameters:

fileName - Property file's name.

header - File header comment. May be null.

Throws:

IllegalArgumentException - if fileName is either null or an empty string.

FileNotFoundException - if the properties file could not be created.

IOException - if there is an error storing the properties into the file.

See Also:

store(String), store(File, String), load(), loadProperties(String), loadProperties(File)

store

public void store(File file,
                  String header)
           throws IllegalArgumentException,
                  FileNotFoundException,
                  IOException

Stores properties in the named properties file using the provided header comment. The header comment is placed at the property file's start.

Parameters:

file - Property file.

header - File header comment. May be null.

Throws:

IllegalArgumentException - if file is null.

FileNotFoundException - if the properties file could not be created.

IOException - if there is an error storing the properties into the file.

See Also:

store(String), store(String, String), load(), loadProperties(String), loadProperties(File)

addListener

public void addListener(PropertiesListener listener)
                 throws IllegalArgumentException,
                        IllegalStateException

Adds a properties listener. If this is the first listener and the watchRate > zero, then starts the watch timer.

Note: when the underlying properties file changes, it will be automatically reloaded prior to calling back to the registered PropertiesListeners.

Parameters:

listener - Add this properties listener.

Throws:

IllegalArgumentException - if listener is null.

IllegalStateException - if this is no underlying property file.

removeListener

public void removeListener(PropertiesListener listener)

Removes a properties listener. If there are no more listeners and the watch timer is running, then the timer is canceled.

Note: when the watch timer is canceled, Properties will no longer determine if the underlying properties file has changed and so will not automatically reload said file if it should change.

Parameters:

listener - Remove this listener.

Throws:

IllegalStateException - if this is no underlying property file.

loadProperties

public static Properties loadProperties(String fileName)
                                 throws IllegalArgumentException,
                                        IOException

Returns a properties list loaded with the values found in the named properties file. If the file does not exist, an empty properties object is returned. This allows new properties to be created and stored.

Parameters:

fileName - the properties file name.

Returns:

A properties list.

Throws:

IllegalArgumentException - if fileName is either null or an empty string.

IOException - if fileName is not a valid properties file.

See Also:

loadProperties(File), load(), store(String)

loadProperties

public static Properties loadProperties(File file)
                                 throws IllegalArgumentException,
                                        IOException

Returns a properties list loaded with the values found in the properties file. If the file does not exist, an empty properties object is returned. This allows new properties to be created and stored.

Parameters:

file - the properties file object.

Returns:

A properties list.

Throws:

IllegalArgumentException - if file is null.

IOException - if file is not a valid properties file.

See Also:

loadProperties(String), load(), store(String)