From 6a4a183c09cd501f6e613bf739498c8f1f0c5c32 Mon Sep 17 00:00:00 2001 From: Gavin King Date: Fri, 20 Sep 2024 12:45:10 +0200 Subject: [PATCH] jakarta.annotation.Nonnull implies optional=false see issue #614 Signed-off-by: Gavin King --- .../main/java/jakarta/persistence/Basic.java | 8 +++-- .../java/jakarta/persistence/ManyToOne.java | 8 +++-- .../java/jakarta/persistence/OneToOne.java | 8 +++-- .../ch11-metadata-for-or-mapping.adoc | 34 ++++++++++++------- 4 files changed, 40 insertions(+), 18 deletions(-) diff --git a/api/src/main/java/jakarta/persistence/Basic.java b/api/src/main/java/jakarta/persistence/Basic.java index 8f2ddc30..3bc87c58 100644 --- a/api/src/main/java/jakarta/persistence/Basic.java +++ b/api/src/main/java/jakarta/persistence/Basic.java @@ -97,8 +97,12 @@ * (Optional) Specifies whether the value of the field or * property may be null. * - *

This is a hint and is disregarded for primitive types; - * it may be used in schema generation to infer that the + *

If the annotated field or property is of primitive type, + * or if it is also annotated {@code @jakarta.annotation.Nonnull}, + * then {@code optional=false} is implied, and the value of this + * annotation member is ignored. + * + *

May be used in schema generation to infer that the * mapped column is {@link Column#nullable not null}. * *

If not specified, defaults to {@code true}. diff --git a/api/src/main/java/jakarta/persistence/ManyToOne.java b/api/src/main/java/jakarta/persistence/ManyToOne.java index 68437e12..a895e6f2 100644 --- a/api/src/main/java/jakarta/persistence/ManyToOne.java +++ b/api/src/main/java/jakarta/persistence/ManyToOne.java @@ -123,8 +123,12 @@ FetchType fetch() default FetchType.EAGER; /** - * (Optional) Whether the association is optional. If set - * to false then a non-null relationship must always exist. + * (Optional) Whether the association is optional. If set to + * {@code false} then a non-null relationship must always exist. + * + *

If the annotated field or property is also annotated + * {@code @jakarta.annotation.Nonnull}, then {@code optional=false} + * is implied, and the value of this annotation member is ignored. * *

May be used in schema generation to infer that the * mapped foreign key column is {@link JoinColumn#nullable diff --git a/api/src/main/java/jakarta/persistence/OneToOne.java b/api/src/main/java/jakarta/persistence/OneToOne.java index fa231937..7d44ef2e 100644 --- a/api/src/main/java/jakarta/persistence/OneToOne.java +++ b/api/src/main/java/jakarta/persistence/OneToOne.java @@ -163,8 +163,12 @@ FetchType fetch() default FetchType.EAGER; /** - * (Optional) Whether the association is optional. If set - * to false then a non-null relationship must always exist. + * (Optional) Whether the association is optional. If set to + * {@code false} then a non-null relationship must always exist. + * + *

If the annotated field or property is also annotated + * {@code @jakarta.annotation.Nonnull}, then {@code optional=false} + * is implied, and the value of this annotation member is ignored. */ boolean optional() default true; diff --git a/spec/src/main/asciidoc/ch11-metadata-for-or-mapping.adoc b/spec/src/main/asciidoc/ch11-metadata-for-or-mapping.adoc index 4d1b7da7..c052f3c6 100644 --- a/spec/src/main/asciidoc/ch11-metadata-for-or-mapping.adoc +++ b/spec/src/main/asciidoc/ch11-metadata-for-or-mapping.adoc @@ -575,9 +575,9 @@ strategy hint has been specified. In particular, lazy fetching might only be available for `Basic` mappings for which property-based access is used. -The `optional` element is a hint as to -whether the value of the field or property may be null. It is -disregarded for primitive types. +If the annotated field or property is of primitive type, or if it is +also annotated with `jakarta.annotation.Nonnull`, then `optional=false` +is implied, and the value of the `optional` annotation member is ignored. .Basic Annotation Elements [#a14218,options="header"] @@ -590,9 +590,9 @@ strategy is a requirement on the persistence provider runtime that the value must be eagerly fetched. The LAZY strategy is a hint to the persistence provider runtime. |EAGER |boolean |optional -|(Optional) Whether the value of the field or -property may be null. This is a hint and is disregarded for primitive -types; it may be used in schema generation. +|(Optional) Whether the value of the field or property may be null. +May be used in schema generation. Ignored if the field or property +is of primitive type or is annotated `Nonnull`. |true |=== @@ -2983,6 +2983,10 @@ runtime that the associated entity should be fetched lazily when it is first accessed. The implementation is permitted to eagerly fetch associations for which the `LAZY` strategy hint has been specified. +If the annotated field or property is also annotated with +`jakarta.annotation.Nonnull`, then `optional=false` is implied +and the value of the `optional` annotation member is ignored. + .ManyToOne Annotation Elements [#a15202,options="header"] |=== @@ -3010,9 +3014,10 @@ persistence provider runtime. |boolean |optional -|(Optional) Whether the association is -optional. If set to false then a non-null relationship must always -exist. +|(Optional) Whether the association is optional. If set to false, +then a non-null relationship must always exist. +May be used in schema generation. Ignored if the field or property +is annotated `Nonnull`. |true |=== @@ -4118,6 +4123,10 @@ applications must otherwise not depend upon a specific order of removal, and must not reassign an entity that has been orphaned to another relationship or otherwise attempt to persist it. +If the annotated field or property is also annotated with +`jakarta.annotation.Nonnull`, then `optional=false` is implied +and the value of the `optional` annotation member is ignored. + .OneToOne Annotation Elements [#a15735,options="header"] |=== @@ -4144,9 +4153,10 @@ persistence provider runtime. |boolean |optional -|(Optional) Whether the association is -optional. If set to false then a non-null relationship must always -exist. +|(Optional) Whether the association is optional. If set to false, +then a non-null relationship must always exist. +May be used in schema generation. Ignored if the field or property +is annotated `Nonnull`. |true |String