UberProperties

java.lang.Object
- com.Ostermiller.util.UberProperties

```
public class UberProperties
extends java.lang.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

Constructor Summary

Constructors
Constructor and Description
`UberProperties()` Creates an empty property list with no default values.
`UberProperties(UberProperties defaults)` Creates an empty property list with the specified defaults.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addProperties(java.lang.String name, java.lang.String[] values)` Adds the values to the list of properties with the given name.
`void`	`addProperties(java.lang.String name, java.lang.String[] values, java.lang.String comment)` Adds the values to the list of properties with the given name.
`void`	`addProperty(java.lang.String name, java.lang.String value)` Adds a value to the list of properties with the given name.
`void`	`addProperty(java.lang.String name, java.lang.String value, java.lang.String comment)` Adds a value to the list of properties with the given name.
`boolean`	`contains(java.lang.String name)` Test to see if a property with the given name exists.
`java.lang.String`	`getComment()` Get the comment associated with this set of properties.
`java.lang.String`	`getComment(java.lang.String name)` Get the comment associated with this property.
`java.lang.String[]`	`getProperties(java.lang.String name)` Get the values for a property.
`java.lang.String[]`	`getProperties(java.lang.String name, java.lang.String[] defaultValues)` Get the values for a property.
`java.lang.String`	`getProperty(java.lang.String name)` Get the first property with the given name.
`java.lang.String`	`getProperty(java.lang.String name, java.lang.String defaultValue)` Get the first property with the given name.
`int`	`getPropertyNameCount()` Get the number of unique names for properties stored in this UberProperties.
`void`	`load(java.io.InputStream in)` Add the properties from the input stream to this UberProperties.
`void`	`load(java.io.InputStream in, boolean add)` Add the properties from the input stream to this UberProperties.
`void`	`load(java.lang.String[] userFile, java.lang.String systemResource)` Load these properties from a user file with default properties from a system resource.
`java.lang.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.
`boolean`	`remove(java.lang.String name)` Remove any property with the given name.
`void`	`save(java.io.OutputStream out)` Save these properties to the given stream.
`void`	`save(java.lang.String[] userFile)` Save these properties from a user file.
`void`	`setComment(java.lang.String comment)` Set the comment associated with this set of properties.
`void`	`setProperties(java.lang.String name, java.lang.String[] values)` Replaces all properties of the given name with properties with the given values.
`void`	`setProperties(java.lang.String name, java.lang.String[] values, java.lang.String comment)` Replaces all properties of the given name with properties with the given values.
`void`	`setProperty(java.lang.String name, java.lang.String value)` Replaces all properties of the given name with a single property with the given value.
`void`	`setProperty(java.lang.String name, java.lang.String value, java.lang.String comment)` Replaces all properties of the given name with a single property with the given value.
`java.lang.String`	`toString()` Save these properties to a string.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - 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:
    
    java.lang.NullPointerException - if defaults is null.
    
    Since:
    
    ostermillerutils 1.00.00
- Method Detail
  - contains
```
public boolean contains(java.lang.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:
    
    java.lang.NullPointerException - if name is null.
    
    Since:
    
    ostermillerutils 1.00.00
  - remove
```
public boolean remove(java.lang.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:
    
    java.lang.NullPointerException - if name is null.
    
    Since:
    
    ostermillerutils 1.00.00
  - setProperty
```
public void setProperty(java.lang.String name,
                        java.lang.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:
    
    java.lang.NullPointerException - if name is null.
    
    Since:
    
    ostermillerutils 1.00.00
  - setProperties
```
public void setProperties(java.lang.String name,
                          java.lang.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:
    
    java.lang.NullPointerException - if name is null.
    
    java.lang.NullPointerException - if values is null.
    
    java.lang.IllegalArgumentException - if values is empty.
    
    Since:
    
    ostermillerutils 1.00.00
  - setProperty
```
public void setProperty(java.lang.String name,
                        java.lang.String value,
                        java.lang.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:
    
    java.lang.NullPointerException - if name is null.
    
    java.lang.NullPointerException - if comment is null.
    
    Since:
    
    ostermillerutils 1.00.00
  - setProperties
```
public void setProperties(java.lang.String name,
                          java.lang.String[] values,
                          java.lang.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:
    
    java.lang.NullPointerException - if name is null.
    
    java.lang.NullPointerException - if values is null.
    
    java.lang.IllegalArgumentException - if values is empty.
    
    Since:
    
    ostermillerutils 1.00.00
  - addProperty
```
public void addProperty(java.lang.String name,
                        java.lang.String value,
                        java.lang.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:
    
    java.lang.NullPointerException - if name is null.
    
    java.lang.NullPointerException - if value is null.
    
    Since:
    
    ostermillerutils 1.00.00
  - addProperties
```
public void addProperties(java.lang.String name,
                          java.lang.String[] values,
                          java.lang.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:
    
    java.lang.NullPointerException - if name is null.
    
    java.lang.NullPointerException - if values is null.
    
    Since:
    
    ostermillerutils 1.00.00
  - addProperty
```
public void addProperty(java.lang.String name,
                        java.lang.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:
    
    java.lang.NullPointerException - if name is null.
    
    java.lang.NullPointerException - if value is null.
    
    Since:
    
    ostermillerutils 1.00.00
  - addProperties
```
public void addProperties(java.lang.String name,
                          java.lang.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:
    
    java.lang.NullPointerException - if name is null.
    
    java.lang.NullPointerException - if values is null.
    
    Since:
    
    ostermillerutils 1.00.00
  - load
```
public void load(java.lang.String[] userFile,
                 java.lang.String systemResource)
          throws java.io.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:
    
    java.io.IOException - if an error occurs when reading.
    
    java.lang.NullPointerException - if userFile is null.
    
    java.lang.IllegalArgumentException - if userFile is empty.
    
    Since:
    
    ostermillerutils 1.00.00
  - load
```
public void load(java.io.InputStream in,
                 boolean add)
          throws java.io.IOException
```
    Add the properties from the input stream to this UberProperties.
    
    Parameters:
    
    in - InputStream containing properties.
    
    add - whether parameters should add to parameters with the same name or replace them.
    
    Throws:
    
    java.io.IOException - if an error occurs when reading.
    
    Since:
    
    ostermillerutils 1.00.00
  - load
```
public void load(java.io.InputStream in)
          throws java.io.IOException
```
    Add the properties from the input stream to this UberProperties.
    Properties that are found replace any properties that were there before.
    
    Parameters:
    
    in - InputStream containing properties.
    
    Throws:
    
    java.io.IOException - if an error occurs when reading.
    
    Since:
    
    ostermillerutils 1.00.00
  - save
```
public void save(java.lang.String[] userFile)
          throws java.io.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:
    
    java.io.IOException - if an error occurs when reading.
    
    java.lang.NullPointerException - if userFile is null.
    
    java.lang.IllegalArgumentException - if userFile is empty.
    
    Since:
    
    ostermillerutils 1.00.00
  - save
```
public void save(java.io.OutputStream out)
          throws java.io.IOException
```
    Save these properties to the given stream.
    
    Parameters:
    
    out - OutputStream to which these properties should be written.
    
    Throws:
    
    java.io.IOException - if an error occurs when writing.
    
    Since:
    
    ostermillerutils 1.00.00
  - getProperty
```
public java.lang.String getProperty(java.lang.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 java.lang.String getProperty(java.lang.String name,
                                    java.lang.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 java.lang.String[] getProperties(java.lang.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
  - getProperties
```
public java.lang.String[] getProperties(java.lang.String name,
                                        java.lang.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 java.lang.String getComment(java.lang.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 java.lang.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(java.lang.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 java.lang.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 java.lang.String toString()
```
    Save these properties to a string.
    
    Overrides:
    
    toString in class java.lang.Object
    
    Returns:
    
    Serialized String version of these properties.
    
    Since:
    
    ostermillerutils 1.02.23

com.Ostermiller.util Java Utilities

Class UberProperties

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

UberProperties

UberProperties

Method Detail

contains

remove

setProperty

setProperties

setProperty

setProperties

addProperty

addProperties

addProperty

addProperties

load

load

load

save

save

getProperty

getProperty

getProperties

getProperties

getComment

propertyNames

setComment

getComment

getPropertyNameCount

toString

com.Ostermiller.util Java Utilities