org.syphr.prom
Class PropertiesManager<T>

java.lang.Object
  extended by org.syphr.prom.PropertiesManager<T>
Type Parameters:
T - the type that represents the keys of the properties file

public class PropertiesManager<T>
extends Object

This class creates a management API for a Properties file.

Author:
Gregory P. Moyer

Constructor Summary
PropertiesManager(File file, Properties defaults, Translator<T> translator, Evaluator evaluator, ExecutorService executor)
          Construct a new manager for the given properties file.
 
Method Summary
 void addPropertyListener(PropertyListener<T> listener)
          Add a listener for property events (such as change, save, load).
 PropertiesManager<T> copy(File newFile)
          Copy the current state of this manager to a new instance that is based on a different file.
protected  Retriever createRetriever()
          Build a new Retriever instance that will be used by the evaluator to request the values of nested property references.
 boolean getBooleanProperty(T property)
          Retrieve the value of the given property as a boolean.
 double getDoubleProperty(T property)
          Retrieve the value of the given property as a double.
 double getDoublePropertyFallback(T property)
          Retrieve the value of the given property as a double.
<E extends Enum<E>>
E
getEnumProperty(T property, Class<E> type)
          Retrieve the value of the given property as an Enum constant of the given type.

Note that this method requires the Enum constants to all have upper case names (following Java naming conventions).
<E extends Enum<E>>
E
getEnumPropertyFallback(T property, Class<E> type)
          Retrieve the value of the given property as an Enum constant of the given type.
protected  Evaluator getEvaluator()
          Retrieve the object that converts nested property references into evaluated strings.
 File getFile()
           
 float getFloatProperty(T property)
          Retrieve the value of the given property as a float.
 float getFloatPropertyFallback(T property)
          Retrieve the value of the given property as a float.
 int getIntegerProperty(T property)
          Retrieve the value of the given property as an integer.
 int getIntegerPropertyFallback(T property)
          Retrieve the value of the given property as an integer.
 long getLongProperty(T property)
          Retrieve the value of the given property as a long.
 long getLongPropertyFallback(T property)
          Retrieve the value of the given property as a long.
 Properties getProperties()
          Retrieve a Properties object that contains the properties managed by this instance.

Please note that the returned Properties object is not connected in any way to this manager and is only a snapshot of what the properties looked like at the time the request was fulfilled.
 String getProperty(T property)
          Get the current value of the given property.
 PropertyManager<T> getPropertyManager(T property)
          Get an object that will encapsulate the functionality of this manager specific to a single property.
 String getRawProperty(T property)
          Get the current value of the given property, but without translating references.
protected  Retriever getRetriever()
          Get the Retriever instance used internally to fetch values using an Evaluator.
 Translator<T> getTranslator()
          Retrieve the object that translates between key objects and property names.
 boolean isAutoTrim()
          Determine whether or not values will be automatically trimmed of whitespace as they are read.
 boolean isDefault(T property)
          Determine whether or not the given property is set to its default value.
 boolean isModified()
          Determine whether or not any property has been modified since the last load or save.
 boolean isModified(T property)
          Determine whether or not the given property has been modified since it was last load or saved.
 boolean isReferencing(T property1, T property2)
          Determine whether or not one property holds references to another property.
 boolean isSavingDefaults()
          Determine whether or not default values will be written to the properties file when and if it is saved.
 Set<T> keySet()
          Retrieve the set of keys currently in use by this manager.
 void load()
          Load the current values of all properties.

This method will block and wait for the properties to be loaded.
 Future<Void> loadNB()
          Load the properties file.
 void loadProperty(T property)
          Load the current value of the given property from the file without modifying the values of any other properties.
 Future<Void> loadPropertyNB(T property)
          Load the current value of the given property from the file without modifying the values of any other properties.
 Reference referenceAt(T property, int position)
          Retrieve the reference to another property from within the value of the given property at the given position.
 void removePropertyListener(PropertyListener<T> listener)
          Remove a property listener.
 void reset()
          Reset the properties to the original defaults.
 void resetProperty(T property)
          Reset the given property to its default value.
 void save()
          Save the current values of all properties.

This method will block and wait for the properties to be saved.
 Future<Void> saveNB()
          Save the current values of all properties.

This method will not block to wait for the properties to be saved.
 void saveProperty(T property)
          Save the current value of the given property to the file without modifying the values of any other properties in the file.
<E extends Enum<E>>
void
saveProperty(T property, E value)
          Save the given property using an Enum constant.
 void saveProperty(T property, Object value)
          Save the given property using an object's string representation.
 void saveProperty(T property, String value)
          Modify the value of the given property and save only that change to permanent storage.
 Future<Void> savePropertyNB(T property)
          Save the current value of the given property to the file without modifying the values of any other properties in the file.
 void setAutoTrim(boolean autoTrim)
          Set the flag that determines whether or not values will be automatically trimmed of whitespace as they are read.
 void setComment(String comment)
          Set a comment that will be written to the file that stores the properties managed by this instance.

The default is no comment.
<E extends Enum<E>>
void
setProperty(T property, E value)
          Set the given property using an Enum constant.
 void setProperty(T property, Object value)
          Set the given property using an object's string representation.
 void setProperty(T property, String value)
          Set the given property using a string.
 void setSavingDefaults(boolean savingDefaults)
          Set the flag that determines whether or not default values are saved to the properties file when and if it is written.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

PropertiesManager

public PropertiesManager(File file,
                         Properties defaults,
                         Translator<T> translator,
                         Evaluator evaluator,
                         ExecutorService executor)
Construct a new manager for the given properties file.

Parameters:
file - the file system location of the properties represented here
defaults - default values for the properties represented here
translator - the translator to convert between key objects and property names
evaluator - the evaluator to convert nested property references into fully evaluated strings
executor - a service to handle potentially long running tasks, such as interacting with the file system
Method Detail

copy

public PropertiesManager<T> copy(File newFile)
Copy the current state of this manager to a new instance that is based on a different file. The logical use case for this is to specify a file that does not currently exist and then call save(). This would effectively copy the properties file.

Note that this method does not copy listeners or PropertyManager instances. It will also install the current Translator, Evaluator, ExecutorService, as well as the default Properties into the new instance.

Parameters:
newFile - the file to which the new instance will be based
Returns:
a new manager with the same property values and defaults as this instance

setSavingDefaults

public void setSavingDefaults(boolean savingDefaults)
Set the flag that determines whether or not default values are saved to the properties file when and if it is written.

Parameters:
savingDefaults - the flag to set

isSavingDefaults

public boolean isSavingDefaults()
Determine whether or not default values will be written to the properties file when and if it is saved.

Returns:
true if default values will be written out; false otherwise

setAutoTrim

public void setAutoTrim(boolean autoTrim)
Set the flag that determines whether or not values will be automatically trimmed of whitespace as they are read.

Parameters:
autoTrim - the flag to set

isAutoTrim

public boolean isAutoTrim()
Determine whether or not values will be automatically trimmed of whitespace as they are read.

Returns:
true if values will be trimmed; false otherwise

setComment

public void setComment(String comment)
Set a comment that will be written to the file that stores the properties managed by this instance.

The default is no comment.

Parameters:
comment - the comment to set

getFile

public File getFile()
Returns:
the file represented by this properties manager

getPropertyManager

public PropertyManager<T> getPropertyManager(T property)
Get an object that will encapsulate the functionality of this manager specific to a single property. This makes it easier to watch, modify, and generally interact with a single property.

Parameters:
property - the property to manage
Returns:
the encapsulation of the functionality of this manager as it pertains to a single property

addPropertyListener

public void addPropertyListener(PropertyListener<T> listener)
Add a listener for property events (such as change, save, load).

Parameters:
listener - the listener to add

removePropertyListener

public void removePropertyListener(PropertyListener<T> listener)
Remove a property listener.

Parameters:
listener - the listener to remove

getTranslator

public Translator<T> getTranslator()
Retrieve the object that translates between key objects and property names.

Returns:
the property name translator

getEvaluator

protected Evaluator getEvaluator()
Retrieve the object that converts nested property references into evaluated strings.

Returns:
the nested property evaluator

getProperties

public Properties getProperties()
Retrieve a Properties object that contains the properties managed by this instance.

Please note that the returned Properties object is not connected in any way to this manager and is only a snapshot of what the properties looked like at the time the request was fulfilled.

Returns:
a Properties instance containing the properties managed by this instance (including defaults)

keySet

public Set<T> keySet()
Retrieve the set of keys currently in use by this manager. This encompasses any key which currently has a value or a default value associated with it. Normally, this should have the same contents as an enumeration of the valid key objects, but it is not guaranteed.

An example of where this set would not have the same contents as the set of key objects would be if at least one property key has no value defined for it and no default value associated with it. In that case, it would not be included in this set.

Returns:
the set of keys currently in use by this manager

getProperty

public String getProperty(T property)
Get the current value of the given property.

Parameters:
property - the property to retrieve
Returns:
the value of the given property (or null if an error occurred while attempting to read the properties)

getBooleanProperty

public boolean getBooleanProperty(T property)
Retrieve the value of the given property as a boolean.

Parameters:
property - the property to retrieve
Returns:
true if the value of the property is "true" (case insensitive); false otherwise

getIntegerProperty

public int getIntegerProperty(T property)
                       throws NumberFormatException
Retrieve the value of the given property as an integer.

Parameters:
property - the property to retrieve
Returns:
the integer value of the given property
Throws:
NumberFormatException - if the current value is not an integer

getIntegerPropertyFallback

public int getIntegerPropertyFallback(T property)
                               throws NumberFormatException
Retrieve the value of the given property as an integer. If the current value of the specified property cannot be converted to an integer, the default value will be retrieved.

Parameters:
property - the property to retrieve
Returns:
the integer value of the given property or the default value if the current value is not a valid integer
Throws:
NumberFormatException - if both the current and default values are not integers

getLongProperty

public long getLongProperty(T property)
                     throws NumberFormatException
Retrieve the value of the given property as a long.

Parameters:
property - the property to retrieve
Returns:
the long value of the given property
Throws:
NumberFormatException - if the current value is not a long

getLongPropertyFallback

public long getLongPropertyFallback(T property)
                             throws NumberFormatException
Retrieve the value of the given property as a long. If the current value of the specified property cannot be converted to a long, the default value will be retrieved.

Parameters:
property - the property to retrieve
Returns:
the long value of the given property or the default value if the current value is not a valid long
Throws:
NumberFormatException - if both the current and default values are not longs

getFloatProperty

public float getFloatProperty(T property)
                       throws NumberFormatException
Retrieve the value of the given property as a float.

Parameters:
property - the property to retrieve
Returns:
the float value of the given property
Throws:
NumberFormatException - if the current value is not a float

getFloatPropertyFallback

public float getFloatPropertyFallback(T property)
                               throws NumberFormatException
Retrieve the value of the given property as a float. If the current value of the specified property cannot be converted to a float, the default value will be retrieved.

Parameters:
property - the property to retrieve
Returns:
the float value of the given property or the default value if the current value is not a valid float
Throws:
NumberFormatException - if both the current and default values are not floats

getDoubleProperty

public double getDoubleProperty(T property)
                         throws NumberFormatException
Retrieve the value of the given property as a double.

Parameters:
property - the property to retrieve
Returns:
the double value of the given property
Throws:
NumberFormatException - if the current value is not a double

getDoublePropertyFallback

public double getDoublePropertyFallback(T property)
                                 throws NumberFormatException
Retrieve the value of the given property as a double. If the current value of the specified property cannot be converted to a double, the default value will be retrieved.

Parameters:
property - the property to retrieve
Returns:
the double value of the given property or the default value if the current value is not a valid double
Throws:
NumberFormatException - if both the current and default values are not doubles

getEnumProperty

public <E extends Enum<E>> E getEnumProperty(T property,
                                             Class<E> type)
                                  throws IllegalArgumentException
Retrieve the value of the given property as an Enum constant of the given type.

Note that this method requires the Enum constants to all have upper case names (following Java naming conventions). This allows for case insensitivity in the properties file.

Type Parameters:
E - the type of Enum that will be returned
Parameters:
property - the property to retrieve
type - the Enum type to which the property will be converted
Returns:
the Enum constant corresponding to the value of the given property
Throws:
IllegalArgumentException - if the current value is not a valid constant of the given type

getEnumPropertyFallback

public <E extends Enum<E>> E getEnumPropertyFallback(T property,
                                                     Class<E> type)
                                          throws IllegalArgumentException
Retrieve the value of the given property as an Enum constant of the given type. If the current value of the specified property cannot be converted to the appropriate Enum, the default value will be retrieved.

Note that this method requires the Enum constants to all have upper case names (following Java naming conventions). This allows for case insensitivity in the properties file.

Type Parameters:
E - the type of Enum that will be returned
Parameters:
property - the property to retrieve
type - the Enum type to which the property will be converted
Returns:
the Enum constant corresponding to the value of the given property or the default value if the current value is not a valid instance of the given type
Throws:
IllegalArgumentException - if both the current and default values are not valid constants of the given type

getRawProperty

public String getRawProperty(T property)
Get the current value of the given property, but without translating references. If auto trim is enabled, the value will also be trimmed of whitespace.

Parameters:
property - the property to retrieve
Returns:
the value of the given property

isDefault

public boolean isDefault(T property)
Determine whether or not the given property is set to its default value.

Parameters:
property - the property to check
Returns:
true if the given property has its default value; false otherwise

isReferencing

public boolean isReferencing(T property1,
                             T property2)
Determine whether or not one property holds references to another property.

Parameters:
property1 - the property to check for references
property2 - the target referenced property
Returns:
true if the first property references the second; false otherwise

referenceAt

public Reference referenceAt(T property,
                             int position)
Retrieve the reference to another property from within the value of the given property at the given position. If such a reference does not exist, the result of this method will be null.

Parameters:
property - the property to search for the requested reference
position - the position to check for a reference
Returns:
the appropriate reference if one exists; null otherwise

loadProperty

public void loadProperty(T property)
                  throws IOException
Load the current value of the given property from the file without modifying the values of any other properties. In other words, isModified(Object) will return false for the given property after this call completes, but it will return true for any other properties that have been modified since the last load or save.

This method will block and wait for the property to be loaded. See loadPropertyNB(Object) for a non-blocking version.

Parameters:
property - the property to load
Throws:
IOException - if there is an error while attempting to read the property from the file

loadPropertyNB

public Future<Void> loadPropertyNB(T property)
Load the current value of the given property from the file without modifying the values of any other properties. In other words, isModified(Object) will return false for the given property after this call completes, but it will return true for any other properties that have been modified since the last load or save.

This method will not block to wait for the property to be loaded. See loadProperty(Object) for a blocking version.

Parameters:
property - the property to save
Returns:
a task representing this save request
Throws:
IOException - if there is an error while attempting to write the property to the file

load

public void load()
          throws IOException
Load the current values of all properties.

This method will block and wait for the properties to be loaded. See loadNB() for a non-blocking version.

Throws:
IOException - if there is an error while attempting to load the properties

loadNB

public Future<Void> loadNB()
Load the properties file. This will override all current values with whatever has last been saved.

This method will not block to wait for the properties to be loaded. See load() for a blocking version.

Returns:
a Future representing this load request

setProperty

public <E extends Enum<E>> void setProperty(T property,
                                            E value)
                 throws IllegalArgumentException
Set the given property using an Enum constant. This will not write the new value to the file system.

Please note that the Enum value set here is case insensitive. See getEnumProperty(Object, Class) for additional details.

Type Parameters:
E - the type of Enum value to set
Parameters:
property - the property whose value is being set
value - the value to set
Throws:
IllegalArgumentException - if a null value is given (see resetProperty(Object))
See Also:
saveProperty(Object, Enum)

setProperty

public void setProperty(T property,
                        Object value)
                 throws IllegalArgumentException
Set the given property using an object's string representation. This will not write the new value to the file system.

Parameters:
property - the property whose value is being set
value - the value to set
Throws:
IllegalArgumentException - if a null value is given (see resetProperty(Object))
See Also:
saveProperty(Object, Object)

setProperty

public void setProperty(T property,
                        String value)
                 throws IllegalArgumentException
Set the given property using a string. This will not write the new value to the file system.

Parameters:
property - the property whose value is being set
value - the value to set
Throws:
IllegalArgumentException - if a null value is given (see resetProperty(Object))
See Also:
saveProperty(Object, String)

saveProperty

public <E extends Enum<E>> void saveProperty(T property,
                                             E value)
                  throws IOException
Save the given property using an Enum constant. See saveProperty(Object, String) for additional details.

Please note that the Enum value saved here is case insensitive. See getEnumProperty(Object, Class) for additional details.

Type Parameters:
E - the type of Enum value to save
Parameters:
property - the property whose value is being saved
value - the value to save
Throws:
IOException - if there is an error while attempting to write the property to the file

saveProperty

public void saveProperty(T property,
                         Object value)
                  throws IOException
Save the given property using an object's string representation. See saveProperty(Object, String) for additional details.

Parameters:
property - the property whose value is being saved
value - the value to save
Throws:
IOException - if there is an error while attempting to write the property to the file

saveProperty

public void saveProperty(T property,
                         String value)
                  throws IOException
Modify the value of the given property and save only that change to permanent storage. This method will not save other properties whose values may have been modified since the file was last loaded or saved. Any modifications that have been made to other properties will still be set, but the file will not reflect those changes until save() or saveNB() is called.

Note that there is no guarantee that the modification and saving will be atomic. In other words, it is possible that this call will modify the value, another call will further change the value, and then the property will be saved.

Parameters:
property - the property whose value is being saved
value - the value to save
Throws:
IOException - if there is an error while attempting to write the property to the file

saveProperty

public void saveProperty(T property)
                  throws IOException
Save the current value of the given property to the file without modifying the values of any other properties in the file. In other words, isModified(Object) will return false for the given property after this call completes, but it will return true for any other properties that have been modified since the last load or save.

This method will block and wait for the property to be saved. See savePropertyNB(Object) for a non-blocking version.

Parameters:
property - the property to save
Throws:
IOException - if there is an error while attempting to write the property to the file

savePropertyNB

public Future<Void> savePropertyNB(T property)
Save the current value of the given property to the file without modifying the values of any other properties in the file. In other words, isModified(Object) will return false for the given property after this call completes, but it will return true for any other properties that have been modified since the last load or save.

This method will not block to wait for the property to be saved. See saveProperty(Object) for a blocking version.

Parameters:
property - the property to save
Returns:
a task representing this save request
Throws:
IOException - if there is an error while attempting to write the property to the file

save

public void save()
          throws IOException
Save the current values of all properties.

This method will block and wait for the properties to be saved. See saveNB() for a non-blocking version.

Throws:
IOException - if there is an error while attempting to save the properties

saveNB

public Future<Void> saveNB()
Save the current values of all properties.

This method will not block to wait for the properties to be saved. See save() for a blocking version.

Returns:
a task representing this save request

resetProperty

public void resetProperty(T property)
Reset the given property to its default value. This will not write the new value to the file system.

Parameters:
property - the property whose value is being reset

reset

public void reset()
Reset the properties to the original defaults.


isModified

public boolean isModified(T property)
Determine whether or not the given property has been modified since it was last load or saved.

Parameters:
property - the property to check
Returns:
true if this property has been modified since the last time it was loaded or saved; false otherwise

isModified

public boolean isModified()
Determine whether or not any property has been modified since the last load or save.

Returns:
true if any property known to this instance has been modified since the last load or save; false otherwise

createRetriever

protected Retriever createRetriever()
Build a new Retriever instance that will be used by the evaluator to request the values of nested property references.

Returns:
a new Retriever

getRetriever

protected Retriever getRetriever()
Get the Retriever instance used internally to fetch values using an Evaluator.

Returns:
the retriever instance
See Also:
createRetriever(), Evaluator


Copyright © 2010-2012 Gregory P. Moyer. All Rights Reserved.