Java Doc for UberProperties.java in  » Template-Engine » ostermillerutils » com » Ostermiller » util » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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.

If the property is not specified in this UberProperties but it is in the default UberProperties, the default is used.

If the property is not specified in this UberProperties but it is in the default UberProperties, the default is used.

Example:

load(
 new String(){".java","tld","company","package","component.properties"}
 "tld/company/package/component.properties",
 )

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 the comment for this property, or null if there is no comment or the property does not exist.
since:
   ostermillerutils 1.00.00

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 all the values associated with the given key, or null if the property does not exist.
since:
   ostermillerutils 1.00.00

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
Parameters:
  defaultValues - Values to use when property not present all the values associated with the given key, or null if the property does not exist.
since:
   ostermillerutils 1.00.00

Example:

load(
 new String(){".java","tld","company","package","component.properties"}
 "tld/company/package/component.properties",
 )

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

Example:

save(
 new String(){"tld","company","package","component.properties"}
 )