DATAJDBC-374 - Introduce shortcuts for Embedded#onEmpty(…)

@Embedded.Nullable & @Embedded.Empty offer shortcuts for @Embedded(onEmpty = USE_NULL) and @Embedded(onEmpty = USE_EMPTY) to reduce verbositility and simultaneously set JSR-305 @javax.annotation.Nonnull accordingly.

    @Embedded.Nullable
    EmbeddedEntity embeddedEntity;

Original pull request: #154.

Author: christophstrobl

pom.xml

@@ -34,6 +34,7 @@
 		<postgresql.version>42.0.0</postgresql.version>
 		<mariadb-java-client.version>2.2.3</mariadb-java-client.version>
 		<testcontainers.version>1.9.1</testcontainers.version>
+		<jsr305.version>3.0.2</jsr305.version>
 	</properties>
 
 	<inceptionYear>2017</inceptionYear>

spring-data-jdbc/src/test/java/org/springframework/data/jdbc/core/convert/EntityRowMapperUnitTests.java

@@ -558,13 +558,13 @@ static class WithNullableEmbeddedImmutableValue {
 	static class WithEmptyEmbeddedImmutableValue {
 
 		@Id Long id;
-		@Embedded(onEmpty = OnEmpty.USE_EMPTY) ImmutableValue embeddedImmutableValue;
+		@Embedded.Empty ImmutableValue embeddedImmutableValue;
 	}
 
 	static class WithEmbeddedPrimitiveImmutableValue {
 
 		@Id Long id;
-		@Embedded(onEmpty = OnEmpty.USE_NULL) ImmutablePrimitiveValue embeddedImmutablePrimitiveValue;
+		@Embedded.Nullable ImmutablePrimitiveValue embeddedImmutablePrimitiveValue;
 	}
 
 	@Value

spring-data-relational/pom.xml

@@ -48,6 +48,13 @@
 			<artifactId>spring-core</artifactId>
 		</dependency>
 
+		<dependency>
+			<groupId>com.google.code.findbugs</groupId>
+			<artifactId>jsr305</artifactId>
+			<version>${jsr305.version}</version>
+			<optional>true</optional>
+		</dependency>
+
 		<dependency>
 			<groupId>org.assertj</groupId>
 			<artifactId>assertj-core</artifactId>

spring-data-relational/src/main/java/org/springframework/data/relational/core/mapping/Embedded.java

@@ -21,6 +21,10 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+import javax.annotation.meta.When;
+
+import org.springframework.core.annotation.AliasFor;
+
 /**
  * The annotation to configure a value object as embedded in the current table.
  * <p />
@@ -38,6 +42,8 @@
 
 	/**
 	 * Set the load strategy for the embedded object if all contained fields yield {@literal null} values.
+	 * <p />
+	 * {@link Nullable @Embedded.Nullable} and {@link Empty @Embedded.Empty} offer shortcuts for this.
 	 * 
 	 * @return never {@link} null.
 	 */
@@ -57,4 +63,84 @@
 	enum OnEmpty {
 		USE_NULL, USE_EMPTY
 	}
+
+	/**
+	 * Shortcut for a nullable embedded property.
+	 *
+	 * <pre>
+	 * <code>
+	 * &#64;Embedded.Nullable
+	 * private Address address;
+	 * </code>
+	 * </pre>
+	 * 
+	 * as alternative to the more verbose
+	 * 
+	 * <pre>
+	 * <code>
+	 *
+	 * &#64;Embedded(onEmpty = USE_NULL)
+	 * &#64;javax.annotation.Nonnull(when = When.MAYBE)
+	 * private Address address;
+	 *
+	 * </code>
+	 * </pre>
+	 *
+	 * @author Christoph Strobl
+	 * @since 1.1
+	 * @see Embedded#onEmpty()
+	 */
+	@Embedded(onEmpty = OnEmpty.USE_NULL)
+	@Documented
+	@Retention(RetentionPolicy.RUNTIME)
+	@Target({ ElementType.FIELD, ElementType.METHOD })
+	@javax.annotation.Nonnull(when = When.MAYBE)
+	@interface Nullable {
+
+		/**
+		 * @return prefix for columns in the embedded value object. An empty {@link String} by default.
+		 */
+		@AliasFor(annotation = Embedded.class, attribute = "prefix")
+		String prefix() default "";
+	}
+
+	/**
+	 * Shortcut for an empty embedded property.
+	 *
+	 * <pre>
+	 * <code>
+	 * &#64;Embedded.Empty
+	 * private Address address;
+	 * </code>
+	 * </pre>
+	 *
+	 * as alternative to the more verbose
+	 *
+	 * <pre>
+	 * <code>
+	 *
+	 * &#64;Embedded(onEmpty = USE_EMPTY)
+	 * &#64;javax.annotation.Nonnull(when = When.NEVER)
+	 * private Address address;
+	 *
+	 * </code>
+	 * </pre>
+	 *
+	 * @author Christoph Strobl
+	 * @since 1.1
+	 * @see Embedded#onEmpty()
+	 */
+	@Embedded(onEmpty = OnEmpty.USE_EMPTY)
+	@Documented
+	@Retention(RetentionPolicy.RUNTIME)
+	@Target({ ElementType.FIELD, ElementType.METHOD })
+	@javax.annotation.Nonnull(when = When.NEVER)
+	@interface Empty {
+
+		/**
+		 * @return prefix for columns in the embedded value object. An empty {@link String} by default.
+		 */
+		@AliasFor(annotation = Embedded.class, attribute = "prefix")
+		String prefix() default "";
+	}
 }

src/main/asciidoc/jdbc.adoc

@@ -314,6 +314,24 @@ public class EmbeddedEntity {
 If you need a value object multiple times in an entity, this can be achieved with the optional `prefix` element of the `@Embedded` annotation.
 This element represents a prefix and is prepend for each column name in the embedded object.
 
+[TIP]
+====
+Make use of the shortcuts `@Embedded.Nullable` & `@Embedded.Empty` for `@Embedded(onEmpty = USE_NULL)` and `@Embedded(onEmpty = USE_EMPTY)` to reduce verbositility and simultaneously set JSR-305 `@javax.annotation.Nonnull` accordingly.
+
+[source, java]
+----
+public class MyEntity {
+
+    @Id
+    Integer id;
+
+    @Embedded.Nullable <1>
+    EmbeddedEntity embeddedEntity;
+}
+----
+<1> Shortcut for `@Embedded(onEmpty = USE_NULL)`.
+====
+
 [[jdbc.entity-persistence.state-detection-strategies]]
 === Entity State Detection Strategies