Package com.Ostermiller.util

Class UberProperties

java.lang.Object
com.Ostermiller.util.UberProperties
public class UberProperties extends Object
The Properties class represents a persistent set of properties. The Properties can be saved to a stream or loaded from a stream. Each key and its corresponding value in the property list is a string. More information about this class is available from ostermiller.org.

A property list can contain another property list as its "defaults"; this second property list is searched if the property key is not found in the original property list.

When saving properties to a stream or loading them from a stream, the ISO 8859-1 character encoding is used. For characters that cannot be directly represented in this encoding, Unicode escapes are used; however, only a single 'u' character is allowed in an escape sequence. The native2ascii tool can be used to convert property files to and from other character encodings.

Unlike the java.util.Properties, UberProperties does not inherit from java.util.Hashtable, so Objects other than strings cannot be stored in it. Also, comments from a files are preserved, and there can be several properties for a given name.

This class is not synchronized, so it should not be used in a multi-threaded environment without external synchronization.

The file format that UberProperties uses is as follows:

The file is assumed to be using the ISO 8859-1 character encoding. All of the comment lines (starting with a '#' or '!') at the beginning of the file before the first line that is not a comment, are the comment associated with the file. After that, each comment will be associated with the next property. If there is more than one property with the same name, the first comment will be the only one that is loaded.

Every property occupies one line of the input stream. Each line is terminated by a line terminator (\n or \r or \r\n).

A line that contains only whitespace or whose first non-whitespace character is an ASCII # or ! is ignored (thus, # or ! indicate comment lines).

Every line other than a blank line or a comment line describes one property to be added to the table (except that if a line ends with \, then the following line, if it exists, is treated as a continuation line, as described below). The key consists of all the characters in the line starting with the first non-whitespace character and up to, but not including, the first ASCII =, :, or whitespace character. All of the key termination characters may be included in the key by preceding them with a \. Any whitespace after the key is skipped; if the first non-whitespace character after the key is = or :, then it is ignored and any whitespace characters after it are also skipped. All remaining characters on the line become part of the associated element string. Within the element string, the ASCII escape sequences \t, \n, \r, \\, \", \', \ (a backslash and a space), and \\uxxxx are recognized and converted to single characters. Moreover, if the last character on the line is \, then the next line is treated as a continuation of the current line; the \ and line terminator are simply discarded, and any leading whitespace characters on the continuation line are also discarded and are not part of the element string.

As an example, each of the following four lines specifies the key "Truth" and the associated element value "Beauty":

Truth = Beauty
           Truth:Beauty
   Truth                        :Beauty

As another example, the following three lines specify a single property:

fruits                          apple, banana, pear, \
                                cantaloupe, watermelon, \
                                kiwi, mango

The key is "fruits" and the associated element is:
"apple, banana, pear, cantaloupe, watermelon, kiwi, mango"
Note that a space appears before each \ so that a space will appear after each comma in the final result; the \, line terminator, and leading whitespace on the continuation line are merely discarded and are not replaced by one or more other characters.

As a third example, the line:
cheeses
specifies that the key is "cheeses" and the associated element is the empty string.

Since:
ostermillerutils 1.00.00
Author:
Stephen Ostermiller https://ostermiller.org/contact.pl?regarding=Java+Utilities

  • Constructor Details

    • UberProperties

      public UberProperties()
      Creates an empty property list with no default values.
      Since:
      ostermillerutils 1.00.00

    • UberProperties

      public UberProperties(UberProperties defaults)
      Creates an empty property list with the specified defaults.
      Parameters:
      defaults - the defaults.
      Throws:
      NullPointerException - if defaults is null.
      Since:
      ostermillerutils 1.00.00

  • Method Details

    • contains

      public boolean contains(String name)
      Test to see if a property with the given name exists.
      Parameters:
      name - the name of the property.
      Returns:
      true if the property existed and was removed, false if it did not exist.
      Throws:
      NullPointerException - if name is null.
      Since:
      ostermillerutils 1.00.00

    • remove

      public boolean remove(String name)
      Remove any property with the given name.
      Parameters:
      name - the name of the property.
      Returns:
      true if the property existed and was removed, false if it did not exist.
      Throws:
      NullPointerException - if name is null.
      Since:
      ostermillerutils 1.00.00

    • setProperty

      public void setProperty(String name, String value)
      Replaces all properties of the given name with a single property with the given value.
      Parameters:
      name - the name of the property.
      value - the value of the property, or null to remove it.
      Throws:
      NullPointerException - if name is null.
      Since:
      ostermillerutils 1.00.00

    • setProperties

      public void setProperties(String name, String[] values)
      Replaces all properties of the given name with properties with the given values.
      Parameters:
      name - the name of the property.
      values - for the property.
      Throws:
      NullPointerException - if name is null.
      NullPointerException - if values is null.
      IllegalArgumentException - if values is empty.
      Since:
      ostermillerutils 1.00.00

    • setProperty

      public void setProperty(String name, String value, String comment)
      Replaces all properties of the given name with a single property with the given value.
      Parameters:
      name - the name of the property.
      value - the value of the property or null to remove it.
      comment - the comment for the property, or null to remove it.
      Throws:
      NullPointerException - if name is null.
      NullPointerException - if comment is null.
      Since:
      ostermillerutils 1.00.00

    • setProperties

      public void setProperties(String name, String[] values, String comment)
      Replaces all properties of the given name with properties with the given values.
      Parameters:
      name - the name of the property.
      values - value of the property.
      comment - the comment for the property, or null to remove it.
      Throws:
      NullPointerException - if name is null.
      NullPointerException - if values is null.
      IllegalArgumentException - if values is empty.
      Since:
      ostermillerutils 1.00.00

    • addProperty

      public void addProperty(String name, String value, String comment)
      Adds a value to the list of properties with the given name.
      Parameters:
      name - the name of the property.
      value - the values for the property, or null to remove.
      comment - the comment for the property, or null to remove it.
      Throws:
      NullPointerException - if name is null.
      NullPointerException - if value is null.
      Since:
      ostermillerutils 1.00.00

    • addProperties

      public void addProperties(String name, String[] values, String comment)
      Adds the values to the list of properties with the given name.
      Parameters:
      name - the name of the property.
      values - the values for the property.
      comment - the comment for the property, or null to remove it.
      Throws:
      NullPointerException - if name is null.
      NullPointerException - if values is null.
      Since:
      ostermillerutils 1.00.00

    • addProperty

      public void addProperty(String name, String value)
      Adds a value to the list of properties with the given name.
      Parameters:
      name - the name of the property.
      value - the values for the property.
      Throws:
      NullPointerException - if name is null.
      NullPointerException - if value is null.
      Since:
      ostermillerutils 1.00.00

    • addProperties

      public void addProperties(String name, String[] values)
      Adds the values to the list of properties with the given name.
      Parameters:
      name - the name of the property.
      values - the values for the property.
      Throws:
      NullPointerException - if name is null.
      NullPointerException - if values is null.
      Since:
      ostermillerutils 1.00.00

    • load

      public void load(String[] userFile, String systemResource) throws IOException
      Load these properties from a user file with default properties from a system resource.

      Example: 

      load(
     new String(){".java","tld","company","package","component.properties"}
     "tld/company/package/component.properties",
 )
      This will load the properties file relative to the classpath as the defaults and the file <%userhome%>/.java/tld/company/package/component.properties if the file exists. The .java directory is recommended as it is a common, possibly hidden, directory in the users home directory commonly used by Java programs. This method is meant to be used with the save(String systemResource) method which will save modified properties back to the user directory.
      Parameters:
      userFile - array of Strings representing a path and file name relative to the user home directory.
      systemResource - name relative to classpath of default properties, or null to ignore.
      Throws:
      IOException - if an error occurs when reading.
      NullPointerException - if userFile is null.
      IllegalArgumentException - if userFile is empty.
      Since:
      ostermillerutils 1.00.00

    • load

      public void load(InputStream in, boolean add) throws IOException
      Add the properties from the input stream to this UberProperties.

      The input stream in parsed as ISO-8859-1 (Latin 1) text.

      Parameters:
      in - InputStream containing properties.
      add - whether parameters should add to parameters with the same name or replace them.
      Throws:
      IOException - if an error occurs when reading.
      Since:
      ostermillerutils 1.00.00

    • load

      public void load(Reader reader, boolean add) throws IOException
      Add the properties from the reader to this UberProperties.
      Parameters:
      reader - Reader containing properties.
      add - whether parameters should add to parameters with the same name or replace them.
      Throws:
      IOException - if an error occurs when reading.
      Since:
      ostermillerutils 1.07.01

    • load

      public void load(InputStream in) throws IOException
      Add the properties from the input stream to this UberProperties.

      The input stream in parsed as ISO-8859-1 (Latin 1) text.

      Properties that are found replace any properties that were there before.

      Parameters:
      in - InputStream containing properties.
      Throws:
      IOException - if an error occurs when reading.
      Since:
      ostermillerutils 1.00.00

    • load

      public void load(Reader in) throws IOException
      Add the properties from the reader to this UberProperties.

      Properties that are found replace any properties that were there before.

      Parameters:
      in - Reader containing properties.
      Throws:
      IOException - if an error occurs when reading.
      Since:
      ostermillerutils 1.00.00

    • save

      public void save(String[] userFile) throws IOException
      Save these properties from a user file.

      Example: 

      save(
     new String(){"tld","company","package","component.properties"}
 )
      This will save the properties file relative to the user directory: <%userhome%>/tld/company/package/component.properties Directories will be created as needed.
      Parameters:
      userFile - array of Strings representing a path and file name relative to the user home directory.
      Throws:
      IOException - if an error occurs when reading.
      NullPointerException - if userFile is null.
      IllegalArgumentException - if userFile is empty.
      Since:
      ostermillerutils 1.00.00

    • save

      public void save(Writer out) throws IOException
      Save these properties to the given writer. The properties are saved without escaping high byte characters with backslash u style escape sequences. This method is intended for those who wish to store properties in UTF-8 (or other high byte capable) text file. When saved via this method, the properties can only be read back using the read(Reader) method, as the read(InputStream) and read(File) methods assume ISO-8859-1 encoded bytes.

      Note that this method in NOT compatible with the java.util.Properties class. This method will store unicode characters un-escaped.

      Parameters:
      out - writer
      Throws:
      IOException - if an input/output error occurs
      Since:
      ostermillerutils 1.07.01

    • save

      public void save(OutputStream out) throws IOException
      Save these properties to the given stream.
      Parameters:
      out - OutputStream to which these properties should be written.
      Throws:
      IOException - if an error occurs when writing.
      Since:
      ostermillerutils 1.00.00

    • getProperty

      public String getProperty(String name)
      Get the first property with the given name. If the property is not specified in this UberProperties but it is in the default UberProperties, the default is used. If no default is found, null is returned.
      Parameters:
      name - Parameter name
      Returns:
      the first value of this property, or null if the property does not exist.
      Since:
      ostermillerutils 1.00.00

    • getProperty

      public String getProperty(String name, String defaultValue)
      Get the first property with the given name. If the property is not specified in this UberProperties but it is in the default UberProperties, the default UberProperties is consulted, otherwise, the supplied default is used.
      Parameters:
      name - Parameter name
      defaultValue - Value to use when property not present
      Returns:
      the first value of this property.
      Since:
      ostermillerutils 1.00.00

    • getProperties

      public String[] getProperties(String name)
      Get the values for a property. Properties returned in the same order in which they were added.

      If the property is not specified in this UberProperties but it is in the default UberProperties, the default is used. If no default is found, null is returned.

      Parameters:
      name - Parameter name
      Returns:
      all the values associated with the given key, or null if the property does not exist.
      Since:
      ostermillerutils 1.00.00

    • toJavaUtilProperties

      public Properties toJavaUtilProperties()
      Convert this UberProperties into a java.util.Properties.
      Returns:
      java properties object.
      Since:
      ostermillerutils 1.07.01

    • getProperties

      public String[] getProperties(String name, String[] defaultValues)
      Get the values for a property. Properties returned in the same order in which they were added.

      If the property is not specified in this UberProperties but it is in the default UberProperties, the default UberProperties is consulted, otherwise, the supplied defaults are used.

      Parameters:
      name - Parameter name
      defaultValues - Values to use when property not present
      Returns:
      all the values associated with the given key, or null if the property does not exist.
      Since:
      ostermillerutils 1.00.00

    • getComment

      public String getComment(String name)
      Get the comment associated with this property.

      If the property is not specified in this UberProperties but it is in the default UberProperties, the default is used. If no default is found, null is returned.

      Parameters:
      name - Parameter name
      Returns:
      the comment for this property, or null if there is no comment or the property does not exist.
      Since:
      ostermillerutils 1.00.00

    • propertyNames

      public String[] propertyNames()
      Returns an enumeration of all the keys in this property list, including distinct keys in the default property list if a key of the same name has not already been found from the main properties list.
      Returns:
      an enumeration of all the keys in this property list, including the keys in the default property list.
      Since:
      ostermillerutils 1.00.00

    • setComment

      public void setComment(String comment)
      Set the comment associated with this set of properties.
      Parameters:
      comment - the comment for entire set of properties, or null to clear.
      Since:
      ostermillerutils 1.00.00

    • getComment

      public String getComment()
      Get the comment associated with this set of properties.
      Returns:
      comment for entire set of properties, or null if there is no comment.
      Since:
      ostermillerutils 1.00.00

    • getPropertyNameCount

      public int getPropertyNameCount()
      Get the number of unique names for properties stored in this UberProperties.
      Returns:
      number of names.
      Since:
      ostermillerutils 1.00.00

    • toString

      public String toString()
      Save these properties to a string.
      Overrides:
      toString in class Object
      Returns:
      Serialized String version of these properties.
      Since:
      ostermillerutils 1.02.23

    • getIntegerProperty

      public Integer getIntegerProperty(String name)
      Liberally parse the property value as an integer. Uses StringHelper.parseInteger() to parse the integer.
      Parameters:
      name - the property name
      Returns:
      the parsed property value, or null if the property does not exist or cannot be parsed.
      Since:
      ostermillerutils 1.07.01
      See Also:

    • getIntProperty

      public int getIntProperty(String name, int defaultValue)
      Liberally parse the property value as an integer. Uses StringHelper.parseInt() to parse the integer.
      Parameters:
      name - the property name
      defaultValue - default value to be return in case of error
      Returns:
      the parsed property value, or the default if the property does not exist or cannot be parsed.
      Since:
      ostermillerutils 1.07.01
      See Also:

    • getBooleanProperty

      public Boolean getBooleanProperty(String name)
      Liberally parse the property value as a boolean. Uses StringHelper.parseBoolean() to parse the boolean.
      Parameters:
      name - the property name
      Returns:
      the parsed property value, or null if the property does not exist or cannot be parsed.
      Since:
      ostermillerutils 1.07.01
      See Also:

    • getBooleanProperty

      public boolean getBooleanProperty(String name, boolean defaultValue)
      Liberally parse the property value as a boolean. Uses StringHelper.parseBoolean() to parse the boolean.
      Parameters:
      name - the property name
      defaultValue - default value to be return in case of error
      Returns:
      the parsed property value, or the default if the property does not exist or cannot be parsed.
      Since:
      ostermillerutils 1.07.01
      See Also: