org.zkoss.util
Class Maps

java.lang.Object
  org.zkoss.util.Maps

public class Maps
extends java.lang.Object

Utilities for process Map.

Author:

tomyeh

Constructor Summary

Maps()

Method Summary

static void	load(java.util.Map map, java.io.InputStream sm) Reads a property list (key and element pairs) from the input stream, by detecting correct charset.
static void	load(java.util.Map map, java.io.InputStream sm, boolean caseInsensitive) Reads a property list (key and element pairs) from the input stream, by detecting correct charset.
static void	load(java.util.Map map, java.io.InputStream sm, java.lang.String charset) Reads a property list (key and element pairs) from the input stream, by specifying the charset.
static void	load(java.util.Map map, java.io.InputStream sm, java.lang.String charset, boolean caseInsensitive) Reads a property list (key and element pairs) from the input stream, by specifying the charset.
static java.util.Map	parse(java.util.Map map, java.lang.String src, char separator, char quote) Parses a string into a map.
static java.util.Map	parse(java.util.Map map, java.lang.String src, char separator, char quote, boolean asValue) Parses a string into a map.
static java.lang.String	toString(java.util.Map map, char quote, char separator) Converts a map to a string.
static java.lang.StringBuffer	toStringBuffer(java.lang.StringBuffer sb, java.util.Map map, char quote, char separator) Converts a map to string and append to a string buffer.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Maps

public Maps()

Method Detail

load

public static final void load(java.util.Map map,
                              java.io.InputStream sm,
                              java.lang.String charset,
                              boolean caseInsensitive)
                       throws java.io.IOException

Reads a property list (key and element pairs) from the input stream, by specifying the charset.

Like java.util.Properties, it translates \\u, \n, \r, \t and \f. However, it enhanced Properties as follows.

• It accepts any charset, not just 8859-1.
• It uses a different syntax to let value spread over multiple lines, descrubed below.
• Whitespace is trimmed around '=' and at the beginning of the key and the ending of the value.
• Illegal lines are ignored (Properties.load considers it as a key with an empty value).
• Only '=' is accepted as the separator of key and value.
• Only '#' is accepted as comment lines.

To spead a value over multiple lines, you could, unlike java.util.Properties.load, append '{' to the end of a line. Then, all the following lines are considerred as part of a value, unless encountering a line containing only one '}'.
Example:

abc = {
line 1
line 2
}
xyz = {
line 1
line 2
}

Moreover, you could prefix a group of keys with certain prefix:

org.zkoss.some. {
 a = aaa
 b = bbb
}

It actually defines two keys: "org.zkoss.some.a" and "org.zkoss.some.b".

Note: (1) whitespace in the {...} block are all preserved.
(2) if only whitespaces is between '=' and '{', they are ignored.

Parameters:

charset - the charset; if null, it detects UTF-16 BOM (0xfe 0xff or 0xff 0xfe). If no UTF-16 BOM, UTF-8 is always assumed. Note 1: UTF-8's BOM (0xef 0xbb 0xbf) is optional, so we don't count on it. Note 2: ISO-8859-1 is not used because we cannot tell its difference from UTF-8 (while some of our properties files are in UTF-8).

caseInsensitive - whether the key used to access the map is case-insensitive. If true, all keys are converted to lower cases.

Throws:

java.io.IOException

load

public static final void load(java.util.Map map,
                              java.io.InputStream sm,
                              java.lang.String charset)
                       throws java.io.IOException

Reads a property list (key and element pairs) from the input stream, by specifying the charset.

Throws:

java.io.IOException

load

public static final void load(java.util.Map map,
                              java.io.InputStream sm,
                              boolean caseInsensitive)
                       throws java.io.IOException

Reads a property list (key and element pairs) from the input stream, by detecting correct charset.

Parameters:

caseInsensitive - whether the key used to access the map is case-insensitive. If true, all keys are converted to lower cases.

Throws:

java.io.IOException

load

public static final void load(java.util.Map map,
                              java.io.InputStream sm)
                       throws java.io.IOException

Reads a property list (key and element pairs) from the input stream, by detecting correct charset.

Throws:

java.io.IOException

parse

public static final java.util.Map parse(java.util.Map map,
                                        java.lang.String src,
                                        char separator,
                                        char quote)
                                 throws IllegalSyntaxException

Parses a string into a map.

For example, if the following string is parsed:
a12=12,b3,c6=abc=125,x=y

Then, a map with the following content is returned:
("a12", "12"), ("b3", null), ("c6", "abc=125"), ("x", "y")

If = is omitted, it is considered as a key with the null value. If you want to consider it as the value, use parse(Map, String, char, char, boolean) instead. Actually, this is the same as parse(map, src, separator, quote, false);

Notice: only the first = after separator is meaningful, so you don't have to escape the following =.

Beside specifying the quote character, you could use back slash quote a single character (as Java does).

Parameters:

map - the map to put parsed results to; null to create a new hash map

src - the string to parse

separator - the separator, e.g., ' ' or ','.

quote - the quote character to surrounding value, e.g., name = 'value'. If (char)0, no quotation is recognized. Notice: if value is an expression, it is better to specify (char)0 because expression might contain strings.

Returns:

the map being generated

Throws:

IllegalSyntaxException - if syntax errors

See Also:

CollectionsX.parse(java.util.Collection, java.lang.String, char), toString(Map, char, char)

parse

public static final java.util.Map parse(java.util.Map map,
                                        java.lang.String src,
                                        char separator,
                                        char quote,
                                        boolean asValue)
                                 throws IllegalSyntaxException

Parses a string into a map.

If = is omitted, whether it is considered as a key with the null value or a value with the null key depends on the asValue argument. If true, it is considered as a value with the null key.

For example, if the following string is parsed with asValue=false:
a12=12,b3,c6=abc=125,x=y

Then, a map with the following content is returned:
("a12", "12"), ("b3", null), ("c6", "abc=125"), ("x", "y")

Notice: only the first = after separator is meaningful, so you don't have to escape the following =.

Beside specifying the quote character, you could use back slash quote a single character (as Java does).

Parameters:

map - the map to put parsed results to; null to create a new hash map

src - the string to parse

separator - the separator, e.g., ' ' or ','.

quote - the quote character to surrounding value, e.g., name = 'value'. If (char)0, no quotation is recognized. Notice: if value is an expression, it is better to specify (char)0 because expression might contain strings.

asValue - whether to consider the substring without = as a value (with the null key), or as a key (with the null value)

Returns:

the map being generated

Throws:

IllegalSyntaxException - if syntax errors

Since:

2.4.0

See Also:

CollectionsX.parse(java.util.Collection, java.lang.String, char), toString(Map, char, char)

toString

public static final java.lang.String toString(java.util.Map map,
                                              char quote,
                                              char separator)

Converts a map to a string.

Parameters:

map - the map to convert from

quote - the quotation character; 0 means no quotation surrunding the value

separator - the separator between two name=value pairs

See Also:

parse(Map, String, char, char)

toStringBuffer

public static final java.lang.StringBuffer toStringBuffer(java.lang.StringBuffer sb,
                                                          java.util.Map map,
                                                          char quote,
                                                          char separator)

Converts a map to string and append to a string buffer.

See Also:

toString(java.util.Map, char, char)