From 1e2b9eb078efbe3de0ca29ff2f0b3e2a625cbfaf Mon Sep 17 00:00:00 2001
From: Stephen Colebourne <scolebourne@apache.org>
Date: Fri, 4 Mar 2011 14:46:03 +0000
Subject: [PATCH] Javadoc and clarify null handling

git-svn-id: https://svn.apache.org/repos/asf/commons/proper/lang/trunk@1077977 13f79535-47bb-0310-9956-ffa450edef68
---
 .../org/apache/commons/lang3/EnumUtils.java   | 52 +++++++++++--------
 .../apache/commons/lang3/EnumUtilsTest.java   | 20 +++++++
 2 files changed, 50 insertions(+), 22 deletions(-)

diff --git a/src/main/java/org/apache/commons/lang3/EnumUtils.java b/src/main/java/org/apache/commons/lang3/EnumUtils.java
index 800ad0627..8baec19ff 100644
--- a/src/main/java/org/apache/commons/lang3/EnumUtils.java
+++ b/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>
-     * This method is useful when you need a map of enums 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.</p>
      *
-     * @param enumClass  the class of the <code>enum</code> to get, not null
+     * @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>
-     * This method is useful when you need a list of enums rather than an array.
+     * <p>Gets the {@code List} of enums.</p>
+     * 
+     * <p>This method is useful when you need a list of enums rather than an array.</p>
      *
-     * @param enumClass  the class of the <code>enum</code> to get, not null
+     * @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>
-     * This method differs from {@link Enum#valueOf} in that checks if the name is
-     * a valid enum without needing to catch the exception.
+     * <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.</p>
      *
-     * @param enumClass  the class of the <code>enum</code> to get, not null
-     * @param enumName   the enum name
+     * @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>
-     * This method differs from {@link Enum#valueOf} in that it does not throw an exception
-     * for an invalid enum name.
+     * <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.</p>
      *
-     * @param enumClass  the class of the <code>enum</code> to get, not null
-     * @param enumName   the enum name
-     * @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) {
diff --git a/src/test/java/org/apache/commons/lang3/EnumUtilsTest.java b/src/test/java/org/apache/commons/lang3/EnumUtilsTest.java
index 6b3f7416c..7fd8a0a4f 100644
--- a/src/test/java/org/apache/commons/lang3/EnumUtilsTest.java
+++ b/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
+        }
     }
 
 }