org.gvsig.i18n.utils
Class OrderedProperties

java.lang.Object
  extended byjava.util.AbstractMap
      extended byjava.util.TreeMap
          extended byorg.gvsig.i18n.utils.OrderedProperties
All Implemented Interfaces:
java.lang.Cloneable, java.util.Map, java.io.Serializable, java.util.SortedMap
Direct Known Subclasses:
DoubleProperties

public class OrderedProperties
extends java.util.TreeMap

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 the specified encoding. If no encoding is specified, then the ISO 8859-1 encoding is used, with Unicode escapes with a single u for any character which cannot be represented.

Author:
Jochen Hoenicke, Eric Blake (ebb9@email.byu.edu), Cesar Martinez Izquierdo (cesar.martinez@iver.es)
See Also:
status: updated to 1.4, Serialized Form

Constructor Summary
OrderedProperties()
          Creates a new empty property list with no default values.
OrderedProperties(OrderedProperties defaults)
          Create a new empty property list with the specified default values.
 
Method Summary
 java.lang.String getProperty(java.lang.String key)
          Gets the property with the specified key in this property list.
 java.lang.String getProperty(java.lang.String key, java.lang.String defaultValue)
          Gets the property with the specified key in this property list.
 void list(java.io.PrintStream out)
          Prints the key/value pairs to the given print stream.
 void list(java.io.PrintWriter out)
          Prints the key/value pairs to the given print writer.
 void load(java.io.InputStream inStream)
          Reads a property list from an input stream.
 void load(java.io.InputStream inStream, java.lang.String encoding)
          Reads a property list from an input stream, using the provided encoding.
 java.util.Enumeration propertyNames()
          Returns an enumeration of all keys in this property list, including the keys in the default property list.
 java.lang.Object setProperty(java.lang.String key, java.lang.String value)
          Adds the given key/value pair to this properties.
 void store(java.io.OutputStream out, java.lang.String header)
          Writes the key/value pairs to the given output stream, in a format suitable for load(InputStream).
 void store(java.io.OutputStream out, java.lang.String header, java.lang.String encoding)
          Writes the key/value pairs to the given output stream, in a format suitable for load(InputStream is, String encoding).
 
Methods inherited from class java.util.TreeMap
clear, clone, comparator, containsKey, containsValue, entrySet, firstKey, get, headMap, keySet, lastKey, put, putAll, remove, size, subMap, tailMap, values
 
Methods inherited from class java.util.AbstractMap
equals, hashCode, isEmpty, toString
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface java.util.Map
equals, hashCode, isEmpty
 

Constructor Detail

OrderedProperties

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


OrderedProperties

public OrderedProperties(OrderedProperties defaults)
Create a new empty property list with the specified default values.

Parameters:
defaults - a Properties object containing the default values
Method Detail

setProperty

public java.lang.Object setProperty(java.lang.String key,
                                    java.lang.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(java.io.InputStream inStream)
          throws java.io.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 these 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:
java.io.IOException - if an error occurred when reading the input
java.lang.NullPointerException - if in is null

load

public void load(java.io.InputStream inStream,
                 java.lang.String encoding)
          throws java.io.IOException
Reads a property list from an input stream, using the provided encoding. The provided stream should be correctly encoded as specified, otherwise an IOException error will be thrown. No escape sequences are accepted to represent any character, and thus this method has some limitations and the format of the accepted property files is slightly different from the standard Java property files. The main differences are: The stream should have the following format:
An empty line or a line starting with # or ! is ignored. Otherwise, each line describes a key/value pair.
The chars up to the first whitespace, = or : are the key. You cannot include these caracters in the key. 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.

Parameters:
inStream - the input stream
Throws:
java.io.IOException - if an error occurred when reading the input
java.lang.NullPointerException - if in is null

store

public void store(java.io.OutputStream out,
                  java.lang.String header,
                  java.lang.String encoding)
           throws java.io.IOException
Writes the key/value pairs to the given output stream, in a format suitable for load(InputStream is, String encoding). Note that this method does not use escape sequences to represent characters outside the encoding range, charset-dependent substitution sequence will be generated if such character is present in the stream. Moreover, because there is no escape sequences, the newline (\n) and carriage return (\r) characters must not be used (the resulting property file will be incorrect). Because of the same reason, whitespaces, :, =, ! and # must not be used in the key
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. 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:
java.lang.ClassCastException - if this property contains any key or value that isn't a string
java.io.IOException - if writing to the stream fails
java.lang.NullPointerException - if out is null
Since:
1.2

store

public void store(java.io.OutputStream out,
                  java.lang.String header)
           throws java.io.IOException
Writes the key/value pairs to the given output stream, in a format suitable for load(InputStream).
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:
java.lang.ClassCastException - if this property contains any key or value that isn't a string
java.io.IOException - if writing to the stream fails
java.lang.NullPointerException - if out is null
Since:
1.2

getProperty

public java.lang.String getProperty(java.lang.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:
java.lang.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 java.lang.String getProperty(java.lang.String key,
                                    java.lang.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:
java.lang.ClassCastException - if this property contains any key or value that isn't a string
See Also:
#defaults, setProperty(String, String)

propertyNames

public java.util.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(java.io.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:
java.lang.ClassCastException - if this property contains a key or a value that isn't a string
See Also:
list(PrintWriter)

list

public void list(java.io.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:
java.lang.ClassCastException - if this property contains a key or a value that isn't a string
Since:
1.1
See Also:
list(PrintStream)