Class JProperties

All Implemented Interfaces:
Serializable, Cloneable, Map<String,String>
Direct Known Subclasses:
LangProperties

public class JProperties extends Hashtable<String,String>
This class, based on Properties manage properties file in UTF-8 encoding. Its save updateAndSave(File) methods keep layout of previous properties file.

Thread-safety: all read methods (getProperty, getXxxProperty, getProperties, getSubProperties...) are lock-free. Write methods are synchronized on this instance.

See Also:
  • Field Details

    • PREFIX_PROPERTIES_CACHE_MAX_ENTRIES

      protected static final int PREFIX_PROPERTIES_CACHE_MAX_ENTRIES
      See Also:
    • prefixPropertiesCache

      protected volatile Map<String,JProperties> prefixPropertiesCache
    • propertyNameAsDefaultValue

      protected boolean propertyNameAsDefaultValue
    • listenerSet

      protected volatile Set<JPropertiesListener> listenerSet
    • SENSITIVE_KEYWORD

      protected Set<String> SENSITIVE_KEYWORD
    • ENCRYPTED_EXTENSION

      protected String ENCRYPTED_EXTENSION
      Suffix identifying a property whose value is encrypted, for example db.password.crypt. When such a key is written, its name without the suffix (db.password) is registered as a protected key. Subclasses may change it.
      See Also:
  • Constructor Details

    • JProperties

      public JProperties()
    • JProperties

      protected JProperties(JProperties jProperties)
      Constructor with a parent JProperties (used only for resolve linked properties when subProperties feature is used.
      Parameters:
      jProperties - parent JProperties object, used for linked property resolution
  • Method Details

    • getListenerSet

      public Set<JPropertiesListener> getListenerSet()
      Retrieve set of all JPropertiesListener use by this JProperties instance.
      Returns:
      the set of all listeners for this JProperties.
      Since:
      public since jcms-10.0.3 - JCMS-6890
      See Also:
    • setListenerSet

      public void setListenerSet(Set<JPropertiesListener> listeners)
      Set the Set of JPropertiesListener that this JProperties instance must used to notify
      Parameters:
      listeners - a Set of JProperties listener to assigne (listener are cleared if null is specified)
      Since:
      jcms-10.0.3 - JCMS-6890
      See Also:
    • addPropertiesListener

      public void addPropertiesListener(JPropertiesListener l)
      Adds a listener for any change of this JProperties.
      Parameters:
      l - the listener to add
      See Also:
    • removePropertiesListener

      public void removePropertiesListener(JPropertiesListener l)
      Removes a listener for any change of this JProperties.
      Parameters:
      l - the listener to remove
      See Also:
    • firePropertiesChange

      public void firePropertiesChange()
      Triggers a properties change to notify all listener of this JProperties.
      See Also:
    • containsProperty

      public boolean containsProperty(String name)
      Tests if this JProperties contains the given property key/name.
      Parameters:
      name - the key/name of the property to check
      Returns:
      true if the specified object is a key in this hashtable; false otherwise.
    • getProperty

      public String getProperty(String name)
      Gets value of a property.
      Parameters:
      name - the key/name of the property to retrieve
      Returns:
      the property value
    • getProperty

      public String getProperty(String name, String defaultValue)
      Gets the value of a property given its key/name.
      Parameters:
      name - the key/name of the property to retrieve
      defaultValue - the default value to use if the existing value is null.
      Returns:
      the value of a property given its key/name.
    • setProperty

      public Object setProperty(String name, String value)
      Sets value of a property.
      Parameters:
      name - the key/name of the property to retrieve
      value - the new value to assign.
      Returns:
      the previous value of the specified key/name
    • getBooleanProperty

      public boolean getBooleanProperty(String name, boolean defaultValue)
      Gets the value of a property as a boolean given its key/name.
      Parameters:
      name - the key/name of the property to retrieve
      defaultValue - the default value to use if the existing value is null or is neither "false" nor "true" (case sensitive).
      Returns:
      the boolean value of the property
    • getIntegerProperty

      public int getIntegerProperty(String name, int defaultValue)
      Gets the value of a property as an int value given its key/name.
      Parameters:
      name - the key/name of the property to retrieve
      defaultValue - the default value to use if the existing value is null or if Integer.parseInt() throws exception during String to int conversion.
      Returns:
      the int value of the property
    • getLongProperty

      public long getLongProperty(String name, long defaultValue)
      Gets the value of a property as a long value given its key/name.
      Parameters:
      name - the key/name of the property to retrieve
      defaultValue - the default value to use if the existing value is null or if Long.parseLong() throws exception during String to long conversion.
      Returns:
      the long value of the property
    • getFloatProperty

      public float getFloatProperty(String name, float defaultValue)
      Gets the value of a property as a float value given its key/name.
      Parameters:
      name - the key/name of the property to retrieve
      defaultValue - the default value to use if the existing value is null or if Float.parseFloat() throws exception during String to float conversion.
      Returns:
      the float value of the property
    • getDoubleProperty

      public double getDoubleProperty(String name, double defaultValue)
      Gets the value of a property as a double value given its key/name.
      Parameters:
      name - the key/name of the property to retrieve
      defaultValue - the default value to use if the existing value is null or if Double.parseDouble() throws exception during String to double conversion.
      Returns:
      the double value of the property
    • getStringArrayProperty

      public String[] getStringArrayProperty(String name, String[] defaultValue)
      Gets the value of a property as a String array.

      The property value must be in one of the following forms:

      • "@{delim}value1{delim}value2...", where {delim} is one character delimiter of your choice.
      • "value1{delim}value2{delim}...", where {delim} is a character from \t\n\r\f.
      For example :
         String[] array = prop.getStringArrayProperty("missingexample", new String[] { "default", "value"});
         assertEquals(2, array.length);
         assertEquals("default", array[0]);
         assertEquals("value", array[1]);
      
         prop.setProperty("example1", "@|abc|def");
         String[] array1 = prop.getStringArrayProperty("example1", new String[] { });
         assertEquals(2, array1.length);
         assertEquals("abc", array1[0]);
         assertEquals("def", array1[1]);
      
         prop.setProperty("example2", "foo bar\tzig");
         String[] array2 = prop.getStringArrayProperty("example2", new String[] { });
         assertEquals(3, array2.length);
         assertEquals("foo", array2[0]);
         assertEquals("bar", array2[1]);
         assertEquals("zig", array2[2]);
       
      Parameters:
      name - the key/name of the property to retrieve
      defaultValue - the default value to use if the existing value is null or no values could be found in the conversion.
      Returns:
      a String array
    • buildArrayFromString

      protected static String[] buildArrayFromString(String value, String[] defaultValue)
      Convert a string to a String[] using the following formats:
      • "@{delim}value1{delim}value2...", where {delim} is one character delimiter of your choice.
      • "value1{delim}value2{delim}...", where {delim} is a character from \t\n\r\f.
      Parameters:
      value - the value
      defaultValue - the default value
      Returns:
      an array of String
    • getIntArrayProperty

      public int[] getIntArrayProperty(String name, int[] defaultValue)
      Gets the value of a property as a int array. Uses same format of getStringArrayProperty(String, String[]).
      Parameters:
      name - the key/name of the property to retrieve
      defaultValue - the default value to use if the existing value is null or no values could be found in the conversion.
      Returns:
      an int array
      See Also:
    • addProperties

      public void addProperties(Properties prop)
      Add every property of the given Properties to this JProperties.
      Parameters:
      prop - the properties to be added
    • addProperties

      public void addProperties(JProperties prop)
      Add every property of the given JProperties to this JProperties.
      Parameters:
      prop - the jproperties to be added
    • checkCacheGetProperties

      protected JProperties checkCacheGetProperties(String prefix)
    • putCacheGetProperties

      protected void putCacheGetProperties(String prefix, JProperties prop)
    • invalidateCacheGetProperties

      public void invalidateCacheGetProperties()
      Invalidate the cache used for getProperties(String) method (and therefore getSubProperties(String)).

      The cache map is replaced by a new empty one rather than cleared: a getProperties(String) call started before the invalidation stores its result, possibly built from the old content, in the discarded map, so it is never served afterwards. The call is cheap (an empty ConcurrentHashMap allocates its table lazily), lock-free and can be made from any thread.

      Since:
      jcms-8.0.2
    • getProperties

      public JProperties getProperties(String prefix)
      Returns a new property set of properties with key matching a given prefix.
      Parameters:
      prefix - the prefix the properties must match to be added to the returned JProperties instance, if null, all properties are added.
      Returns:
      a new property set of properties with key matching a given prefix.
    • getSubProperties

      public Map<String,Object> getSubProperties(String prefix)
      Returns a map of properties built from those properties and having a given prefix.
      Example:
      prop:
      foo.bar.case1.x: value of x for case1
      foo.bar.case1.y: value of y for case1
      foo.bar.case2.x: value of x for case2
      foo.bar.case2.y: value of y for case2
      foo.bar.case2.z.t: value of z for case2

      prop.getSubProperties("foo.bar.") returns a Map with the keys case1 and case2.

      A JProperties is bound to case1 and it contains the properties:
      x: value of x for case1
      y: value of y for case1

      A JProperties is bound to case2 and it contains the properties:
      x: value of x for case2
      y: value of y for case2
      z.t: value of z for case2

      Parameters:
      prefix - the prefix
      Returns:
      a map with string as the key and either String or JProperties as the value.
      Since:
      jcms-5.7.2
    • clearProperties

      public void clearProperties()
      Clear all properties.
    • load

      public void load(File file) throws IOException
      Reads a property file (key and element pairs) from the given File. The file encoding is assumed to be UTF-8.
      Parameters:
      file - the file from which to read properties.
      Throws:
      IOException - if an error occurred when reading from the input stream.
      IllegalArgumentException - if the input stream contains a malformed Unicode escape sequence.
      See Also:
    • load

      public void load(File file, boolean unprotectSensitiveData) throws IOException
      Reads a property file (key and element pairs) from the given File. The file encoding is assumed to be UTF-8.
      Parameters:
      file - the file from which to read properties.
      unprotectSensitiveData - true if sensitive data should be unprotected after read
      Throws:
      IOException - if an error occurred when reading from the input stream.
      IllegalArgumentException - if the input stream contains a malformed Unicode escape sequence.
      See Also:
    • load

      public void load(File file, String prefix) throws IOException
      Reads a property file (key and element pairs) from the given File. The file encoding is assumed to be UTF-8.
      Parameters:
      file - the file from which to read properties.
      prefix - a prefix to use add to all properties' name. if null, no prefix is used.
      Throws:
      IOException - if an error occurred when reading from the input stream.
      IllegalArgumentException - if the input stream contains a malformed Unicode escape sequence.
      See Also:
    • load

      public void load(File file, String prefix, boolean unprotectSensitiveData) throws IOException
      Reads a property file (key and element pairs) from the given File. The file encoding is assumed to be UTF-8.
      Parameters:
      file - the file from which to read properties.
      prefix - a prefix to use add to all properties' name. if null, no prefix is used.
      unprotectSensitiveData - true if sensitive data should be unprotected after read
      Throws:
      IOException - if an error occurred when reading from the input stream.
      IllegalArgumentException - if the input stream contains a malformed Unicode escape sequence.
      See Also:
    • getLoadedFiles

      public Set<File> getLoadedFiles()
      Retrieve a set of all that were loaded in this JProperties instance (ordered by the load order)
      Returns:
      a Set, never returns null
      Since:
      JCMS-6735
    • updateAndSave

      public void updateAndSave(File file) throws IOException
      Updates and save properties. The original layout is preserved for existing properties and comments New properties are appended.
      Parameters:
      file - the properties File to read and update.
      Throws:
      IOException - IOException thrown in method
    • isSensitiveProperty

      public boolean isSensitiveProperty(String key)
      Check if the specified property key is considered to be sensitive and for which values is being concealed or crypted on saved.
      Parameters:
      key - the name of the property being verified
      Returns:
      true if property is sensitive, false otherwise
      Since:
      jcms-10.0.3 / JCMS-7225 (initally introduce as private in jcms-10.0.2 / JCMS-6928)
    • toString

      public String toString()
    • parse

      public static JProperties parse(String str)
    • getProtectedKeySet

      public Set<String> getProtectedKeySet()
      Returns the names of the protected properties, that is properties holding sensitive data whose value must be concealed when displayed or saved (see JProperties.isSensitiveProperty(String)).

      The set is filled automatically: each time a key ending with ENCRYPTED_EXTENSION is written (put, putAll, putIfAbsent, compute, computeIfAbsent, merge), the key without its last dot-separated part is added (db.password.crypt registers db.password). Keys can also be added explicitly with addProtectedKeys(Collection). Removing a property does not remove its protected key.

      The returned set is live and modifiable: changes made to it apply to this instance. It is thread-safe and can be iterated while other threads write, without ConcurrentModificationException. A clone() shares this set with the original (shallow copy).

      Returns:
      the set of protected property names, never null
      See Also:
    • addProtectedKeys

      public void addProtectedKeys(Collection<String> col)
      Registers additional protected property names, for keys that do not follow the ENCRYPTED_EXTENSION convention. The names are added as is (no suffix is removed) to the set returned by getProtectedKeySet().
      Parameters:
      col - the property names to protect; ignored if null
      See Also:
    • size

      public int size()
      Specified by:
      size in interface Map<K,V>
      Overrides:
      size in class Hashtable<K,V>
    • isEmpty

      public boolean isEmpty()
      Specified by:
      isEmpty in interface Map<K,V>
      Overrides:
      isEmpty in class Hashtable<K,V>
    • get

      public String get(Object key)
      Specified by:
      get in interface Map<K,V>
      Overrides:
      get in class Hashtable<K,V>
    • getOrDefault

      public String getOrDefault(Object key, String def)
      Specified by:
      getOrDefault in interface Map<K,V>
      Overrides:
      getOrDefault in class Hashtable<K,V>
    • containsKey

      public boolean containsKey(Object key)
      Specified by:
      containsKey in interface Map<K,V>
      Overrides:
      containsKey in class Hashtable<K,V>
    • containsValue

      public boolean containsValue(Object val)
      Specified by:
      containsValue in interface Map<K,V>
      Overrides:
      containsValue in class Hashtable<K,V>
    • contains

      public boolean contains(Object val)
      Overrides:
      contains in class Hashtable<K,V>
    • keys

      public Enumeration<String> keys()
      Overrides:
      keys in class Hashtable<K,V>
    • elements

      public Enumeration<String> elements()
      Overrides:
      elements in class Hashtable<K,V>
    • forEach

      public void forEach(BiConsumer<? super String,? super String> action)
      Specified by:
      forEach in interface Map<K,V>
      Overrides:
      forEach in class Hashtable<K,V>
    • keySet

      public Set<String> keySet()
      Specified by:
      keySet in interface Map<K,V>
      Overrides:
      keySet in class Hashtable<K,V>
    • values

      public Collection<String> values()
      Specified by:
      values in interface Map<K,V>
      Overrides:
      values in class Hashtable<K,V>
    • entrySet

      public Set<Map.Entry<String,String>> entrySet()
      Specified by:
      entrySet in interface Map<K,V>
      Overrides:
      entrySet in class Hashtable<K,V>
    • put

      public String put(String key, String value)
      Specified by:
      put in interface Map<K,V>
      Overrides:
      put in class Hashtable<K,V>
    • remove

      public String remove(Object key)
      Specified by:
      remove in interface Map<K,V>
      Overrides:
      remove in class Hashtable<K,V>
    • clear

      public void clear()
      Specified by:
      clear in interface Map<K,V>
      Overrides:
      clear in class Hashtable<K,V>
    • putAll

      public void putAll(Map<? extends String,? extends String> m)
      Specified by:
      putAll in interface Map<K,V>
      Overrides:
      putAll in class Hashtable<K,V>
    • putIfAbsent

      public String putIfAbsent(String key, String value)
      Specified by:
      putIfAbsent in interface Map<K,V>
      Overrides:
      putIfAbsent in class Hashtable<K,V>
    • remove

      public boolean remove(Object key, Object value)
      Specified by:
      remove in interface Map<K,V>
      Overrides:
      remove in class Hashtable<K,V>
    • replace

      public boolean replace(String key, String oldValue, String newValue)
      Specified by:
      replace in interface Map<K,V>
      Overrides:
      replace in class Hashtable<K,V>
    • replace

      public String replace(String key, String value)
      Specified by:
      replace in interface Map<K,V>
      Overrides:
      replace in class Hashtable<K,V>
    • replaceAll

      public void replaceAll(BiFunction<? super String,? super String,? extends String> function)
      Specified by:
      replaceAll in interface Map<K,V>
      Overrides:
      replaceAll in class Hashtable<K,V>
    • computeIfAbsent

      public String computeIfAbsent(String key, Function<? super String,? extends String> function)
      Specified by:
      computeIfAbsent in interface Map<K,V>
      Overrides:
      computeIfAbsent in class Hashtable<K,V>
    • computeIfPresent

      public String computeIfPresent(String key, BiFunction<? super String,? super String,? extends String> function)
      Specified by:
      computeIfPresent in interface Map<K,V>
      Overrides:
      computeIfPresent in class Hashtable<K,V>
    • compute

      public String compute(String key, BiFunction<? super String,? super String,? extends String> function)
      Specified by:
      compute in interface Map<K,V>
      Overrides:
      compute in class Hashtable<K,V>
    • merge

      public String merge(String key, String value, BiFunction<? super String,? super String,? extends String> function)
      Specified by:
      merge in interface Map<K,V>
      Overrides:
      merge in class Hashtable<K,V>
    • equals

      public boolean equals(Object o)
      Specified by:
      equals in interface Map<K,V>
      Overrides:
      equals in class Hashtable<K,V>
    • hashCode

      public int hashCode()
      Specified by:
      hashCode in interface Map<K,V>
      Overrides:
      hashCode in class Hashtable<K,V>
    • clone

      public Object clone()
      Overrides:
      clone in class Hashtable<K,V>