Please replace jakarta.annotation:jakarta.annotation-api with jspecify

[vlsi]

Looks like the project uses jakarta.annotation:jakarta.annotation-api for nullability annotations, however, there are several issues with that:

1. jakarta has problematic license: it is a mix of EPL 2.0, GPL2 w CPE (see https://repo1.maven.org/maven2/jakarta/annotation/jakarta.annotation-api/3.0.0/jakarta.annotation-api-3.0.0.pom). Apache Software foundation legals do not appreciate those types of licenses, see https://www.apache.org/legal/resolved.html#category-x

2. There's a standard way of handling nullability: https://jspecify.dev/
   It covers nullability much better, and the tooling is much better there.

The rule of thumb with JSpecify is as follows:
a) Prefer non-null by default, thus in 99% of the cases you should NOT use @Nonnull.
b) Mark every package as @NullMarked: create package-info.java and mark it with @NullMarked. There's no "package with subpackages" since a subpackage might come in a different jar which might have never heard of jspecify
c) @Nullable is a type annotation, so it should be placed closer to a type. So you should prefer public @Nullable String getShortOpt() rather than @Nullable public String getShortOpt(). At the end of the day, what does "nullable method" mean?

PS I identified the issue when upgrading ph-css in JMeter

[phax]

Thanks for the information. Switching to jspecify does make sense, but adding a package-info file to each package adds a lot of overhead. I like to have it per usage - makes my life easier.
Will implement it for a 12.1 which requires a lot of follow-up releases as well, so it will take some time...

[vlsi]

adding a package-info file to each package adds a lot of overhead

Frankly, initially I thought the same, however, now I think having a per-package package-info.java is better since Java has no "subpackages" concept (taking into account that one of the subpackages might locate in a different Java module)

I like to have it per usage

Could you clarify what you mean by that?
Do you mean per-class @NullMarked?

[phax]

Na - way simpler. I already assigned separate Nullable and Nonnull to basically all parameters and return types - I will stick with that. Makes it imho ever easier to read (and less error prone compared to forgetting the package-info file in one of the packages). But in the end, it should give the same - if not even a more exact - result. Especially the Nonnull assumption onn Generic types is de facto impossible to guarantee when you develop a library - for applications this may be more defined.

[phax]

Will be part of 12.1.0 release

[vlsi]

Especially the Nonnull assumption onn Generic types is de facto impossible to guarantee when you develop a library

I’m not sure what you mean here. I’ve annotated pgjdbc and apache calcite with full machine verification of nullness including generics.
Kotlin compiles generics with proper nullability annotations as well, so generic types can be annotated including libraries

[phax]

Okay, lets use the java.util.List type for example - as the designer of the interface I have no clue, whether it is used with Nullable or NonNull types.
Or is the recommendation in this case to assume Nullable and an implementing class (like e.g. ArrayList would add the @NonNull to its implementation definition (as in implements List<@Nonnull T>)?

[vlsi]

For List, it is reasonable to go with interface List<T extends @Nullable Object>. It would allow clients to use it for both nullable and non-nullable values. If a client wants a list of non-nullable Lock instances, they could go for class LockList implements List<Lock> (assuming non-null by default which is the recommended by checkerframework and jspecify nullmarked).

Sometimes the interface wants to forbid nullable types. For instance, a custom map-like interface might want forbidding nullable keys, so they could explicitly declare it: interface MyMap<Key extends @NonNull Object, Value>. It would forbid clients to specialise the interface with nullable keys.

In general, you are right: the interface designer should think and decide if nullable types should be allowed or not just like they decide on the wildcards and so on.

Does that make sense? Do you have any ph-commons-specific question?

[vlsi]

By the way, when jspecify treats interface List<T> as if it was interface List<T extends @Nullable Object>, so it is not like you have to add those extends @Nullable Object everywhere