Package 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	Description
static class	Maps.SerializableEntry<K,V>	A serializable implement of Map.Entry

Constructor Summary

Constructors

Constructor	Description
Maps()

Method Summary

Modifier and Type	Method	Description
static final 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 final 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 final 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 final 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	of(Object... args)	Returns a map containing the given mappings.
static final 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 final 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 final 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 final 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 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)	Parse a string into a map.
static final 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 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)	Parse a string into a map that allows multiple values.
static final String	toString(Map<? super String,? super String> map, char quote, char separator)	Converts a map to a string.
static final String	toString(Map<? super String,? super String> map, char quote, char separator, char pairSeparator)	Converts a map to a string.
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.
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.
static <K, V> Set<Maps.SerializableEntry<K,V>>	transferToSerializableEntrySet(Set<Map.Entry<K,V>> entry)	Transfer Set<<Map.Entry<K, V>> to be serializable

Methods inherited from class java.lang.Object

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

Constructor Details

Maps

public Maps()

Method Details

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)

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)

Transfer Set<<Map.Entry<K, V>> to be serializable

Since:

8.0.0

of

public static Map of(Object... args)

Returns a map containing the given mappings.

Since:

10.0.0