ewe.util
Class Properties

java.lang.Object
  ewe.util.Hashtable
      ewe.util.Properties

All Implemented Interfaces:

Map

public class Properties

extends Hashtable

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 ä)

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 Java UTF8 encoding.

See Also:

PropertyResourceBundle

Nested Class Summary

Nested classes inherited from class ewe.util.Map

Map.MapEntry

Field Summary

protected Properties	defaults The property list that contains default values for any keys not in this property list.
static String	ENCODING This is the encoding used.

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.

Properties(PropertyList pl)
Create a new property list from a ewe.data.PropertyList object.

Method Summary

Object	clone() Create a field for field copy of this Object if this Object implements the Cloneable interface.
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(PrintWriter out) Prints the key/value pairs to the given print writer.
void	load(InputStream inStream) Reads a property list from an input stream.
Enumeration	propertyNames() Returns an enumeration of all keys in this property list, including the keys in the default property list.
void	set(Properties other) Set the properties in this collection from those in the specified Properties.
void	set(PropertyList pl) Set the properties in this collection from those in the specified PropertyList.
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.
PropertyList	toPropertyList(PropertyList destination) Convert/copy the properties in this collection into a PropertyList object.

Methods inherited from class ewe.util.Hashtable

clear, containsKey, containsValue, elements, entries, get, isEmpty, keys, put, rehash, remove, size

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, toString

Field Detail

ENCODING

public static String ENCODING

This is the encoding used. By default it is IO.JAVA_UTF8_CODEC

defaults

protected Properties defaults

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

Constructor Detail

Properties

public Properties()

Creates a new empty property list with no default values.

Properties

public Properties(PropertyList pl)

Create a new property list from a ewe.data.PropertyList object.

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 Detail

toPropertyList

public PropertyList toPropertyList(PropertyList destination)

Convert/copy the properties in this collection into a PropertyList object. This method will also set the default values in the destination PropertyList if they are not explicitly set in this Properties object.

Parameters:

destination - A possibly null destination PropertyList.

Returns:

The destination or new PropertyList.

set

public void set(PropertyList pl)

Set the properties in this collection from those in the specified PropertyList.

set

public void set(Properties other)

Set the properties in this collection from those in the specified Properties.

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

See Also:

getProperty(String)

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

Throws:

IOException - if an error occurred when reading the input

NullPointerException - if in is null

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

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

See Also:

defaults, setProperty(String, String), getProperty(String, 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

See Also:

defaults, setProperty(String, String)

clone

public Object clone()

Description copied from class: Object

Create a field for field copy of this Object if this Object implements the Cloneable interface.

Overrides:

clone in class Object

Returns:

A clone of this Object.

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

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

See Also:

#list(PrintStream)