[JAVA-2641] Add JSR-305-compatible NonNull annotations to the driver API Created: 18/Oct/17  Updated: 29/Oct/23  Resolved: 20/Mar/18

Status: Closed
Project: Java Driver
Component/s: API
Affects Version/s: None
Fix Version/s: 3.7.0

Type: New Feature Priority: Major - P3
Reporter: Jeffrey Yemin Assignee: Jeffrey Yemin
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Problem/Incident
causes JAVA-2886 Incorrect JSR-305 nullability annotat... Closed
Related
is related to JAVA-2901 ChangeStreamDocument.getFullDocument ... Closed
is related to JAVA-2814 Add JSR-305-compatible NonNull annota... Backlog
Epic Link: Kotlin Support

 Description   

Annotating the public API with NonNull annotations will allow tools like IntelliJ and other JVM languages like Kotlin to enforce constraints on application code that uses the driver.

See for an example the recent support for null-safety added to Spring Framework 5.0 here.

A couple of strange things about JSR-305 that need to be considered:

  • It was never actually approved and incorporated into the JDK. Rather, it's available at the following Maven coordinates: com.google.code.findbugs:jsr305:3.0.2
  • The package javax.annotation is exported by the java.xml.ws.annotation module in Java 9, and, though it's deprecated and slated for removal, I think that will conflict with any other module that also contains classes in the same package (like the JSR-305 one). However, this doesn't appear to affect Spring, perhaps because the JSR-305 jar file is a compileOnly dependency.


 Comments   
Comment by Githook User [ 20/Mar/18 ]

Author:

{'email': 'ross.lawley@gmail.com', 'name': 'Ross Lawley', 'username': 'rozza'}

Message: Moved JSR-305 compatible annotation to driver-core

JAVA-2641
Branch: master
https://github.com/mongodb/mongo-java-driver/commit/8e9a543c10f24b8881a9cac048fe60d1bc762cbc

Comment by Githook User [ 20/Mar/18 ]

Author:

{'email': 'jeff.yemin@10gen.com', 'name': 'Jeff Yemin', 'username': 'jyemin'}

Message: JAVA-2641: Add missing @Nullable annotation to UpdateResult#getUpsertedId
Branch: master
https://github.com/mongodb/mongo-java-driver/commit/2b12bbea2b670cf7db742b529fbc47da0314dccd

Comment by Githook User [ 20/Mar/18 ]

Author:

{'email': 'jeff.yemin@10gen.com', 'name': 'Jeff Yemin', 'username': 'jyemin'}

Message: JAVA-2641: Change jsr305 dependendency from optional to compileOnly
Branch: master
https://github.com/mongodb/mongo-java-driver/commit/1139899d6738b21633da878d93edb8d75774f25b

Comment by Githook User [ 19/Mar/18 ]

Author:

{'email': 'jeff.yemin@10gen.com', 'name': 'Jeff Yemin', 'username': 'jyemin'}

Message: JAVA-2641: Make com.mongodb.client packages a NonNullApi and add Nullable annotations to methods and parameters that require it
Branch: master
https://github.com/mongodb/mongo-java-driver/commit/28c1c46e62f7adf8f974667413bd7e84480f785b

Comment by Githook User [ 19/Mar/18 ]

Author:

{'email': 'jeff.yemin@10gen.com', 'name': 'Jeff Yemin', 'username': 'jyemin'}

Message: JAVA-2641: Make com.mongodb a NonNullApi and add Nullable annotations to methods and parameters that require it
Branch: master
https://github.com/mongodb/mongo-java-driver/commit/ab4a6a17c9756a0232e037d221d503c2640eac00

Comment by Githook User [ 19/Mar/18 ]

Author:

{'email': 'jeff.yemin@10gen.com', 'name': 'Jeff Yemin', 'username': 'jyemin'}

Message: JAVA-2641: Make com.mongodb.async.client and com.mongodb.async.client.gridfs a NonNullApi and add Nullable annotations to methods and parameters that require it
Branch: master
https://github.com/mongodb/mongo-java-driver/commit/4379ce188acbd18614a10b2805c0bc63af4d484c

Comment by Githook User [ 19/Mar/18 ]

Author:

{'email': 'jeff.yemin@10gen.com', 'name': 'Jeff Yemin', 'username': 'jyemin'}

Message: JAVA-2641: Make com.mongodb.client.internal a NonNullApi and add Nullable annotations to methods and parameters that require it
Branch: master
https://github.com/mongodb/mongo-java-driver/commit/2de302ff1d7c2abed67662f4d1d74ed6a83c5961

Comment by Githook User [ 19/Mar/18 ]

Author:

{'email': 'jeff.yemin@10gen.com', 'name': 'Jeff Yemin', 'username': 'jyemin'}

Message: JAVA-2641: Make com.mongodb.client and com.mongodb.client.gridfs a NonNullApi and add Nullable annotations to methods and parameters that require it
Branch: master
https://github.com/mongodb/mongo-java-driver/commit/de2370c0b8651201b2c028669df6c1bbf8bc37c1

Comment by Githook User [ 19/Mar/18 ]

Author:

{'email': 'jeff.yemin@10gen.com', 'name': 'Jeff Yemin', 'username': 'jyemin'}

Message: JAVA-2641: Add custom annotations using JSR-305 meta-annotatios
Branch: master
https://github.com/mongodb/mongo-java-driver/commit/2d6c0691c8cfdf2f872f7405f3ce4f17da3c84b0

Comment by Mark Paluch [ 27/Dec/17 ]

Spring Framework's (Non)Nullability annotations are intended primarily to assist developers during development time within their IDE. Our annotations are annotated with proper JSR-305 annotations to comply with JSR-305's ideas. JSR-305 is not required to be on the classpath during development-time/compile-time/runtime of user-code. Our public API defaults to non-null by annotating packages with @NonNullApi. Exceptions to non-nullability defaults (parameters, method return, fields) are annotated with @Nullable. @NonNull is used for rather punctual non-nullability indications without requiring to alter a whole package.

We have additional runtime support based on our annotations to allow/reject null values in method arguments and return values on controller and repository API if user-code is annotated using Spring Framework's annotations. If JSR-305 annotations are on the class-path, then we can leverage these, too (e.g. user-defined meta-annotations), but that's totally optional.

We're expressing nullability constraints using Spring Framework's annotations on our public API. We're using Lombok's @Nonnull in combination with @RequiredArgsConstructor to generate non-null checks.

Comment by Jeffrey Yemin [ 27/Dec/17 ]

mpaluch@paluch.biz cstrobl Can either of you elaborate on the thinking behind taking the JSR-305 dependency in the Spring Framework, given the issues with the Java 9 module system (and perhaps OSGi)? And why are the nullability-related Lombok annotations used in some places, but quite sparingly? Was any thought given to more pervasive use of run-time null checks using code generation, as Lombok supports with its annotation processor?

Comment by Jeffrey Yemin [ 08/Dec/17 ]

A few additional notes:

So one option is to emulate Spring's technique, which centralizes the JSR-305 references to just a few annotations.

Generated at Thu Feb 08 08:57:44 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.