org.zkoss.util

Class Maps

java.lang.Object

org.zkoss.util.Maps

public class Maps
extends Object

Utilities for process Map.

Author:

tomyeh

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Maps.SerializableEntry<K,V> A serializable implement of Map.Entry

Constructor Summary

Constructors

Constructor and Description
Maps()

Method Summary

Modifier and Type	Method and Description
static void	load(Map<? super String,? super String> map, InputStream sm) Reads a property list (key and element pairs) from the input stream, by detecting correct charset.
static void	load(Map<? super String,? super String> map, InputStream sm, boolean caseInsensitive) Reads a property list (key and element pairs) from the input stream, by detecting correct charset.
static void	load(Map<? super String,? super String> map, InputStream sm, String charset) Reads a property list (key and element pairs) from the input stream, by specifying the charset.
static void	load(Map<? super String,? super String> map, InputStream sm, String charset, boolean caseInsensitive) Reads a property list (key and element pairs) from the input stream, by specifying the charset.
static Map<? super String,? super String>	parse(Map<? super String,? super String> map, String src, char separator, char quote) Parses a string into a map.
static Map<? super String,? super String>	parse(Map<? super String,? super String> map, String src, char separator, char quote, boolean asValue) Parses a string into a map.
static Map<? super String,? super String>	parse(Map<? super String,? super String> map, String src, char separator, char quote, boolean asValue, boolean parenthesis) Parses a string into a map.
static Map<? super String,? super String>	parse(Map<? super String,? super String> map, String src, char pairSeparator, char separator, char quote) Parses a string into a map.
static Map<? super String,? super String>	parse(Map<? super String,? super String> map, String src, char pairSeparator, char separator, char quote, boolean asValue, boolean parenthesis) Parse a string into a map.
static Map	parse(Map map, String src, char separator, char quote, boolean asValue, boolean multiple, boolean parenthesis) Deprecated. As of release 6.0.0, replaced with parse(Map, String, char, char, boolean, boolean) and parseMultiple(java.util.Map<? super java.lang.String, java.util.Collection<java.lang.String>>, java.lang.String, char, char, boolean, boolean)
static Map<? super String,Collection<String>>	parseMultiple(Map<? super String,Collection<String>> map, String src, char separator, char quote, boolean asValue, boolean parenthesis) Parse a string into a map that allows multiple values..
static Map<? super String,Collection<String>>	parseMultiple(Map<? super String,Collection<String>> map, String src, char pairSeparator, char separator, char quote, boolean asValue, boolean parenthesis) Parse a string into a map that allows multiple values.
static String	toString(Map<? super String,? super String> map, char quote, char separator) Converts a map to a string.
static String	toString(Map<? super String,? super String> map, char quote, char separator, char pairSeparator) Converts a map to a string.
static StringBuffer	toStringBuffer(StringBuffer sb, Map<? super String,? super String> map, char quote, char separator) Converts a map to string and append to a string buffer.
static StringBuffer	toStringBuffer(StringBuffer sb, Map<? super String,? super String> map, char quote, char separator, char pairSeparator) Converts a map to string and append to a string buffer.
static <K,V> Set<Maps.SerializableEntry<K,V>>	transferToSerializableEntrySet(Set<Map.Entry<K,V>> entry) Tranfer Set<> to be serializable

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(Map<? super String,? super String> map,
                              InputStream sm,
                              String charset,
                              boolean caseInsensitive)
                       throws 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, described 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 spread 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 considered 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:

IOException

load

public static final void load(Map<? super String,? super String> map,
                              InputStream sm,
                              String charset)
                       throws IOException

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

Throws:

IOException

load

public static final void load(Map<? super String,? super String> map,
                              InputStream sm,
                              boolean caseInsensitive)
                       throws 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:

IOException

load

public static final void load(Map<? super String,? super String> map,
                              InputStream sm)
                       throws IOException

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

Throws:

IOException

parse

public static final Map<? super String,? super String> parse(Map<? super String,? super String> map,
                                                             String src,
                                                             char separator,
                                                             char quote)
                                                      throws IllegalSyntaxException

Parses a string into a map. It is the same as

parse(map, src, '=', separator, quote, false, false, false);

Throws:

IllegalSyntaxException

See Also:

parse(Map, String, char, char, char, boolean, boolean), parseMultiple(java.util.Map<? super java.lang.String, java.util.Collection<java.lang.String>>, java.lang.String, char, char, boolean, boolean)

parse

public static final Map<? super String,? super String> parse(Map<? super String,? super String> map,
                                                             String src,
                                                             char separator,
                                                             char quote,
                                                             boolean asValue)
                                                      throws IllegalSyntaxException

Parses a string into a map. It is the same as

parse(map, src, '=', separator, quote, asValue, false, false);

Throws:

IllegalSyntaxException

Since:

2.4.0

See Also:

parse(Map, String, char, char, char, boolean, boolean), parseMultiple(java.util.Map<? super java.lang.String, java.util.Collection<java.lang.String>>, java.lang.String, char, char, boolean, boolean)

parse

public static final Map<? super String,? super String> parse(Map<? super String,? super String> map,
                                                             String src,
                                                             char pairSeparator,
                                                             char separator,
                                                             char quote)
                                                      throws IllegalSyntaxException

Parses a string into a map. It is the same as

parse(map, src, pairSeparator, separator, quote, false, false, false);

Throws:

IllegalSyntaxException

Since:

7.0.1

See Also:

parse(Map, String, char, char, char, boolean, boolean), parseMultiple(java.util.Map<? super java.lang.String, java.util.Collection<java.lang.String>>, java.lang.String, char, char, boolean, boolean)

parse

public static final Map<? super String,? super String> parse(Map<? super String,? super String> map,
                                                             String src,
                                                             char separator,
                                                             char quote,
                                                             boolean asValue,
                                                             boolean parenthesis)
                                                      throws IllegalSyntaxException

Parses a string into a map. It is the same as

parse(map, src, '=', separator, quote, asValue, parenthesis, false);

Throws:

IllegalSyntaxException

Since:

6.0.0

See Also:

parse(Map, String, char, char, char, boolean, boolean), parseMultiple(java.util.Map<? super java.lang.String, java.util.Collection<java.lang.String>>, java.lang.String, char, char, boolean, boolean)

parse

public static final Map<? super String,? super String> parse(Map<? super String,? super String> map,
                                                             String src,
                                                             char pairSeparator,
                                                             char separator,
                                                             char quote,
                                                             boolean asValue,
                                                             boolean parenthesis)
                                                      throws IllegalSyntaxException

Parse 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 backslash 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

pairSeparator - the separator of key and value, e.g., '=' or ':'.

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

quote - the quote character to surround the value. Ignored if quote is (char)0.
Since 3.6.0: if quote is (char)1, then both ' and " are accepted.
For example, a1='b c' will generate a map entry, ("a1", "b c") if quote is '\''.
Note: the quote is taken off before storing to the map.
Note: the quote can not be used to surround the name

asValue - whether to consider the substring without = as a value (with the null key), or as a key (with the null value) For example, a12 is considered as a key if asValue is false. However, if you surround it with a quote, it is always considered as a value. For example, 'a12' is considered as a value no matter asValue is true or not.

parenthesis - whether to parse parenthesis in the value, {}, () and []. If true, the separator is ignored inside the parenthesis. Specify true if the value might contain EL expressions. Note: it has no effect to the name.

Returns:

the map being generated.

Throws:

IllegalSyntaxException - if syntax errors

Since:

7.0.1

See Also:

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

parseMultiple

public static final Map<? super String,Collection<String>> parseMultiple(Map<? super String,Collection<String>> map,
                                                                         String src,
                                                                         char separator,
                                                                         char quote,
                                                                         boolean asValue,
                                                                         boolean parenthesis)
                                                                  throws IllegalSyntaxException

Parse a string into a map that allows multiple values.. It is the same as

parseMultiple(map, src, '=', separator, quote, asValue, parenthesis);

Throws:

IllegalSyntaxException

Since:

6.0.0

See Also:

parseMultiple(Map, String, char, char, char, boolean, boolean), CollectionsX.parse(java.util.Collection<java.lang.String>, java.lang.String, char), toString(Map, char, char, char)

parseMultiple

public static final Map<? super String,Collection<String>> parseMultiple(Map<? super String,Collection<String>> map,
                                                                         String src,
                                                                         char pairSeparator,
                                                                         char separator,
                                                                         char quote,
                                                                         boolean asValue,
                                                                         boolean parenthesis)
                                                                  throws IllegalSyntaxException

Parse a string into a map that allows multiple values.

Unlike parse(java.util.Map<? super java.lang.String, ? super java.lang.String>, java.lang.String, char, char), it assumes there might be multiple values. Thus, the value of the map is a collection of String instances. For example, src is a1=x,a1=y, then the value for a1 is a list with two values, "x" and "y".

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 backslash 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

pairSeparator - the separator of key and value, e.g., '=' or ':'.

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

quote - the quote character to surround the value. Ignored if quote is (char)0.
Since 3.6.0: if quote is (char)1, then both ' and " are accepted.
For example, a1='b c' will generate a map entry, ("a1", "b c") if quote is '\''.
Note: the quote is taken off before storing to the map.
Note: the quote can not be used to surround the name

asValue - whether to consider the substring without = as a value (with the null key), or as a key (with the null value) For example, a12 is considered as a key if asValue is false. However, if you surround it with a quote, it is always considered as a value. For example, 'a12' is considered as a value no matter asValue is true or not.

parenthesis - whether to parse parenthesis in the value, {}, () and []. If true, the separator is ignored inside the parenthesis. Specify true if the value might contain EL expressions. Note: it has no effect to the name.

Returns:

the map being generated. The value of the map is a list of String objects (List<String>).

Throws:

IllegalSyntaxException - if syntax errors

Since:

7.0.1

See Also:

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

parse

public static final Map parse(Map map,
                              String src,
                              char separator,
                              char quote,
                              boolean asValue,
                              boolean multiple,
                              boolean parenthesis)
                       throws IllegalSyntaxException

Deprecated. As of release 6.0.0, replaced with parse(Map, String, char, char, boolean, boolean) and parseMultiple(java.util.Map<? super java.lang.String, java.util.Collection<java.lang.String>>, java.lang.String, char, char, boolean, boolean)

Throws:

IllegalSyntaxException

toString

public static final String toString(Map<? super String,? super String> map,
                                    char quote,
                                    char separator)

Converts a map to a string. It is the same as

toString(map, quote, separator, '=');

See Also:

toString(Map, char, char, char), parse(Map, String, char, char, char)

toString

public static final String toString(Map<? super String,? super String> map,
                                    char quote,
                                    char separator,
                                    char pairSeparator)

Converts a map to a string.

Parameters:

map - the map to convert from

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

separator - the separator between two name=value pairs

pairSeparator - the separator between name and value

Since:

7.0.1

See Also:

parse(Map, String, char, char, char)

toStringBuffer

public static final StringBuffer toStringBuffer(StringBuffer sb,
                                                Map<? super String,? super String> map,
                                                char quote,
                                                char separator)

Converts a map to string and append to a string buffer. It is the same as

toStringBuffer(sb, map, quote, separator, '=');

See Also:

toStringBuffer(StringBuffer, Map, char, char, char), toString(Map, char, char, char)

toStringBuffer

public static final StringBuffer toStringBuffer(StringBuffer sb,
                                                Map<? super String,? super String> map,
                                                char quote,
                                                char separator,
                                                char pairSeparator)

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

Since:

7.0.1

See Also:

toString(Map, char, char, char)

transferToSerializableEntrySet

public static <K,V> Set<Maps.SerializableEntry<K,V>> transferToSerializableEntrySet(Set<Map.Entry<K,V>> entry)

Tranfer Set<> to be serializable

Since:

8.0.0