Java instanceof Operator

1. Introduction

In this quick tutorial, we’ll learn about the instanceof operator in Java.

2. What Is the instanceof Operator?

instanceof is a binary operator we use to test if an object is of a given type. The result of the operation is either true or false. It’s also known as a type comparison operator because it compares the instance with the type.

Before casting an unknown object, the instanceof check should always be used. Doing this helps to avoid a ClassCastException at runtime.

The instanceof operator’s basic syntax is:

(object) instanceof (type)

Now let’s see a basic example for the instanceof operator. First, we’ll create a class Round:

public class Round {
    // implementation details
}

Next, we’ll create a class Ring that extends Round:

public class Ring extends Round {
    // implementation details
}

We can use instanceof to check if an instance of Ring is of Round type:

@Test
void givenWhenInstanceIsCorrect_thenReturnTrue() {
    Ring ring = new Ring();
    assertTrue(ring instanceof Round);
}

3. How Does the instanceof Operator Work?

The instanceof operator works on the principle of the is-a relationship. The concept of an is-a relationship is based on class inheritance or interface implementation.

To demonstrate this, we’ll create a Shape interface:

public interface Shape {
    // implementation details
}

We’ll also create a class Circle, which implements the Shape interface and also extends the Round class:

public class Circle extends Round implements Shape {
    // implementation details
}

The instanceof result will be true if the object is an instance of the type:

@Test
void givenWhenObjectIsInstanceOfType_thenReturnTrue() {
    Circle circle = new Circle();
    assertTrue(circle instanceof Circle);
}

It will also be true if the object is an instance of a subclass of the type:

@Test
void givenWhenInstanceIsOfSubtype_thenReturnTrue() {
    Circle circle = new Circle();
    assertTrue(circle instanceof Round);
}

If the type is an interface, it will return true if the object implements the interface:

@Test
void givenWhenTypeIsInterface_thenReturnTrue() {
    Circle circle = new Circle();
    assertTrue(circle instanceof Shape);
}

The instanceof operator can’t be used if there’s no relationship between the object that’s being compared and the type it’s being compared with.

We’ll create a new class, Triangle, that implements Shape, but has no relationship with Circle:

public class Triangle implements Shape {
    // implementation details
}

Now if we use instanceof to check if a Circle is an instance of Triangle:

@Test
void givenWhenComparingClassInDiffHierarchy_thenCompilationError() {
    Circle circle = new Circle();
    assertFalse(circle instanceof Triangle);
}

We’ll get a compilation error because there’s no relationship between the Circle and Triangle classes:

java.lang.Error: Unresolved compilation problem:
  Incompatible conditional operand types Circle and Triangle

4. Using instanceof With the Object Type

In Java, every class implicitly inherits from the Object class. Therefore, using the instanceof operator with the Object type will always evaluate to true:

@Test
void givenWhenTypeIsOfObjectType_thenReturnTrue() {
    Thread thread = new Thread();
    assertTrue(thread instanceof Object);
}

5. Using the instanceof Operator When an Object Is null

If we use the instanceof operator on any object that’s null, it returns false. We also don’t need a null check when using an instanceof operator.

@Test
void givenWhenInstanceValueIsNull_thenReturnFalse() {
    Circle circle = null;
    assertFalse(circle instanceof Round);
}

6. instanceof and Generics

Instance tests and casts depend on inspecting the type information at runtime. Therefore, we can’t use instanceof along with erased generic types.

For instance, if we try to compile the following snippet:

public static <T> void sort(List<T> collection) {
    if (collection instanceof List<String>) {
        // sort strings differently
    }
        
    // omitted
}

Then we get this compilation error:

error: illegal generic type for instanceof
        if (collection instanceof List<String>) {
                                      ^

Technically speaking, we’re only allowed to use instanceof along with reified types in Java. A type is reified if its type information is present at runtime.

The reified types in Java are as follows:

• Primitive types, like int
• Non-generic classes and interfaces, like String or Random
• Generic types in which all types are unbounded wildcards, like Set<?> or Map<?, ?>
• Raw types, like List or HashMap
• Arrays of other reifiable types, like String[], List[], or Map<?, ?>[]

Because generic type parameters aren’t reified, we can’t use them either:

public static <T> boolean isOfType(Object input) {
    return input instanceof T; // won't compile
}

However, it’s possible to test against something like List<?>:

if (collection instanceof List<?>) {
    // do something
}

7. Stream API – Filtering Types Using instanceof Before Casting

One great feature that Java 8 has brought us is the Stream API. We often convert a type A collection to a type B collection using Stream‘s map() method.

If the type conversion is done by typecasting, we may want to check the types before performing the typecasting to avoid the ClassCastException.

Next, let’s see an example. Let’s say we have a Stream of Round instances:

Stream<Round> roundStream = Stream.of(new Ring(), new Ring(), new Circle());

As the code above shows, the roundStream object contains two Ring objects and one Circle instance.

Now, if we convert roundStream to a list of Ring without checking the types, ClassCastException will be raised as a Circle is not a Ring:

@Test
void givenWhenStream_whenCastWithoutInstanceOfChk_thenGetException() {
    Stream<Round> roundStream = Stream.of(new Ring(), new Ring(), new Circle());
    assertThrows(ClassCastException.class, () -> roundStream.map(it -> (Ring) it).collect(Collectors.toList()));
}

However, if we filter Ring objects before the map() call, we’ll get the expected list:

@Test
void givenWhenStream_whenCastAfterInstanceOfChk_thenGetExpectedResult() {
    Stream<Round> roundStream = Stream.of(new Ring(), new Ring(), new Circle());
    List<Ring> ringList = roundStream.filter(it -> it instanceof Ring).map(it -> (Ring) it).collect(Collectors.toList());
    assertEquals(2, ringList.size());
}

8. Conclusion

In this brief article, we learned about the instanceof operator and how to use it.