HHH-17325 Add SoftDeleteTimestamp annotation

Author: YongGoose

hibernate-core/src/main/java/org/hibernate/annotations/CurrentTimestamp.java

@@ -15,6 +15,7 @@
 import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 import static org.hibernate.generator.EventType.INSERT;
+import static org.hibernate.generator.EventType.SOFT_DELETE;
 import static org.hibernate.generator.EventType.UPDATE;
 
 /**
@@ -59,23 +60,27 @@
  *
  * @see UpdateTimestamp
  * @see CreationTimestamp
+ * @see SoftDeleteTimestamp
  * @see CurrentTimestampGeneration
  *
  * @since 6.0
  *
  * @author Steve Ebersole
+ * @author Yongjun Hong
  */
 @ValueGenerationType(generatedBy = CurrentTimestampGeneration.class)
 @Retention(RUNTIME)
 @Target({ FIELD, METHOD, ANNOTATION_TYPE })
 public @interface CurrentTimestamp {
 	/**
-	 * Determines when the timestamp is generated. But default, it is updated
-	 * when any SQL {@code insert} or {@code update} statement is executed.
-	 * If it should be generated just once, on the initial SQL {@code insert},
-	 * explicitly specify {@link EventType#INSERT event = INSERT}.
+	 * Determines when the timestamp is generated. By default, it is updated
+	 * when any SQL {@code insert}, {@code update}, or soft-delete operation
+	 * is executed. If it should be generated just once, on the initial SQL
+	 * {@code insert}, explicitly specify {@link EventType#INSERT event = INSERT}.
+	 * For soft-delete operations, {@link EventType#SOFT_DELETE} can be used.
 	 */
-	EventType[] event() default {INSERT, UPDATE};
+	EventType[] event() default {INSERT, UPDATE, SOFT_DELETE};
+
 
 	/**
 	 * Specifies how the timestamp is generated. By default, it is generated

hibernate-core/src/main/java/org/hibernate/annotations/SoftDeleteTimestamp.java

@@ -0,0 +1,60 @@
+/*
+ * SPDX-License-Identifier: LGPL-2.1-or-later
+ * Copyright Red Hat Inc. and Hibernate Authors
+ */
+package org.hibernate.annotations;
+
+import org.hibernate.generator.internal.CurrentTimestampGeneration;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+import static java.lang.annotation.ElementType.FIELD;
+import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
+
+/**
+ * Specifies that the annotated field or property is a generated <em>soft delete timestamp</em>.
+ * The timestamp is generated just once, when an entity instance is soft-deleted in the database.
+ * <p>
+ * By default, the timestamp is generated by {@linkplain java.time.Clock#instant in memory}.
+ * but this may be changed by explicitly specifying the {@link #source}.
+ * Otherwise, this annotation is a synonym for
+ * {@link SoftDeleteTimestamp @SoftDeleteTimestamp(source=VM)}.
+ * <p>
+ * The annotated property may be of any one of the following types:
+ * {@link java.util.Date},
+ * {@link java.util.Calendar},
+ * {@link java.sql.Date},
+ * {@link java.sql.Time},
+ * {@link java.sql.Timestamp},
+ * {@link java.time.Instant},
+ * {@link java.time.LocalDate},
+ * {@link java.time.LocalDateTime},
+ * {@link java.time.LocalTime},
+ * {@link java.time.MonthDay},
+ * {@link java.time.OffsetDateTime},
+ * {@link java.time.OffsetTime},
+ * {@link java.time.Year},
+ * {@link java.time.YearMonth}, or
+ * {@link java.time.ZonedDateTime}.
+ * <p>
+ * A field annotated {@code @SoftDeleteTimeStamp} may not be directly set by the application
+ * program.
+ *
+ * @see SoftDeleteTimestamp
+ * @see CurrentTimestamp
+ *
+ * @author Yongjun Hong
+ */
+@ValueGenerationType(generatedBy = CurrentTimestampGeneration.class)
+@Retention(RUNTIME)
+@Target({FIELD, METHOD})
+public @interface SoftDeleteTimestamp {
+	/**
+	 * Specifies how the timestamp is generated. By default, it is generated
+	 * in memory, which might save a round trip to the database, depending on
+	 * the capabilities of the database and JDBC driver.
+	 */
+	SourceType source() default SourceType.VM;
+}

hibernate-core/src/main/java/org/hibernate/annotations/SourceType.java

@@ -11,6 +11,7 @@
  * @see CurrentTimestamp#source()
  * @see UpdateTimestamp#source()
  * @see CreationTimestamp#source()
+ * @see SoftDeleteTimestamp#source()
  * @see Source
  *
  * @author Hardy Ferentschik

hibernate-core/src/main/java/org/hibernate/boot/models/HibernateAnnotations.java

@@ -25,6 +25,7 @@
  * for unused because
  *
  * @author Steve Ebersole
+ * @author Yongjun Hong
  */
 @SuppressWarnings({ "deprecation", "removal", "unused" })
 public interface HibernateAnnotations {
@@ -511,6 +512,10 @@ public interface HibernateAnnotations {
 			SoftDelete.class,
 			SoftDeleteAnnotation.class
 	);
+	OrmAnnotationDescriptor<SoftDeleteTimestamp,SoftDeleteTimeStampAnnotation> SOFT_DELETE_TIMESTAMP = new OrmAnnotationDescriptor<>(
+			SoftDeleteTimestamp.class,
+			SoftDeleteTimeStampAnnotation.class
+	);
 	OrmAnnotationDescriptor<SortComparator,SortComparatorAnnotation> SORT_COMPARATOR = new OrmAnnotationDescriptor<>(
 			SortComparator.class,
 			SortComparatorAnnotation.class

hibernate-core/src/main/java/org/hibernate/boot/models/annotations/internal/CurrentTimestampAnnotation.java

@@ -11,6 +11,7 @@
 import org.hibernate.models.spi.SourceModelBuildingContext;
 
 import static org.hibernate.generator.EventType.INSERT;
+import static org.hibernate.generator.EventType.SOFT_DELETE;
 import static org.hibernate.generator.EventType.UPDATE;
 
 @SuppressWarnings({ "ClassExplicitlyAnnotation", "unused" })
@@ -23,7 +24,7 @@ public class CurrentTimestampAnnotation implements CurrentTimestamp {
 	 * Used in creating dynamic annotation instances (e.g. from XML)
 	 */
 	public CurrentTimestampAnnotation(SourceModelBuildingContext modelContext) {
-		this.event = new org.hibernate.generator.EventType[] {INSERT, UPDATE};
+		this.event = new org.hibernate.generator.EventType[] {INSERT, UPDATE, SOFT_DELETE};
 		this.source = org.hibernate.annotations.SourceType.DB;
 	}
 

hibernate-core/src/main/java/org/hibernate/boot/models/annotations/internal/SoftDeleteTimeStampAnnotation.java

@@ -0,0 +1,53 @@
+/*
+ * SPDX-License-Identifier: LGPL-2.1-or-later
+ * Copyright Red Hat Inc. and Hibernate Authors
+ */
+package org.hibernate.boot.models.annotations.internal;
+
+import org.hibernate.annotations.SoftDeleteTimestamp;
+import org.hibernate.annotations.SourceType;
+import org.hibernate.models.spi.SourceModelBuildingContext;
+
+import java.lang.annotation.Annotation;
+import java.util.Map;
+
+@SuppressWarnings({ "ClassExplicitlyAnnotation", "unused" })
+@jakarta.annotation.Generated("org.hibernate.orm.build.annotations.ClassGeneratorProcessor")
+public class SoftDeleteTimeStampAnnotation implements SoftDeleteTimestamp {
+	private org.hibernate.annotations.SourceType source;
+
+	/**
+	 * Used in creating dynamic annotation instances (e.g. from XML)
+	 */
+	public SoftDeleteTimeStampAnnotation(SourceModelBuildingContext modelContext) {
+		this.source = org.hibernate.annotations.SourceType.VM;
+	}
+
+	/**
+	 * Used in creating annotation instances from JDK variant
+	 */
+	public SoftDeleteTimeStampAnnotation(SoftDeleteTimestamp annotation, SourceModelBuildingContext modelContext) {
+		this.source = annotation.source();
+	}
+
+	/**
+	 * Used in creating annotation instances from Jandex variant
+	 */
+	public SoftDeleteTimeStampAnnotation(Map<String, Object> attributeValues, SourceModelBuildingContext modelContext) {
+		this.source = (org.hibernate.annotations.SourceType) attributeValues.get( "source" );
+	}
+
+	@Override
+	public Class<? extends Annotation> annotationType() {
+		return SoftDeleteTimestamp.class;
+	}
+
+	@Override
+	public SourceType source() {
+		return source;
+	}
+
+	public void source(org.hibernate.annotations.SourceType value) {
+		this.source = value;
+	}
+}

hibernate-core/src/main/java/org/hibernate/generator/EventType.java

@@ -13,6 +13,7 @@
  * even though there are only two types.
  *
  * @author Gavin King
+ * @author Yongjun Hong
  *
  * @since 6.2
  *
@@ -35,5 +36,13 @@ public enum EventType {
 	 * This indicates, for example, that a version number should be
 	 * incremented.
 	 */
-	UPDATE;
+	UPDATE,
+
+	/**
+	 * An event that occurs when any {@code update} statements needed
+	 * to soft-delete an entity instance are executed.
+	 * This indicates, for example, that a soft-delete flag should be
+	 * set to true or a deletion timestamp should be recorded.
+	 */
+	SOFT_DELETE;
 }

hibernate-core/src/main/java/org/hibernate/generator/EventTypeSets.java

@@ -8,19 +8,22 @@
 import java.util.Set;
 
 import static org.hibernate.generator.EventType.INSERT;
+import static org.hibernate.generator.EventType.SOFT_DELETE;
 import static org.hibernate.generator.EventType.UPDATE;
 
 /**
  * For convenience, enumerates the possible combinations of {@link EventType}.
  *
  * @author Gavin King
+ * @author Yongjun Hong
  *
  * @since 6.2
  */
 public class EventTypeSets {
 	public static final EnumSet<EventType> NONE = EnumSet.noneOf(EventType.class);
 	public static final EnumSet<EventType> INSERT_ONLY = EnumSet.of(INSERT);
 	public static final EnumSet<EventType> UPDATE_ONLY = EnumSet.of(UPDATE);
+	public static final EnumSet<EventType> SOFT_DELETE_ONLY = EnumSet.of(SOFT_DELETE);
 	public static final EnumSet<EventType> INSERT_AND_UPDATE = EnumSet.of(INSERT, UPDATE);
 	public static final EnumSet<EventType> ALL = EnumSet.allOf(EventType.class);
 

hibernate-core/src/main/java/org/hibernate/generator/internal/CurrentTimestampGeneration.java

@@ -30,6 +30,7 @@
 import org.hibernate.SessionFactory;
 import org.hibernate.annotations.CreationTimestamp;
 import org.hibernate.annotations.CurrentTimestamp;
+import org.hibernate.annotations.SoftDeleteTimestamp;
 import org.hibernate.annotations.SourceType;
 import org.hibernate.annotations.UpdateTimestamp;
 import org.hibernate.dialect.Dialect;
@@ -48,30 +49,33 @@
 
 import static org.hibernate.generator.EventTypeSets.INSERT_AND_UPDATE;
 import static org.hibernate.generator.EventTypeSets.INSERT_ONLY;
+import static org.hibernate.generator.EventTypeSets.SOFT_DELETE_ONLY;
 import static org.hibernate.generator.EventTypeSets.fromArray;
 
 /**
  * Value generation strategy which produces a timestamp using the database
  * {@link Dialect#currentTimestamp() current_timestamp} function or the JVM
  * {@linkplain java.time.Clock#instant() current instant}.
  * <p>
- * Underlies the {@link CurrentTimestamp}, {@link CreationTimestamp}, and
- * {@link UpdateTimestamp} annotations.
+ * Underlies the {@link CurrentTimestamp}, {@link CreationTimestamp}, {@link UpdateTimestamp}
+ * and {@link SoftDeleteTimestamp} annotations.
  *
  * @see CurrentTimestamp
  * @see CreationTimestamp
  * @see UpdateTimestamp
+ * @see SoftDeleteTimestamp
  *
  * @since 6.0
  *
  * @author Steve Ebersole
  * @author Gavin King
+ * @author Yongjun Hong
  */
 public class CurrentTimestampGeneration implements BeforeExecutionGenerator, OnExecutionGenerator {
 
 	/**
 	 * Configuration property name to set a custom {@link Clock} for Hibernate ORM to use when generating VM based
-	 * timestamp values for e.g. {@link CurrentTimestamp}, {@link CreationTimestamp}, {@link UpdateTimestamp}
+	 * timestamp values for e.g. {@link CurrentTimestamp}, {@link CreationTimestamp}, {@link UpdateTimestamp}, {@link SoftDeleteTimestamp}
 	 * and {@link org.hibernate.type.descriptor.java.VersionJavaType} methods.
 	 *
 	 * @since 6.6
@@ -197,6 +201,11 @@ public CurrentTimestampGeneration(UpdateTimestamp annotation, Member member, Gen
 		eventTypes = INSERT_AND_UPDATE;
 	}
 
+	public CurrentTimestampGeneration(SoftDeleteTimestamp annotation, Member member, GeneratorCreationContext context) {
+		delegate = getGeneratorDelegate( annotation.source(), member, context );
+		eventTypes = SOFT_DELETE_ONLY;
+	}
+
 	private static CurrentTimestampGeneratorDelegate getGeneratorDelegate(
 			SourceType source,
 			Member member,