com.taco.util
Class MultiLineProperties

java.lang.Object
  extended by java.util.Dictionary
      extended by java.util.Hashtable
          extended by java.util.Properties
              extended by com.taco.util.MultiLineProperties
All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable, java.util.Map

public class MultiLineProperties
extends java.util.Properties

A subclass of java.util.Properties that allows a slightly more user-friendly syntax. If a property value is a C-like expression, it may span multiple lines, without the '\' at the end of each line, provided that the expression has not closed all parenthesis, quotes, etc. This allows values that are BeanShell expressions in particular to be much easier to write.

Also, if '\' is the last non-whitespace character on a line, it is treated as a line continuation marker. This differs from java.util.Properties in which it must be the last character on a line; whitespace afterward invalidates its interpretation as a line continuation marker. In practice, this is quite annoying.

Finally, comments can be associated with each key/value pair. When reading a .properties file, instances of this class associate comments with the key/value pair below it. These comments can be retrieved and set by the user. When a .properties file is written out by this class, if a key/value pair has a comment associated with it, it will be written out before the definition of the property. Thus comments are more or less preserved during the process of reading a .properties file and writing it back out again.

One other deficiency with Properties is fixed by this class. Properties extends Hashtable and uses the hash table to store its mappings. This results in randomly ordered mappings, so key/value pairs are stored and output in a totally different order than read in. To correct this problem, this class uses a LinkedHashMap to store mappings, which keeps the mappings in insertion order. Thus keys(), keySet().iterator(), entrySet().iterator(), and elements(), values().iterator() return iterators that iterate over the mappings in the same order as they appeared in the .properties file. store() outputs the mappings in the same order.

Warning: unlike Properties, this class is not synchronized. This is so a resource bundle backed by an instance of this class doesn't need to copy the mappings or make synchronized calls to this instance. Instead, a resource bundle backed by an instance of this class can make calls to this class without any synchronization penalty.

See Also:
Serialized Form

Field Summary
protected static java.lang.String _ASSIGNMENT_CHARS
          All characters used explicitly to denote an assignment operation between keys and values.
protected static java.lang.String _COMMENT_CHARS
          All characters that mark the beginning of single line comments.
protected  java.util.Map _commentMap
          A map that holds the comments for each property key.
protected static java.util.regex.Pattern _KEY_ASSIGNMENT_PATTERN
          The pattern to match for a key assignment.
protected static java.lang.String _KEY_CHARS_TO_ESCAPE
          Characters in a property key to escape with a backslash before output.
protected static java.util.regex.Pattern _LINE_END_PATTERN
           
protected static java.lang.String _LINE_SEPARATOR
          The system-dependent line separator.
protected  java.util.Map _propertyMap
          A map that holds the properties in the same order as read in.
protected static java.lang.String _SPACE_CHARS
           
protected static java.lang.String _VALUE_CHARS_TO_ESCAPE
          Characters in a property value to escape with a backslash before output.
 
Fields inherited from class java.util.Properties
defaults
 
Constructor Summary
MultiLineProperties()
          Construct a new instance that has no mappings.
MultiLineProperties(java.util.Properties defaults)
          Construct a new instance that has the same mappings as defaults.
 
Method Summary
protected  java.lang.String _commentChars()
          Return a string consisting of all characters used to mark the beginning of single line comments.
protected  java.lang.String _formatComment(java.lang.CharSequence comment)
          Convert a comment (just ordinary text) into text that can actually be put into a .properties file.
protected  java.lang.String _keyCharsToEscape()
          Return a string consisting of all characters in a property key that need to be escaped with a backslash before being output.
protected  java.lang.String _valueCharsToEscape()
          Return a string consisting of all characters in a property value that need to be escaped with a backslash before being output.
 void clear()
           
 java.lang.Object clone()
           
 boolean contains(java.lang.Object value)
           
 boolean containsKey(java.lang.Object a0)
           
 boolean containsValue(java.lang.Object a0)
           
 java.util.Enumeration elements()
           
 java.util.Set entrySet()
           
 java.lang.Object get(java.lang.Object a0)
           
 java.lang.String getCommentForProperty(java.lang.String propertyName)
          Return the comments in the .properties file that appeared just before the definition of the property with the argument name.
 boolean isEmpty()
           
 java.util.Enumeration keys()
           
 java.util.Set keySet()
           
 void load(java.io.InputStream inputStream)
           
static void main(java.lang.String[] args)
          A simple test program.
 java.lang.Object put(java.lang.Object a0, java.lang.Object a1)
           
 void putAll(java.util.Map a0)
           
 java.lang.Object remove(java.lang.Object a0)
           
 void setCommentForProperty(java.lang.String propertyName, java.lang.String comment)
          Set the comment associated with the property with argument name.
 int size()
           
 void store(java.io.OutputStream outputStream, java.lang.String header)
           
static void usage()
           
 java.util.Collection values()
           
 
Methods inherited from class java.util.Properties
getProperty, getProperty, list, list, loadFromXML, propertyNames, save, setProperty, storeToXML, storeToXML
 
Methods inherited from class java.util.Hashtable
equals, hashCode, rehash, toString
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

_propertyMap

protected java.util.Map _propertyMap
A map that holds the properties in the same order as read in.


_commentMap

protected java.util.Map _commentMap
A map that holds the comments for each property key.


_COMMENT_CHARS

protected static final java.lang.String _COMMENT_CHARS
All characters that mark the beginning of single line comments.

See Also:
Constant Field Values

_ASSIGNMENT_CHARS

protected static final java.lang.String _ASSIGNMENT_CHARS
All characters used explicitly to denote an assignment operation between keys and values. This does not includes spaces, which implicitly separate keys and values.

See Also:
Constant Field Values

_SPACE_CHARS

protected static final java.lang.String _SPACE_CHARS
See Also:
Constant Field Values

_KEY_ASSIGNMENT_PATTERN

protected static final java.util.regex.Pattern _KEY_ASSIGNMENT_PATTERN
The pattern to match for a key assignment. This pattern matches the key, which may not contain unescaped ':' or '=' characters or spaces, followed by optional whitespace, followed by ':', '=', or a whitespace character, then followed by more optional whitespace. The key is captured in the first group. Note: we can use "\\s" without meaning line terminators since we only process a single line at a time.


_LINE_END_PATTERN

protected static final java.util.regex.Pattern _LINE_END_PATTERN

_VALUE_CHARS_TO_ESCAPE

protected static final java.lang.String _VALUE_CHARS_TO_ESCAPE
Characters in a property value to escape with a backslash before output. This includes the backslash character, assignment characters, and comment characters.

See Also:
Constant Field Values

_KEY_CHARS_TO_ESCAPE

protected static final java.lang.String _KEY_CHARS_TO_ESCAPE
Characters in a property key to escape with a backslash before output. This includes the backslash character, assignment characters, comment characters, the space character.

See Also:
Constant Field Values

_LINE_SEPARATOR

protected static final java.lang.String _LINE_SEPARATOR
The system-dependent line separator.

Constructor Detail

MultiLineProperties

public MultiLineProperties()
Construct a new instance that has no mappings.


MultiLineProperties

public MultiLineProperties(java.util.Properties defaults)
Construct a new instance that has the same mappings as defaults.

Method Detail

put

public java.lang.Object put(java.lang.Object a0,
                            java.lang.Object a1)
Specified by:
put in interface java.util.Map
Overrides:
put in class java.util.Hashtable

get

public java.lang.Object get(java.lang.Object a0)
Specified by:
get in interface java.util.Map
Overrides:
get in class java.util.Hashtable

size

public int size()
Specified by:
size in interface java.util.Map
Overrides:
size in class java.util.Hashtable

values

public java.util.Collection values()
Specified by:
values in interface java.util.Map
Overrides:
values in class java.util.Hashtable

remove

public java.lang.Object remove(java.lang.Object a0)
Specified by:
remove in interface java.util.Map
Overrides:
remove in class java.util.Hashtable

clear

public void clear()
Specified by:
clear in interface java.util.Map
Overrides:
clear in class java.util.Hashtable

containsKey

public boolean containsKey(java.lang.Object a0)
Specified by:
containsKey in interface java.util.Map
Overrides:
containsKey in class java.util.Hashtable

containsValue

public boolean containsValue(java.lang.Object a0)
Specified by:
containsValue in interface java.util.Map
Overrides:
containsValue in class java.util.Hashtable

entrySet

public java.util.Set entrySet()
Specified by:
entrySet in interface java.util.Map
Overrides:
entrySet in class java.util.Hashtable

isEmpty

public boolean isEmpty()
Specified by:
isEmpty in interface java.util.Map
Overrides:
isEmpty in class java.util.Hashtable

keySet

public java.util.Set keySet()
Specified by:
keySet in interface java.util.Map
Overrides:
keySet in class java.util.Hashtable

putAll

public void putAll(java.util.Map a0)
Specified by:
putAll in interface java.util.Map
Overrides:
putAll in class java.util.Hashtable

clone

public java.lang.Object clone()
Overrides:
clone in class java.util.Hashtable

contains

public boolean contains(java.lang.Object value)
Overrides:
contains in class java.util.Hashtable

elements

public java.util.Enumeration elements()
Overrides:
elements in class java.util.Hashtable

keys

public java.util.Enumeration keys()
Overrides:
keys in class java.util.Hashtable

load

public void load(java.io.InputStream inputStream)
          throws java.io.IOException
Overrides:
load in class java.util.Properties
Throws:
java.io.IOException

store

public void store(java.io.OutputStream outputStream,
                  java.lang.String header)
           throws java.io.IOException
Overrides:
store in class java.util.Properties
Throws:
java.io.IOException

usage

public static void usage()

main

public static void main(java.lang.String[] args)
A simple test program.


_formatComment

protected java.lang.String _formatComment(java.lang.CharSequence comment)

Convert a comment (just ordinary text) into text that can actually be put into a .properties file.

This implementation simply puts a '#' character in front of each line. The contents of each line and number of lines are unchanged.


getCommentForProperty

public java.lang.String getCommentForProperty(java.lang.String propertyName)
Return the comments in the .properties file that appeared just before the definition of the property with the argument name.


setCommentForProperty

public void setCommentForProperty(java.lang.String propertyName,
                                  java.lang.String comment)
Set the comment associated with the property with argument name. The comment will be printed just before the definition of the property in the .properties file.


_commentChars

protected java.lang.String _commentChars()
Return a string consisting of all characters used to mark the beginning of single line comments. This base implementation returns _COMMENT_CHARS.


_keyCharsToEscape

protected java.lang.String _keyCharsToEscape()
Return a string consisting of all characters in a property key that need to be escaped with a backslash before being output. This base implementation returns _KEY_CHARS_TO_ESCAPE.


_valueCharsToEscape

protected java.lang.String _valueCharsToEscape()
Return a string consisting of all characters in a property value that need to be escaped with a backslash before being output. This base implementation returns _VALUE_CHARS_TO_ESCAPE.