21.6 The Class java.util.Properties

A Properties table is a kind of Hashtable with two functionality extensions and with the restriction that keys and elements must be strings. First, there are methods for reading entries into the table from an input stream and writing all the entries in the table to an output stream. Second, a Properties table may refer to another Properties table that provides default values. The getProperty method is much like the get method (§21.4.3), but if an entry is not found in this table, then the defaults table is searched (and that defaults table may itself refer to another defaults table, and so on, recursively).

public class Properties extends Hashtable {
    protected Properties defaults;
    public Properties();
    public Properties(Properties defaults);
    public String getProperty(String key);
    public String getProperty(String key, String defaultValue);
    public Enumeration propertyNames();
    public void load(InputStream in) throws IOException;
    public void save(OutputStream out, String header);
    public void list(PrintStream out);
}

21.6.1 protected Properties defaults;

If the defaults field is not null, it is another Properties table that provides default values for this Properties table.

21.6.2 public Properties()

This constructor initializes a newly created Properties table so that it has no defaults table. Initially, there are no entries in the newly created table.

21.6.3 public Properties(Properties defaults)

This constructor initializes a newly created Properties table so its defaults table is defaults. The argument defaults may be null, in which case the newly created Properties table will not have a defaults table. Initially, there are no entries in the newly created table.

21.6.4 public String getProperty(String key)

If there is an entry in this Properties table with key as its key, the associated element is returned. Otherwise, if this Properties table has a defaults table, then whatever its getProperty method returns is returned. Otherwise, null is returned.

21.6.5 public String getProperty(String key, String defaultValue)

If there is an entry in this Properties table with key as its key, the associated element is returned. Otherwise, if this Properties table has a defaults table, then whatever its getProperty method returns is returned. Otherwise, defaultValue is returned.

21.6.6 public Enumeration propertyNames()

An Enumeration(§21.1) is returned that will generate all the keys for which this Properties table could supply an associated element. If this Properties table has a defaults table (§21.6.1), then keys for which the defaults table has entries are also supplied by the Enumeration, and so on, recursively; but no key is supplied by the Enumeration more than once.

21.6.7 public void load(InputStream in) throws IOException

Properties (key and element pairs) are read from the input stream:

Runtime.getRuntime().getLocalizedInputStream(in)

and added to this Properties table. See the getLocalizedInputStream method of Runtime(§20.16.15).

Every property occupies one line of the input stream. Each line is terminated by a line terminator (\n or \r or \r\n). Lines from the input stream are processed until end of file is reached on the input stream.

A line that contains only whitespace (§20.5.19) 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 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. 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 (but not the key), 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
Truth           :Beauty

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

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

The key is "fruit" 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.

21.6.8 public void save(OutputStream out, String header)

All the properties (key and element pairs) in this Properties table are written to the output stream:

Runtime.getRuntime().getLocalizedOutputStream(out)

in a format suitable for loading into a Properties table using the load method (§21.6.7). See the getLocalizedOutputStream method of Runtime(§20.16.16).

Properties from the defaults table of this Properties table (if any) are not written out by this method.

If the header argument is not null, then an ASCII # character, the header string, and a newline are first written to the output stream. Thus, the header can serve as an identifying comment.

Next, a comment line is always written, consisting of an ASCII # character, the current date and time (as if produced by the toString method of Date(§21.3.7) for the current time), and a newline.

Then every entry in this Properties table is written out, one per line. For each entry the key string is written, then an ASCII =, then the associated element string. Each character of the element string is examined to see whether it should be rendered as an escape sequence. The ASCII characters \, tab, newline, and carriage return are written as \\, \t, \n, and \r, respectively. Characters less than \u0020 and characters greater than \u007E (if necessary, depending on the needs of the localized output stream) are written as \uxxxx for the appropriate hexadecimal value xxxx. Leading space characters, but not embedded or trailing space characters, are written with a preceding \.

21.6.9 public void list(PrintStream out)

Properties (key and element pairs) in this Properties table are written to the output stream out in a possibly abbreviated form that may be more convenient for use in debugging than the output of the save method. No header is written, and element values longer than 40 character are truncated to the first 37 characters, to which the characters "..." are appended. Thus, if the names of the keys are not too long, there is a fighting chance that each property will fit into the space of one line of a physical output device.