Support enum parameters with custom labels

With this change, an enum class can implement toString()
to control how it is presented in the user interface.

Author: ctrueden

pom.xml

@@ -10,7 +10,7 @@
 	</parent>
 
 	<artifactId>scijava-common</artifactId>
-	<version>2.96.1-SNAPSHOT</version>
+	<version>2.97.0-SNAPSHOT</version>
 
 	<name>SciJava Common</name>
 	<description>SciJava Common is a shared library for SciJava software. It provides a plugin framework, with an extensible mechanism for service discovery, backed by its own annotation processor, so that plugins can be loaded dynamically. It is used by downstream projects in the SciJava ecosystem, such as ImageJ and SCIFIO.</description>

src/main/java/org/scijava/convert/DefaultConverter.java

@@ -135,7 +135,7 @@ public Object convert(final Object src, final Type dest) {
 			// special case for conversion to enum
 			if (saneDest.isEnum()) {
 				try {
-					return Types.enumValue(s, saneDest);
+					return Types.enumFromString(s, saneDest);
 				}
 				catch (final IllegalArgumentException exc) {
 					// NB: No action needed.

src/main/java/org/scijava/util/Types.java

@@ -780,8 +780,10 @@ public static <T> T cast(final Object src, final Class<T> dest) {
 	}
 
 	/**
-	 * Converts the given string value to an enumeration constant of the specified
-	 * type.
+	 * Converts the given string <em>value</em> to an enumeration constant of the
+	 * specified type. For example, {@code enumValue("APPLE", Fruit.class)}
+	 * returns {@code Fruit.APPLE} if such a value is among those of the
+	 * requested enum class.
 	 *
 	 * @param name The value to convert.
 	 * @param dest The type of the enumeration constant.
@@ -798,6 +800,60 @@ public static <T> T enumValue(final String name, final Class<T> dest) {
 		return typedResult;
 	}
 
+	/**
+	 * Converts the given string <em>label</em> to an enumeration constant of the
+	 * specified type. An enum label is the string returned by the enum constant's
+	 * {@link Object#toString()} method. For example,
+	 * {@code enumFromLabel("Apple", Fruit.class)} returns {@code Fruit.APPLE} if
+	 * {@code Fruit.APPLE.toString()} is implemented to return {@code "Apple"}.
+	 *
+	 * @param label The {@code toString()} result of the desired enum value.
+	 * @param dest The type of the enumeration constant.
+	 * @return The matching enumeration constant.
+	 * @throws IllegalArgumentException if the type is not an enumeration type, or
+	 *           has no constant with the given label.
+	 */
+	public static <T> T enumFromLabel(final String label, final Class<T> dest) {
+		final T[] values = dest.getEnumConstants();
+		if (values == null) throw iae("Not an enum type: " + name(dest));
+		for (T value : values) {
+			if (Objects.equals(label, value.toString())) return value;
+		}
+		throw iae("Enum class " + dest.getName() + " has no such label: " + label);
+	}
+
+	/**
+	 * Converts the given string value or label to an enumeration constant of the
+	 * specified type.
+	 * <p>
+	 * If the string matches one of the enum values directly, that value will be
+	 * returned via {@link #enumValue(String, Class)}. Otherwise, the result of
+	 * {@link #enumFromLabel} is returned.
+	 * </p>
+	 *
+	 * @param s The name or label of the desired enum value.
+	 * @param dest The type of the enumeration constant.
+	 * @return The matching enumeration constant.
+	 * @throws IllegalArgumentException if the type is not an enumeration type,
+	 *           or has no such constant with the given name nor label.
+	 */
+	public static <T> T enumFromString(final String s, final Class<T> dest) {
+		if (!dest.isEnum()) throw iae("Not an enum type: " + name(dest));
+		try {
+			return enumValue(s, dest);
+		}
+		catch (final IllegalArgumentException exc) {
+			// NB: No action needed.
+		}
+		try {
+			return enumFromLabel(s, dest);
+		}
+		catch (final IllegalArgumentException exc) {
+			// NB: No action needed.
+		}
+		throw iae("Enum class " + dest.getName() + " has no such value nor label: " + s);
+	}
+
 	/**
 	 * Creates a new {@link ParameterizedType} of the given class together with
 	 * the specified type arguments.

src/test/java/org/scijava/util/TypesTest.java

@@ -593,7 +593,7 @@ public void testEnumValue() {
 	/** Tests {@link Types#enumValue(String, Class)} for invalid value. */
 	@Test(expected = IllegalArgumentException.class)
 	public void testEnumValueNoConstant() {
-		Types.enumValue("NONE", Words.class);
+		Types.enumValue("OMG", Words.class);
 	}
 
 	/** Tests {@link Types#enumValue(String, Class)} for non-enum class. */
@@ -602,6 +602,38 @@ public void testEnumValueNonEnum() {
 		Types.enumValue("HOOYAH", String.class);
 	}
 
+	/** Tests {@link Types#enumFromLabel(String, Class)}. */
+	@Test
+	public void testEnumFromLabel() {
+		final Words foo = Types.enumFromLabel("Foo", Words.class);
+		assertSame(Words.FOO, foo);
+		final Words bar = Types.enumFromLabel("Bar", Words.class);
+		assertSame(Words.BAR, bar);
+		final Words fubar = Types.enumFromLabel("OMG", Words.class);
+		assertSame(Words.FUBAR, fubar);
+	}
+
+	/** Tests {@link Types#enumFromString(String, Class)}. */
+	@Test
+	public void testEnumFromString() {
+		{
+			final Words foo = Types.enumFromString("FOO", Words.class);
+			assertSame(Words.FOO, foo);
+			final Words bar = Types.enumFromString("BAR", Words.class);
+			assertSame(Words.BAR, bar);
+			final Words fubar = Types.enumFromString("FUBAR", Words.class);
+			assertSame(Words.FUBAR, fubar);
+		}
+		{
+			final Words foo = Types.enumFromString("Foo", Words.class);
+			assertSame(Words.FOO, foo);
+			final Words bar = Types.enumFromString("Bar", Words.class);
+			assertSame(Words.BAR, bar);
+			final Words fubar = Types.enumFromString("OMG", Words.class);
+			assertSame(Words.FUBAR, fubar);
+		}
+	}
+
 	/** Tests {@link Types#parameterize(Class, Map)}. */
 	@Test
 	public void testParameterizeMap() {
@@ -644,7 +676,18 @@ private static class ComplexThing<T extends Serializable & Cloneable> extends
 
 	/** Enumeration for testing conversion to enum types. */
 	public static enum Words {
-		FOO, BAR, FUBAR
+		FOO("Foo"), BAR("Bar"), FUBAR("OMG");
+
+		private final String label;
+
+		private Words(final String label) {
+			this.label = label;
+		}
+
+		@Override
+		public String toString() {
+			return label;
+		}
 	}
 
 	private interface TestTypes<T extends Number> {