java.util

Class Properties

Implemented Interfaces:
Cloneable, Map<K,V>, Serializable
Known Direct Subclasses:
Provider

public class Properties
extends Hashtable<K,V>

A set of persistent properties, which can be saved or loaded from a stream. A property list may also contain defaults, searched if the main list does not contain a property for a given key. An example of a properties file for the german language is given here. This extends the example given in ListResourceBundle. Create a file MyResource_de.properties with the following contents and put it in the CLASSPATH. (The character \u00e4 is the german umlaut)
s1=3
s2=MeineDisk
s3=3. M\u00e4rz 96
s4=Die Diskette ''{1}'' enth\u00e4lt {0} in {2}.
s5=0
s6=keine Dateien
s7=1
s8=eine Datei
s9=2
s10={0,number} Dateien
s11=Das Formatieren schlug fehl mit folgender Exception: {0}
s12=FEHLER
s13=Ergebnis
s14=Dialog
s15=Auswahlkriterium
s16=1,3

Although this is a sub class of a hash table, you should never insert anything other than strings to this property, or several methods, that need string keys and values, will fail. To ensure this, you should use the get/setProperty method instead of get/put. Properties are saved in ISO 8859-1 encoding, using Unicode escapes with a single u for any character which cannot be represented.

See Also:
PropertyResourceBundle, Serialized Form

Field Summary

protected Properties
defaults
The property list that contains default values for any keys not in this property list.

Constructor Summary

Properties()
Creates a new empty property list with no default values.
Properties(Properties defaults)
Create a new empty property list with the specified default values.

Method Summary

String
getProperty(String key)
Gets the property with the specified key in this property list.
String
getProperty(String key, String defaultValue)
Gets the property with the specified key in this property list.
void
list(PrintStream out)
Prints the key/value pairs to the given print stream.
void
list(PrintWriter out)
Prints the key/value pairs to the given print writer.
void
load(InputStream inStream)
Reads a property list from an input stream.
void
loadFromXML(InputStream in)
Decodes the contents of the supplied InputStream as an XML file, which represents a set of properties.
Enumeration
propertyNames()
Returns an enumeration of all keys in this property list, including the keys in the default property list.
Object
setProperty(String key, String value)
Adds the given key/value pair to this properties.
void
store(OutputStream out, String header)
Writes the key/value pairs to the given output stream, in a format suitable for load.
If header is not null, this method writes a comment containing the header as first line to the stream.
void
storeToXML(OutputStream os, String comment)
Encodes the properties as an XML file using the UTF-8 encoding.
void
storeToXML(OutputStream os, String comment, String encoding)
Encodes the properties as an XML file using the supplied encoding.
@Deprecated
void save(OutputStream out, String header)
Deprecated. use store(OutputStream,String) instead

Methods inherited from class java.util.Hashtable<K,V>

V>> entrySet, clear, clone, contains, containsKey, containsValue, elements, equals, get, hashCode, isEmpty, keySet, keys, put, putAll, rehash, remove, size, toString, values

Methods inherited from class java.util.Dictionary<K,V>

elements, get, isEmpty, keys, put, remove, size

Methods inherited from class java.lang.Object

clone, equals, extends Object> getClass, finalize, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

defaults

protected Properties defaults
The property list that contains default values for any keys not in this property list.

Constructor Details

Properties

public Properties()
Creates a new empty property list with no default values.

Properties

public Properties(Properties defaults)
Create a new empty property list with the specified default values.
Parameters:
defaults - a Properties object containing the default values

Method Details

getProperty

public String getProperty(String key)
Gets the property with the specified key in this property list. If the key is not found, the default property list is searched. If the property is not found in the default, null is returned.
Parameters:
key - The key for this property
Returns:
the value for the given key, or null if not found
Throws:
ClassCastException - if this property contains any key or value that isn't a string

getProperty

public String getProperty(String key,
                          String defaultValue)
Gets the property with the specified key in this property list. If the key is not found, the default property list is searched. If the property is not found in the default, the specified defaultValue is returned.
Parameters:
key - The key for this property
defaultValue - A default value
Returns:
The value for the given key
Throws:
ClassCastException - if this property contains any key or value that isn't a string

list

public void list(PrintStream out)
Prints the key/value pairs to the given print stream. This is mainly useful for debugging purposes.
Parameters:
out - the print stream, where the key/value pairs are written to
Throws:
ClassCastException - if this property contains a key or a value that isn't a string

list

public void list(PrintWriter out)
Prints the key/value pairs to the given print writer. This is mainly useful for debugging purposes.
Parameters:
out - the print writer where the key/value pairs are written to
Throws:
ClassCastException - if this property contains a key or a value that isn't a string
Since:
1.1

load

public void load(InputStream inStream)
            throws IOException
Reads a property list from an input stream. The stream should have the following format:
An empty line or a line starting with # or ! is ignored. An backslash (\) at the end of the line makes the line continueing on the next line (but make sure there is no whitespace after the backslash). Otherwise, each line describes a key/value pair.
The chars up to the first whitespace, = or : are the key. You can include this caracters in the key, if you precede them with a backslash (\). The key is followed by optional whitespaces, optionally one = or :, and optionally some more whitespaces. The rest of the line is the resource belonging to the key.
Escape sequences \t, \n, \r, \\, \", \', \!, \#, \ (a space), and unicode characters with the \\uxxxx notation are detected, and converted to the corresponding single character.
# This is a comment
key     = value
k\:5      \ a string starting with space and ending with newline\n
# This is a multiline specification; note that the value contains
# no white space.
weekdays: Sunday,Monday,Tuesday,Wednesday,\\
Thursday,Friday,Saturday
# The safest way to include a space at the end of a value:
label   = Name:\\u0020
Parameters:
inStream - the input stream
Throws:
IOException - if an error occurred when reading the input
NullPointerException - if in is null

loadFromXML

public void loadFromXML(InputStream in)
            throws IOException,
                   InvalidPropertiesFormatException
Decodes the contents of the supplied InputStream as an XML file, which represents a set of properties. The format of the XML file must match the DTD http://java.sun.com/dtd/properties.dtd.
Parameters:
in - the input stream from which to receive the XML data.
Throws:
IOException - if an I/O error occurs in reading the input data.
InvalidPropertiesFormatException - if the input data does not constitute an XML properties file.
NullPointerException - if in is null.
Since:
1.5

propertyNames

public Enumeration propertyNames()
Returns an enumeration of all keys in this property list, including the keys in the default property list.
Returns:
an Enumeration of all defined keys

setProperty

public Object setProperty(String key,
                          String value)
Adds the given key/value pair to this properties. This calls the hashtable method put.
Parameters:
key - the key for this property
value - the value for this property
Returns:
The old value for the given key
Since:
1.2

store

public void store(OutputStream out,
                  String header)
            throws IOException
Writes the key/value pairs to the given output stream, in a format suitable for load.
If header is not null, this method writes a comment containing the header as first line to the stream. The next line (or first line if header is null) contains a comment with the current date. Afterwards the key/value pairs are written to the stream in the following format.
Each line has the form key = value. Newlines, Returns and tabs are written as \n,\t,\r resp. The characters \, !, #, = and : are preceeded by a backslash. Spaces are preceded with a backslash, if and only if they are at the beginning of the key. Characters that are not in the ascii range 33 to 127 are written in the \uxxxx Form.
Following the listing, the output stream is flushed but left open.
Parameters:
out - the output stream
header - the header written in the first line, may be null
Throws:
ClassCastException - if this property contains any key or value that isn't a string
IOException - if writing to the stream fails
NullPointerException - if out is null
Since:
1.2

storeToXML

public void storeToXML(OutputStream os,
                       String comment)
            throws IOException
Encodes the properties as an XML file using the UTF-8 encoding. The format of the XML file matches the DTD http://java.sun.com/dtd/properties.dtd.

Invoking this method provides the same behaviour as invoking storeToXML(os, comment, "UTF-8").

Parameters:
os - the stream to output to.
comment - a comment to include at the top of the XML file, or null if one is not required.
Throws:
IOException - if the serialization fails.
NullPointerException - if os is null.
Since:
1.5

storeToXML

public void storeToXML(OutputStream os,
                       String comment,
                       String encoding)
            throws IOException
Encodes the properties as an XML file using the supplied encoding. The format of the XML file matches the DTD http://java.sun.com/dtd/properties.dtd.
Parameters:
os - the stream to output to.
comment - a comment to include at the top of the XML file, or null if one is not required.
encoding - the encoding to use for the XML output.
Throws:
IOException - if the serialization fails.
NullPointerException - if os or encoding is null.
Since:
1.5

void save

public @Deprecated void save(OutputStream out,
                             String header)

Deprecated. use store(OutputStream,String) instead

Calls store(OutputStream out, String header) and ignores the IOException that may be thrown.
Parameters:
out - the stream to write to
header - a description of the property list
Throws:
ClassCastException - if this property contains any key or value that are not strings

Properties.java -- a set of persistent properties Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005 Free Software Foundation, Inc. This file is part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. GNU Classpath is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with GNU Classpath; see the file COPYING. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination. As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.