1. Overview
We see enumerations in almost every application. These include order status codes, like DRAFT and PROCESSING, and web error codes, like 400, 404, 500, 501, etc. Whenever we see enumerated data in the domain, we’ll see Enum for it in our application. We can use the data in an incoming request and find that enum. For example, we can map web error 400 to BAD_REQUEST.
As such, we need logic to search the enum by criteria. This could be its name or its value. Alternatively, it could even be an arbitrary integer code.
In this tutorial, we’ll learn how to search an enum by criteria. In addition, we’ll also explore different ways to return the enum found.
2. Searching an Enum by Name
To begin with, we know that an enum type is a special data type. It enables a variable to be a set of predefined constants. Let’s define an enum for direction:
public enum Direction {
EAST, WEST, SOUTH, NORTH;
}
The name of the enum value is constant. So for instance, the name of Direction.EAST is EAST. Now we can search the direction by its name. It’s a good idea to implement a case-insensitive search. As a result, East, east, and EAST would all map to Direction.EAST. Let’s add the following method to Direction enum:
public static Direction findByName(String name) {
Direction result = null;
for (Direction direction : values()) {
if (direction.name().equalsIgnoreCase(name)) {
result = direction;
break;
}
}
return result;
}
In this implementation, we’re returning null if we don’t find the enum for the given name. It’s up to us how we treat the not-found scenario. One option is that we can return a default enum value. Conversely, we can throw an exception. We’ll see more examples of searching the enum shortly. Now let’s test our search logic. First, the positive scenario:
@Test
public void givenWeekdays_whenValidDirectionNameProvided_directionIsFound() {
Direction result = Direction.findByName("EAST");
assertThat(result).isEqualTo(Direction.EAST);
}
At the end of this article, we’ll provide the link to the complete code implementation, but right now, we’re going to focus on the code snippets. Here we searched the direction for the name “EAST” and we expect to get Direction.EAST. As mentioned earlier, we know that the search is not case sensitive, so we should get the same result for the name “east” or “East”. Let’s validate our expectations:
@Test
public void givenWeekdays_whenValidDirectionNameLowerCaseProvided_directionIsFound() {
Direction result = Direction.findByName("east");
assertThat(result).isEqualTo(Direction.EAST);
}
We could also add one more test to validate if the search method returns the same result for the name “East”. The following test would illustrate that we get the same result for the name “East”.
@Test public void givenWeekdays_whenValidDirectionNameLowerCaseProvided_directionIsFound() {
Direction result = Direction.findByName("East");
assertThat(result).isEqualTo(Direction.EAST);
}
3. Searching an Enum by Value
Now let’s define an enum for the days in a week. This time, let’s provide a value along with the name. In fact, we can define any data member(s) inside the enum, and then use it for our application logic. Here’s the code for the Weekday enum:
public Weekday {
MONDAY("Monday"),
TUESDAY("Tuesday"),
// ...
SUNDAY("Sunday"),
;
private final String value;
Weekday(String value) {
this.value = value;
}
}
Next, let’s implement the search by the value. So for “Monday” we should get Weekday.MONDAY. Let’s add the following method to the enum:
public static Weekday findByValue(String value) {
Weekday result = null;
for (Weekday day : values()) {
if (day.getValue().equalsIgnoreCase(value)) {
result = day;
break;
}
}
return result;
}
Here we’re iterating over the constants of the enum and then comparing the value input to the value member of the enum. As mentioned earlier, we’re ignoring the case of the value. Now we can test it:
@Test
public void givenWeekdays_whenValidWeekdayValueProvided_weekdayIsFound() {
Weekday result = Weekday.findByValue("Monday");
assertThat(result).isEqualTo(Weekday.MONDAY);
}
If we don’t provide a valid value, we’ll get null in return. Let’s validate this:
@Test
public void givenWeekdays_whenInvalidWeekdayValueProvided_nullIsReturned() {
Weekday result = Weekday.findByValue("mon");
assertThat(result).isNull();
}
The search doesn’t always need to be by string values. That would be quite inconvenient, as we would have to convert the input into a string first and then pass it to the search method. Now let’s see how to search by non-string values, such as an integer value.
4. Searching an Enum by Integer Value
Let’s define a new enum called Month. Here’s the code for the Month enum:
public enum Month {
JANUARY("January", 1),
FEBRUARY("February", 2),
// ...
DECEMBER("December", 12),
;
private final String value;
private final int code;
Month(String value, int code) {
this.value = value;
this.code = code;
}
}
We can see that the month enum has two members, the value and the code, with the code being an integer value. Let’s implement the logic to search the months by their code:
public static Optional<Month> findByCode(int code) {
return Arrays.stream(values()).filter(month -> month.getCode() == code).findFirst();
}
This search looks a little different from the previous searches because we’ve used Java 8 features to demonstrate another way to implement the search. Here, instead of returning the enum itself, we’ll return an Optional value of the enum. Similarly, instead of null, we’ll return an empty Optional. So if we search a month for code 1, we should get Month.JANUARY. Let’s validate this with a test:
@Test
public void givenMonths_whenValidMonthCodeProvided_optionalMonthIsReturned() {
Optional<Month> result = Month.findByCode(1);
assertThat(result).isEqualTo(Optional.of(Month.JANUARY));
}
For invalid code values, we should get an empty Optional. Let’s validate this with a test as well:
@Test
public void givenMonths_whenInvalidMonthCodeProvided_optionalEmptyIsReturned() {
Optional<Month> result = Month.findByCode(0);
assertThat(result).isEmpty();
}
There may be cases where we want to implement a stricter search. As such, we wouldn’t tolerate invalid inputs and we’d throw exceptions to demonstrate this.
5. Exceptions Thrown from Search Methods
Instead of returning null or empty Optional value, we may want to throw an exception. Which exception to throw totally depends on the needs of the system. We’ll choose to throw an IllegalArgumentException if we don’t find the enum. Here’s the code for the search method:
public static Month findByValue(String value) {
return Arrays.stream(values()).filter(month -> month.getValue().equalsIgnoreCase(value)).findFirst().orElseThrow(IllegalArgumentException::new);
}
We can see again that we’re using the Java 8 style while throwing the exception. Let’s validate it with a test:
@Test
public void givenMonths_whenInvalidMonthValueProvided_illegalArgExIsThrown() {
assertThatIllegalArgumentException().isThrownBy(() -> Month.findByValue("Jan"));
}
The search methods demonstrated in this article aren’t the only way to do it, but they represent the most common options. We can also tweak these implementations to suit our system’s needs.
6. Conclusion
In this article, we learned various ways to search enums. We also discussed the different ways to return the results. Finally, we backed those implementations with solid unit tests.
As always, the code relating to this article is available over on GitHub.