Javadoc and clarify null handling

git-svn-id: https://svn.apache.org/repos/asf/commons/proper/lang/trunk@1077977 13f79535-47bb-0310-9956-ffa450edef68

src/main/java/org/apache/commons/lang3/EnumUtils.java

@@ -23,10 +23,12 @@ import java.util.List;
 import java.util.Map;
 
 /**
- * Utility library to provide helper methods for Java enums.
+ * <p>Utility library to provide helper methods for Java enums.</p>
  * 
  * <p>#ThreadSafe#</p>
+ * 
  * @author Apache Software Foundation
+ * @since 3.0
  * @version $Id$
  */
 public class EnumUtils {
@@ -39,11 +41,11 @@ public class EnumUtils {
     }
 
     /**
-     * Gets the <code>Map</code> of <code>enums</code> by name.
+     * <p>Gets the {@code Map} of enums by name.</p>
-     * <p>
-     * This method is useful when you need a map of enums by name.
      * 
-     * @param enumClass  the class of the <code>enum</code> to get, not null
+     * <p>This method is useful when you need a map of enums by name.</p>
+     *
+     * @param enumClass  the class of the enum to query, not null
      * @return the modifiable map of enum names to enums, never null
      */
     public static <E extends Enum<E>> Map<String, E> getEnumMap(Class<E> enumClass) {
@@ -55,11 +57,11 @@ public class EnumUtils {
     }
 
     /**
-     * Gets the <code>List</code> of <code>enums</code>.
+     * <p>Gets the {@code List} of enums.</p>
-     * <p>
-     * This method is useful when you need a list of enums rather than an array.
      * 
-     * @param enumClass  the class of the <code>enum</code> to get, not null
+     * <p>This method is useful when you need a list of enums rather than an array.</p>
+     *
+     * @param enumClass  the class of the enum to query, not null
      * @return the modifiable list of enums, never null
      */
     public static <E extends Enum<E>> List<E> getEnumList(Class<E> enumClass) {
@@ -67,16 +69,19 @@ public class EnumUtils {
     }
 
     /**
-     * Checks if the specified name is a valid <code>enum</code> for the class.
+     * <p>Checks if the specified name is a valid enum for the class.</p>
-     * <p>
-     * This method differs from {@link Enum#valueOf} in that checks if the name is
-     * a valid enum without needing to catch the exception.
      * 
-     * @param enumClass  the class of the <code>enum</code> to get, not null
+     * <p>This method differs from {@link Enum#valueOf} in that checks if the name is
-     * @param enumName   the enum name
+     * a valid enum without needing to catch the exception.</p>
+     *
+     * @param enumClass  the class of the enum to query, not null
+     * @param enumName   the enum name, null returns false
      * @return true if the enum name is valid, otherwise false
      */
     public static <E extends Enum<E>> boolean isValidEnum(Class<E> enumClass, String enumName) {
+        if (enumName == null) {
+            return false;
+        }
         try {
             Enum.valueOf(enumClass, enumName);
             return true;
@@ -86,16 +91,19 @@ public class EnumUtils {
     }
 
     /**
-     * Gets the <code>enum</code> for the class, returning <code>null</code> if not found.
+     * <p>Gets the enum for the class, returning {@code null} if not found.</p>
-     * <p>
-     * This method differs from {@link Enum#valueOf} in that it does not throw an exception
-     * for an invalid enum name.
      * 
-     * @param enumClass  the class of the <code>enum</code> to get, not null
+     * <p>This method differs from {@link Enum#valueOf} in that it does not throw an exception
-     * @param enumName   the enum name
+     * for an invalid enum name.</p>
-     * @return the enum or null if not found
+     *
+     * @param enumClass  the class of the enum to query, not null
+     * @param enumName   the enum name, null returns null
+     * @return the enum, null if not found
      */
     public static <E extends Enum<E>> E getEnum(Class<E> enumClass, String enumName) {
+        if (enumName == null) {
+            return null;
+        }
         try {
             return Enum.valueOf(enumClass, enumName);
         } catch (IllegalArgumentException ex) {

src/test/java/org/apache/commons/lang3/EnumUtilsTest.java

@@ -60,6 +60,16 @@ public class EnumUtilsTest extends TestCase {
         assertEquals(true, EnumUtils.isValidEnum(Traffic.class, "AMBER"));
         assertEquals(true, EnumUtils.isValidEnum(Traffic.class, "GREEN"));
         assertEquals(false, EnumUtils.isValidEnum(Traffic.class, "PURPLE"));
+        assertEquals(false, EnumUtils.isValidEnum(Traffic.class, null));
+    }
+
+    public void test_isEnum_nullClass() {
+        try {
+            EnumUtils.isValidEnum((Class<Traffic>) null, "PURPLE");
+            fail();
+        } catch (NullPointerException ex) {
+            // ok
+        }
     }
 
     public void test_getEnum() {
@@ -67,6 +77,16 @@ public class EnumUtilsTest extends TestCase {
         assertEquals(Traffic.AMBER, EnumUtils.getEnum(Traffic.class, "AMBER"));
         assertEquals(Traffic.GREEN, EnumUtils.getEnum(Traffic.class, "GREEN"));
         assertEquals(null, EnumUtils.getEnum(Traffic.class, "PURPLE"));
+        assertEquals(null, EnumUtils.getEnum(Traffic.class, null));
+    }
+
+    public void test_getEnum_nullClass() {
+        try {
+            EnumUtils.getEnum((Class<Traffic>) null, "PURPLE");
+            fail();
+        } catch (NullPointerException ex) {
+            // ok
+        }
     }
 
 }