org.syphr.prom
Class PropertiesManager<T extends Enum<T>>

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

public class PropertiesManager<T extends Enum<T>>
extends Object

This class creates a management API for a Properties file whose keys are described by an Enum.

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).
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.
<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).
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.
 int getIntegerProperty(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.
 ManagedProperty<T> getManagedProperty(T property)
          Get an object that will encapsulate the functionality of this manager specific to a single property.
 Properties getProperties()
          Retrieve a Properties instance that contains the properties managed by this instance.

Please note that the returned Properties instance 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.

This method will block and wait for the properties to be loaded if they have not been already.
 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 Enum instances and property names (keys).
 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 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.
 Reference referenceAt(T property, int position)
          Determine whether or not a reference to another property exists in the value of the given property at the given position.
 void reload()
          Reload the current values of all properties.

This method will block and wait for the properties to be loaded.
 Future<Void> reloadNB()
          Reload the current values of all properties.

This method will not block to wait for the properties to be loaded.
 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.
<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 all properties to permanent storage.

This method will block and wait for the properties to be loaded if they have not been already.
 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 Enum names and property keys
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

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

getManagedProperty

public ManagedProperty<T> getManagedProperty(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 Enum instances and property names (keys).

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 instance that contains the properties managed by this instance.

Please note that the returned Properties instance 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

keySet

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

An example of where this set would not have the same contents as the set of Enums 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.

This method will block and wait for the properties to be loaded if they have not been already. See reload().

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
See Also:
getProperty(Enum)

getIntegerProperty

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

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
See Also:
getProperty(Enum)

getLongProperty

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

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
See Also:
getProperty(Enum)

getFloatProperty

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

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
See Also:
getProperty(Enum)

getDoubleProperty

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

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
See Also:
getProperty(Enum)

getEnumProperty

public <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). This allows for a 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
See Also:
getProperty(Enum)

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.

This method will block and wait for the properties to be loaded if they have not been already. See reload().

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)

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)
Determine whether or not a reference to another property exists in the value of the given property at the given position. If such a reference does exist, return it.

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

reload

public void reload()
            throws PropertyException
Reload the current values of all properties.

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

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

reloadNB

public Future<Void> reloadNB()
Reload the current values of all properties.

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

Returns:
a task representing this load request

setProperty

public <E extends Enum<E>> void setProperty(T property,
                                            E value)
                 throws PropertyException
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(Enum, 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:
PropertyException - if the properties file has not yet been loaded and an error occurs while trying to do so
See Also:
saveProperty(Enum, Enum)

setProperty

public void setProperty(T property,
                        Object value)
                 throws PropertyException
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:
PropertyException - if the properties file has not yet been loaded and an error occurs while trying to do so
See Also:
saveProperty(Enum, Object)

setProperty

public void setProperty(T property,
                        String value)
                 throws PropertyException
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:
PropertyException - if the properties file has not yet been loaded and an error occurs while trying to do so
See Also:
saveProperty(Enum, String)

saveProperty

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

Please note that the Enum value saved here is case insensitive. See getEnumProperty(Enum, 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:
PropertyException - if there is an error while attempting to load and/or save the properties

saveProperty

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

Parameters:
property - the property whose value is being saved
value - the value to save
Throws:
PropertyException - if there is an error while attempting to load and/or save the properties

saveProperty

public void saveProperty(T property,
                         String value)
                  throws PropertyException
Modify the value of the given property and save all properties to permanent storage.

This method will block and wait for the properties to be loaded if they have not been already. See reload().

Parameters:
property - the property whose value is being saved
value - the value to save
Throws:
PropertyException - if there is an error while attempting to load and/or save the properties

save

public void save()
          throws PropertyException
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:
PropertyException - 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)
                   throws PropertyException
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
Throws:
PropertyException - if the properties file has not yet been loaded and an error occurs while trying to do so

reset

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


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 syphr.org. All Rights Reserved.