Package org.zkoss.util

Class Maps

  • public class Maps
extends java.lang.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

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static void load​(java.util.Map<? super java.lang.String,​? super java.lang.String> 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<? super java.lang.String,​? super java.lang.String> 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<? super java.lang.String,​? super java.lang.String> 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<? super java.lang.String,​? super java.lang.String> 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 of​(java.lang.Object... args)
      Returns a map containing the given mappings.
      static java.util.Map<? super java.lang.String,​? super java.lang.String> parse​(java.util.Map<? super java.lang.String,​? super java.lang.String> map, java.lang.String src, char separator, char quote)
      Parses a string into a map.
      static java.util.Map<? super java.lang.String,​? super java.lang.String> parse​(java.util.Map<? super java.lang.String,​? super java.lang.String> map, java.lang.String src, char separator, char quote, boolean asValue)
      Parses a string into a map.
      static java.util.Map<? super java.lang.String,​? super java.lang.String> parse​(java.util.Map<? super java.lang.String,​? super java.lang.String> map, java.lang.String src, char separator, char quote, boolean asValue, boolean parenthesis)
      Parses a string into a map.
      static java.util.Map<? super java.lang.String,​? super java.lang.String> parse​(java.util.Map<? super java.lang.String,​? super java.lang.String> map, java.lang.String src, char pairSeparator, char separator, char quote)
      Parses a string into a map.
      static java.util.Map<? super java.lang.String,​? super java.lang.String> parse​(java.util.Map<? super java.lang.String,​? super java.lang.String> map, java.lang.String src, char pairSeparator, char separator, char quote, boolean asValue, boolean parenthesis)
      Parse a string into a map.
      static java.util.Map<? super java.lang.String,​java.util.Collection<java.lang.String>> parseMultiple​(java.util.Map<? super java.lang.String,​java.util.Collection<java.lang.String>> map, java.lang.String src, char separator, char quote, boolean asValue, boolean parenthesis)
      Parse a string into a map that allows multiple values..
      static java.util.Map<? super java.lang.String,​java.util.Collection<java.lang.String>> parseMultiple​(java.util.Map<? super java.lang.String,​java.util.Collection<java.lang.String>> map, java.lang.String src, char pairSeparator, char separator, char quote, boolean asValue, boolean parenthesis)
      Parse a string into a map that allows multiple values.
      static java.lang.String toString​(java.util.Map<? super java.lang.String,​? super java.lang.String> map, char quote, char separator)
      Converts a map to a string.
      static java.lang.String toString​(java.util.Map<? super java.lang.String,​? super java.lang.String> map, char quote, char separator, char pairSeparator)
      Converts a map to a string.
      static java.lang.StringBuffer toStringBuffer​(java.lang.StringBuffer sb, java.util.Map<? super java.lang.String,​? super java.lang.String> map, char quote, char separator)
      Converts a map to string and append to a string buffer.
      static java.lang.StringBuffer toStringBuffer​(java.lang.StringBuffer sb, java.util.Map<? super java.lang.String,​? super java.lang.String> map, char quote, char separator, char pairSeparator)
      Converts a map to string and append to a string buffer.
      static <K,​V>
      java.util.Set<Maps.SerializableEntry<K,​V>>      		 transferToSerializableEntrySet​(java.util.Set<java.util.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 Detail

      • Maps

        public Maps()

    • Method Detail

      • load

        public static final void load​(java.util.Map<? super java.lang.String,​? super java.lang.String> 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, 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:
        java.io.IOException

      • load

        public static final void load​(java.util.Map<? super java.lang.String,​? super java.lang.String> 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<? super java.lang.String,​? super java.lang.String> 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<? super java.lang.String,​? super java.lang.String> 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<? super java.lang.String,​? super java.lang.String> parse​(java.util.Map<? super java.lang.String,​? super java.lang.String> map,
                                                                                                 java.lang.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 java.util.Map<? super java.lang.String,​java.util.Collection<java.lang.String>> parseMultiple​(java.util.Map<? super java.lang.String,​java.util.Collection<java.lang.String>> map,
                                                                                                                       java.lang.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 java.lang.String toString​(java.util.Map<? super java.lang.String,​? super java.lang.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 java.lang.StringBuffer toStringBuffer​(java.lang.StringBuffer sb,
                                                          java.util.Map<? super java.lang.String,​? super java.lang.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 java.lang.StringBuffer toStringBuffer​(java.lang.StringBuffer sb,
                                                          java.util.Map<? super java.lang.String,​? super java.lang.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> java.util.Set<Maps.SerializableEntry<K,​V>> transferToSerializableEntrySet​(java.util.Set<java.util.Map.Entry<K,​V>> entry)
        Transfer Set<<Map.Entry<K, V>> to be serializable
        Since:
        8.0.0

      • of

        public static java.util.Map of​(java.lang.Object... args)
        Returns a map containing the given mappings.
        Since:
        10.0.0