Document and clarify Argeo Util.

[lgpl/argeo-commons.git] / org.argeo.util / src / org / argeo / util / LangUtils.java

diff --git a/org.argeo.util/src/org/argeo/util/LangUtils.java b/org.argeo.util/src/org/argeo/util/LangUtils.java
index 968f8ffe1543335d1126d958d14b092f79d60305..7824d12de41945c37a6ea9eeb1962db4f390428d 100644 (file)
--- a/org.argeo.util/src/org/argeo/util/LangUtils.java
+++ b/org.argeo.util/src/org/argeo/util/LangUtils.java
@@ -20,6 +20,7 @@ import java.util.Properties;
 import javax.naming.InvalidNameException;
 import javax.naming.ldap.LdapName;
 
+/** Utilities around Java basic features. */
 public class LangUtils {
        /*
         * NON-API OSGi
@@ -35,28 +36,43 @@ public class LangUtils {
                return res;
        }
 
+       /*
+        * MAP
+        */
+       /**
+        * Creates a new {@link Dictionary} with one key-value pair. Key should not be
+        * null, but if the value is null, it returns an empty {@link Dictionary}.
+        */
+       public static Map<String, Object> map(String key, Object value) {
+               assert key != null;
+               HashMap<String, Object> props = new HashMap<>();
+               if (value != null)
+                       props.put(key, value);
+               return props;
+       }
+
        /*
         * DICTIONARY
         */
 
        /**
-        * Creates a new {@link Dictionary} with one key-value pair (neither key not
-        * value should be null)
+        * Creates a new {@link Dictionary} with one key-value pair. Key should not be
+        * null, but if the value is null, it returns an empty {@link Dictionary}.
         */
        public static Dictionary<String, Object> dict(String key, Object value) {
                assert key != null;
-               assert value != null;
                Hashtable<String, Object> props = new Hashtable<>();
-               props.put(key, value);
+               if (value != null)
+                       props.put(key, value);
                return props;
        }
 
-       /**@deprecated Use {@link #dict(String, Object)} instead.*/
+       /** @deprecated Use {@link #dict(String, Object)} instead. */
        @Deprecated
        public static Dictionary<String, Object> dico(String key, Object value) {
                return dict(key, value);
        }
-       
+
        /** Converts a {@link Dictionary} to a {@link Map} of strings. */
        public static Map<String, String> dictToStringMap(Dictionary<String, ?> properties) {
                if (properties == null) {
@@ -71,6 +87,29 @@ public class LangUtils {
                return res;
        }
 
+       /**
+        * Get a string property from this map, expecting to find it, or
+        * <code>null</code> if not found.
+        */
+       public static String get(Map<String, ?> map, String key) {
+               Object res = map.get(key);
+               if (res == null)
+                       return null;
+               return res.toString();
+       }
+
+       /**
+        * Get a string property from this map, expecting to find it.
+        * 
+        * @throws IllegalArgumentException if the key was not found
+        */
+       public static String getNotNull(Map<String, ?> map, String key) {
+               Object res = map.get(key);
+               if (res == null)
+                       throw new IllegalArgumentException("Map " + map + " should contain key " + key);
+               return res.toString();
+       }
+
        /**
         * Wraps the keys of the provided {@link Dictionary} as an {@link Iterable}.
         */