com.Ostermiller.util Java Utilities


com.Ostermiller.util
Class UberProperties

java.lang.Object
  extended by 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 http://ostermiller.org/contact.pl?regarding=Java+Utilities

Constructor Summary
UberProperties()
          Creates an empty property list with no default values.
UberProperties(UberProperties defaults)
          Creates an empty property list with the specified defaults.
 
Method Summary
 void addProperties(String name, String[] values)
          Adds the values to the list of properties with the given name.
 void addProperties(String name, String[] values, String comment)
          Adds the values to the list of properties with the given name.
 void addProperty(String name, String value)
          Adds a value to the list of properties with the given name.
 void addProperty(String name, String value, String comment)
          Adds a value to the list of properties with the given name.
 boolean contains(String name)
          Test to see if a property with the given name exists.
 Boolean getBooleanProperty(String name)
          Liberally parse the property value as a boolean.
 boolean getBooleanProperty(String name, boolean defaultValue)
          Liberally parse the property value as a boolean.
 String getComment()
          Get the comment associated with this set of properties.
 String getComment(String name)
          Get the comment associated with this property.
 Integer getIntegerProperty(String name)
          Liberally parse the property value as an integer.
 int getIntProperty(String name, int defaultValue)
          Liberally parse the property value as an integer.
 String[] getProperties(String name)
          Get the values for a property.
 String[] getProperties(String name, String[] defaultValues)
          Get the values for a property.
 String getProperty(String name)
          Get the first property with the given name.
 String getProperty(String name, 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(InputStream in)
          Add the properties from the input stream to this UberProperties.
 void load(InputStream in, boolean add)
          Add the properties from the input stream to this UberProperties.
 void load(Reader in)
          Add the properties from the reader to this UberProperties.
 void load(Reader reader, boolean add)
          Add the properties from the reader to this UberProperties.
 void load(String[] userFile, String systemResource)
          Load these properties from a user file with default properties from a system resource.
 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(String name)
          Remove any property with the given name.
 void save(OutputStream out)
          Save these properties to the given stream.
 void save(String[] userFile)
          Save these properties from a user file.
 void save(Writer out)
          Save these properties to the given writer.
 void setComment(String comment)
          Set the comment associated with this set of properties.
 void setProperties(String name, String[] values)
          Replaces all properties of the given name with properties with the given values.
 void setProperties(String name, String[] values, String comment)
          Replaces all properties of the given name with properties with the given values.
 void setProperty(String name, String value)
          Replaces all properties of the given name with a single property with the given value.
 void setProperty(String name, String value, String comment)
          Replaces all properties of the given name with a single property with the given value.
 Properties toJavaUtilProperties()
          Convert this UberProperties into a java.util.Properties.
 String toString()
          Save these properties to a string.
 
Methods inherited from class java.lang.Object
equals, 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:
NullPointerException - if defaults is null.
Since:
ostermillerutils 1.00.00
Method Detail

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:
StringHelper.parseInteger(String)

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:
StringHelper.parseInt(String, int)

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:
StringHelper.parseBoolean(String)

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:
StringHelper.parseBoolean(String, boolean)

com.Ostermiller.util Java Utilities


Copyright © 2001-2012 by Stephen Ostermiller