58

I am doing a code inspection on Android Studio and the following warning pops up

Probable bugs
@NotNull/@Nullable problems 
Not annotated method overrides method annotated with @RecentlyNonNull

for the following code

@Override
public String toString() {
    return title;
}

enter image description here

I've seen @NonNull annotation before, which means that the return can never be a null, but what is @RecentlyNonNull? When do I use it?

Googling leads me to https://android.googlesource.com/platform/tools/metalava/+/fcb3d99ad3fe17a266d066b28ceb6c526f7aa415/stub-annotations/src/main/java/android/support/annotation/RecentlyNonNull.java

which does not provide any explanations.

The lint recommendation is to add that annotation in, but what does it do?

enter image description here

Pang
  • 9,564
  • 146
  • 81
  • 122
Angel Koh
  • 12,479
  • 7
  • 64
  • 91

2 Answers2

46

TL-DR
Consider @RecentlyNonNull as a @NonNull constraint and respect it in the same way in your code because @RecentlyNonNull is under the hood a @NonNull constraint.

Which means in the actual question, the OP should annotate the overrided method with @NonNull to be compliant with the @NonNull (transformed at build time into @RecentlyNonNull) defined in the super class.

The @RecentlyNonNull annotation doesn't make part of the SDK javadoc API.
It is not present in the support subpackage because it is not designed to be present in the source code. Instead, that is computed at build time and replace @NonNull if it is considered as "recent" in the stub source files.

As that is an internal processing, I don't have a simple and straight answer to your question but I may give you some pointers to understand better this annotation and its origin.

1) @RecentlyNonNull or @RecentlyNullable : annotations generated only in the stub source file.

In Android, the generated stub files and the generated documentation stubs don't bring the same level of information : @RecentlyNonNull or @RecentlyNullable may appear in stub files but never in documentation stubs that stick to stub files only.

You can find the information in the Options class source code : 

"$ARG_DOC_STUBS ", "Generate documentation stub source files for the API. Documentation stub " +
                "files are similar to regular stub files, but there are some differences. For example, in " +
                "the stub files, we'll use special annotations like @RecentlyNonNull instead of @NonNull to " +
                "indicate that an element is recently marked as non null, whereas in the documentation stubs we'll " +
                "just list this as @NonNull...

This googlesource document confirms that :

There are some annotations here which are not in the support library, such as @RecentlyNullable and @RecentlyNonNull. These are used only in the stubs to automatically mark code as recently annotated with null/non-null. We do not want these annotations in the source code; the recent-ness is computed at build time and injected into the stubs in place of the normal null annotations.

2) Annotations introduced for code linters and IDE warning/errors.

According to this blog these annotations take their origin from the Kotlin support and allows the compiler/linter to apply a severity level of the non null violation according to how recent is the non null constraint (recent : warning compilation, not recent : error compilation) :

Normally, nullability contract violations in Kotlin result in compilation errors. But to ensure the newly annotated APIs are compatible with your existing code, we are using an internal mechanism provided by the Kotlin compiler team to mark the APIs as recently annotated. Recently annotated APIs will result only in warnings instead of errors from the Kotlin compiler. You will need to use Kotlin 1.2.60 or later.

Our plan is to have newly added nullability annotations produce warnings only, and increase the severity level to errors starting in the following year's Android SDK. The goal is to provide you with sufficient time to update your code.

davidxxx
  • 125,838
  • 23
  • 214
  • 215
  • 2
    So should I treat RecentlyNonNull as something that can be null, or can't be null? – android developer Jun 16 '19 at 20:30
  • 3
    You should consider that the parameter, field or method return value annotated with is designed to not be null, similarly to `@NonNull` purpose(https://stackoverflow.com/questions/35604742/android-nonnull-usefulness) with the difference that this constraint was "recently" added. So linters could be more permissive (while you may change it) – davidxxx Jun 18 '19 at 18:55
  • 1
    So can I assume it's not null, then? – android developer Jun 18 '19 at 21:35
  • 2
    You should indeed. – davidxxx Jun 19 '19 at 06:13
  • 1
    Where is it used though? Only on libraries, right? Not on Android framework. Correct? I ask because for some reason it was mentioned on a video about what's new on Android : https://youtu.be/fnkFOhA7FC4?list=PLWz5rJ2EKKc9hqKx4qZWolQxy59Bt20t_&t=919 , and it's weird because it's not new at all... – android developer Jun 15 '20 at 16:52
  • Actually FusedLocationProviderClient.getLastLocation() marked as @RecentlyNonNull but in practice it can return null – Pavel Poley Aug 19 '21 at 09:13
0

Obviously it implies non-nullability, but I'm guessing the "recently" part implies that it just recently became annotated as such.

For example Object.toString did not use to be @NonNull, so now that it is, we say it is @RecentlyNonNull and whoever overrides it should be @NonNull as well. If you look at the source code the annotation is not present. This means some magic is behind this particular method being not nullable, and that is why is it marked as "recent".

SMMH
  • 310
  • 1
  • 13