java.util.Properties
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 classProperties
extends Hashtable { protected Propertiesdefaults
; publicProperties
(); publicProperties
(Properties defaults); public StringgetProperty
(String key); public StringgetProperty
(String key, String defaultValue); public EnumerationpropertyNames
(); public voidload
(InputStream in) throws IOException; public voidsave
(OutputStream out, String header); public voidlist
(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 \u
xxxx 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 :BeautyAs another example, the following three lines specify a single property:
fruits apple, banana, pear, \ cantaloupe, watermelon, \ kiwi, mangoThe 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.
cheesesspecifies 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 \u
xxxx 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.
Contents | Prev | Next | Index
Java Language Specification (HTML generated by Suzette Pelouch on February 24, 1998)
Copyright © 1996 Sun Microsystems, Inc.
All rights reserved
Please send any comments or corrections to doug.kramer@sun.com