Java Warning “Unchecked Cast”

1. Overview

Sometimes, when we compile our Java source files, we see “unchecked cast” warning messages printed by the Java compiler.

In this tutorial, we're going to take a closer look at the warning message. We'll discuss what this warning means, why we're warned, and how to solve the problem.

Some Java compilers suppress unchecked warnings by default.

Let's make sure we've enabled the compiler's option to print “unchecked” warnings before we look into this “unchecked cast” warning.

2. What Does the “unchecked cast” Warning Mean?

The “unchecked cast” is a compile-time warning. Simply put, we'll see this warning when casting a raw type to a parameterized type without type checking.

An example can explain it straightforwardly. Let's say we have a simple method to return a raw type Map:

public class UncheckedCast {
    public static Map getRawMap() {
        Map rawMap = new HashMap();
        rawMap.put("date 1", LocalDate.of(2021, Month.FEBRUARY, 10));
        rawMap.put("date 2", LocalDate.of(1992, Month.AUGUST, 8));
        rawMap.put("date 3", LocalDate.of(1976, Month.NOVEMBER, 18));
        return rawMap;
    }
...
}

Now, let's create a test method to call the method above method and cast the result to Map<String, LocalDate>:

@Test
public void givenRawMap_whenCastToTypedMap_shouldHaveCompilerWarning() {
    Map<String, LocalDate> castFromRawMap = (Map<String, LocalDate>) UncheckedCast.getRawMap();
    Assert.assertEquals(3, castFromRawMap.size());
    Assert.assertEquals(castFromRawMap.get("date 2"), LocalDate.of(1992, Month.AUGUST, 8));
}

The compiler has to allow this cast to preserve backward compatibility with older Java versions that do not support generics.

But if we compile our Java sources, the compiler will print the warning message. Next, let's compile and run our unit tests using Maven:

$ mvn clean test
...
[WARNING] .../src/test/java/com/baeldung/uncheckedcast/UncheckedCastUnitTest.java:[14,97] unchecked cast
  required: java.util.Map<java.lang.String,java.time.LocalDate>
  found:    java.util.Map
...
[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
...
[INFO] Results:
[INFO] 
[INFO] Tests run: 16, Failures: 0, Errors: 0, Skipped: 0
[INFO] 
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
...

As the Maven output shows, we've reproduced the warning successfully.

On the other hand, our test works without any problem even though we see the “unchecked cast” compiler warning.

We know the compiler won't warn us without reason. There must be some potential problem when we see this warning.

Let's figure it out.

3. Why Does the Java Compiler Warn Us?

Our test method works fine in the previous section, although we see the “unchecked cast” warning. That's because when we were casting the raw type Map to Map<String, LocalDate>, the raw Map contains only <String, LocalDate> entries. That is to say, the typecasting is safe.

To analyze the potential problem, let's change the getRawMap() method a little bit by adding one more entry into the raw type Map:

public static Map getRawMapWithMixedTypes() {
    Map rawMap = new HashMap();
    rawMap.put("date 1", LocalDate.of(2021, Month.FEBRUARY, 10));
    rawMap.put("date 2", LocalDate.of(1992, Month.AUGUST, 8));
    rawMap.put("date 3", LocalDate.of(1976, Month.NOVEMBER, 18));
    rawMap.put("date 4", new Date());
    return rawMap;
}

This time, we added a new entry to the Map with type <String, Date> in the method above.

Now, let's write a new test method to call the getRawMapWithMixedTypes() method:

@Test(expected = ClassCastException.class)
public void givenMixTypedRawMap_whenCastToTypedMap_shouldThrowClassCastException() {
    Map<String, LocalDate> castFromRawMap = (Map<String, LocalDate>) UncheckedCast.getRawMapWithMixedTypes();
    Assert.assertEquals(4, castFromRawMap.size());
    Assert.assertTrue(castFromRawMap.get("date 4").isAfter(castFromRawMap.get("date 3")));
}

If we compile and run the test, the “unchecked cast” warning message is printed again. Also, our test will pass.

However, since our test has the expected = ClassCastException.class argument, it means the test method has thrown a ClassCastException.

If we take a closer look at it, the ClassCastException isn't thrown on the line of casting the raw type Map to Map<String, LocalDate> although the warning message points to this line. Instead, the exception occurs when we get data with the wrong type by the key: castFromRawMap.get(“date 4”). 

If we cast a raw type collection containing data with the wrong types to a parameterized type collection, the ClassCastException won't be thrown until we load the data with the wrong type.

Sometimes, we may get the exception too late.

For instance, we get a raw type Map with many entries by calling our method, and then we cast it to a Map with parameterized type:

(Map<String, LocalDate>) UncheckedCast.getRawMapWithMixedTypes()

For each entry in the Map, we need to send the LocalDate object to a remote API. Until the time we encounter the ClassCastException, it's very likely that a lot of API calls have already been made. Depending on the requirement, some extra restore or data cleanup processes may be involved.

It'll be good if we can get the exception earlier so that we can decide how to handle the circumstance of entries with the wrong types.

As we understand the potential problem behind the “unchecked cast” warning, let's have a look at what we can do to solve the problem.

4. What Should We Do With the Warning?

4.1. Avoid Using Raw Types

Generics have been introduced since Java 5. If our Java environment supports generics, we should avoid using raw types. This is because using raw types will make us lose all the safety and expressiveness benefits of generics.

Moreover, we should search the legacy code and refactor those raw type usages to generics.

However, sometimes we have to work with some old libraries. Methods from those old external libraries may return raw type collections.

Calling those methods and casting to parameterized types will produce the “unchecked cast” compiler warning. But we don't have control over an external library.

Next, let's have a look at how to handle this case.

4.2. Suppress the “unchecked” Warning

If we can't eliminate the “unchecked cast” warning and we're sure that the code provoking the warning is typesafe, we can suppress the warning using the SuppressWarnings(“unchecked”) annotation.

When we use the @SuppressWarning(“unchecked”) annotation, we should always put it on the smallest scope possible.

Let's have a look at the remove() method from the ArrayList class as an example:

public E remove(int index) {
    Objects.checkIndex(index, size);
    final Object[] es = elementData;
                                                              
    @SuppressWarnings("unchecked") E oldValue = (E) es[index];
    fastRemove(es, index);
                                                              
    return oldValue;
}

4.3. Doing Typesafe Check Before Using the Raw Type Collection

As we've learned, the @SuppressWarning(“unchecked”) annotation merely suppresses the warning message without actually checking if the cast is typesafe.

If we're not sure if casting a raw type is typesafe, we should check the types before we really use the data so that we can get the ClassCastException earlier.

5. Conclusion

In this article, we've learned what an “unchecked cast” compiler warning means.

Further, we've addressed the cause of this warning and how to solve the potential problem.

As always, the code in this write-up is all available over on GitHub.