Is rejecting `String.class` for a `Class<@Nullable String>` parameter intended?

[Artur-]

Summary

When a constructor (or method) takes a Class<T> type token and T is inferred as a @Nullable type via the diamond operator, NullAway rejects passing a plain class literal such as String.class:

[NullAway] incompatible types: Class<String> cannot be converted to Class<@Nullable String>

Since there is no way to write a Class<@Nullable String> literal in Java (String.class is always Class<String>, and nullness is not reified on a class token), I'd like to confirm whether this is intended behavior or a false positive that should be special-cased for Class<T> type tokens.

Minimal reproducer

package com.example;

import org.jspecify.annotations.NullMarked;
import org.jspecify.annotations.Nullable;

@NullMarked
public class ClassTokenRepro {

    static class Signal<T extends @Nullable Object> {
        private final Class<T> valueType;

        Signal(Class<T> valueType) {
            this.valueType = valueType;
        }
    }

    void caller() {
        // T = String -> param Class<String>, arg Class<String>: OK
        Signal<String> nonNull = new Signal<>(String.class);

        // T = @Nullable String -> param Class<@Nullable String>, arg Class<String>.
        // ERROR: [NullAway] incompatible types:
        //        Class<String> cannot be converted to Class<@Nullable String>
        Signal<@Nullable String> nullable = new Signal<>(String.class);
    }
}

An explicit type witness does not change the result (the parameter type is still Class<@Nullable String>):

Signal<@Nullable String> nullable = new Signal<@Nullable String>(String.class); // same error

The only way we found to satisfy the checker is an explicit type-use cast, which is erased at runtime to plain String.class:

Signal<@Nullable String> nullable = new Signal<>((Class<@Nullable String>) String.class); // OK

Why this looks questionable

• Class<T> is invariant, so strictly Class<String> is not a Class<@Nullable String>.
• However, a Class instance is a runtime type token. Nullness is not part of the runtime class, and there is no Class<@Nullable String> literal to produce. So for a Class<T> parameter, the nullness of T arguably carries no meaning and the only available argument is a Class<NonNullVersionOfT>.
• This makes any API of the shape Foo(Class<T> type) with T extends @Nullable Object effectively unusable with a nullable T without a cast.

When it changed

The change first appears in 0.13.2, which lines up with the "Initial handling of constructor diamond operators" work (PR #1464): before that the diamond construction was not analyzed, so the nullable case compiled.

Question

Is this the intended behavior for Class<T> (and similar runtime type-token) or just how it happens to work right now?

[cpovirk]

So far, JSpecify discussions have tended toward the idea that there is "no such thing" as a Class<@Nullable String>. [edit: That is, Class requires non-null type arguments.]

That's mainly because it would be an opportunity for "needless" mismatches: If you have a Class<@Nullable String> but need a Class<@NonNull String>, that's annoying, given that there is only one Class<String>, with no nullness truly associated with it, as you've noted.

But it's also worth noting: Class has methods like newInstance that return a T, so a call on a Class<@Nullable String> would produce a @Nullable String, which is unnecessarily general, or else we'd need to declare its return type as @NonNull T. The latter is doable, but:

It turns out that @NonNull T lets users solve this problem on their end: Instead of Class<T> valueType, you can declare Class<@NonNull T> valueType. This is the "projection" use case, the one case in null-marked code in which @NonNull is useful. Compare an API like Iterators.toArray(Iterator, Class). This is what we've recommended for cases like yours.

(There may or may not be NullAway-specific considerations on top of that, but that's what I'd suggest from the perspective of "pure JSpecify.")

[msridhar]

Very sorry for my slow response here. As to the original question:

When a constructor (or method) takes a Class<T> type token and T is inferred as a @Nullable type via the diamond operator, NullAway rejects passing a plain class literal such as String.class:

[NullAway] incompatible types: Class<String> cannot be converted to Class<@Nullable String>

Since there is no way to write a Class<@Nullable String> literal in Java (String.class is always Class<String>, and nullness is not reified on a class token), I'd like to confirm whether this is intended behavior or a false positive that should be special-cased for Class<T> type tokens.

This is indeed a bad error message. We still don't have a proper JDK model for Class (#950), which is probably the root cause. It's on the TODO list.

Does writing Class<@NonNull T> valueType as @cpovirk suggested address your issue for the time being?