refactorings to the AbstractEvent hierarchy

1. delete unused class SaveOrUpdateEvent
2. introduce AbstractPostDatabaseOperationEvent for consistency
3. DirtyCheckEvent should no longer extend FlushEvent

Author: gavinking

hibernate-core/src/main/java/org/hibernate/event/spi/AbstractPostDatabaseOperationEvent.java

@@ -0,0 +1,78 @@
+/*
+ * SPDX-License-Identifier: LGPL-2.1-or-later
+ * Copyright Red Hat Inc. and Hibernate Authors
+ */
+package org.hibernate.event.spi;
+
+import org.hibernate.engine.spi.SessionFactoryImplementor;
+import org.hibernate.persister.entity.EntityPersister;
+
+/**
+ * Represents an operation successfully executed by the database.
+ *
+ * @author Gavin King
+ *
+ * @since 7
+ */
+public abstract class AbstractPostDatabaseOperationEvent extends AbstractEvent {
+
+	private final Object entity;
+	private final Object id;
+	private final EntityPersister persister;
+
+	/**
+	 * Constructs an event containing the pertinent information.
+	 *
+	 * @param source The session from which the event originated.
+	 * @param entity The entity to be involved in the database operation.
+	 * @param id The entity id to be involved in the database operation.
+	 * @param persister The entity's persister.
+	 */
+	public AbstractPostDatabaseOperationEvent(
+			EventSource source,
+			Object entity,
+			Object id,
+			EntityPersister persister) {
+		super( source );
+		this.entity = entity;
+		this.id = id;
+		this.persister = persister;
+	}
+
+	/**
+	 * Retrieves the entity involved in the database operation.
+	 *
+	 * @return The entity.
+	 */
+	public Object getEntity() {
+		return entity;
+	}
+
+	/**
+	 * The id to be used in the database operation.
+	 *
+	 * @return The id.
+	 */
+	public Object getId() {
+		return id;
+	}
+
+	/**
+	 * The persister for the entity.
+	 *
+	 * @return The entity persister.
+	 */
+	public EntityPersister getPersister() {
+		return persister;
+	}
+
+	/**
+	 * The factory which owns the persister for the entity.
+	 *
+	 * @return The factory
+	 */
+	@Override
+	public SessionFactoryImplementor getFactory() {
+		return persister.getFactory();
+	}
+}

hibernate-core/src/main/java/org/hibernate/event/spi/AbstractPreDatabaseOperationEvent.java

@@ -8,7 +8,7 @@
 import org.hibernate.persister.entity.EntityPersister;
 
 /**
- * Represents an operation we are about to perform against the database.
+ * Represents an operation that is about to be executed by the database.
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/event/spi/AutoFlushEvent.java

@@ -6,7 +6,9 @@
 
 import java.util.Set;
 
-/** Defines an event class for the auto-flushing of a session.
+/**
+ * Event class for {@link org.hibernate.FlushMode#AUTO automatic}
+ * stateful session flush.
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/event/spi/ClearEvent.java

@@ -5,16 +5,13 @@
 package org.hibernate.event.spi;
 
 /**
- * An event for {@link org.hibernate.Session#clear()} listening
+ * Event class for {@link org.hibernate.Session#clear}.
  *
  * @author Steve Ebersole
+ *
+ * @see org.hibernate.Session#clear
  */
 public class ClearEvent extends AbstractEvent {
-	/**
-	 * Constructs an event from the given event session.
-	 *
-	 * @param source The session event source.
-	 */
 	public ClearEvent(EventSource source) {
 		super( source );
 	}

hibernate-core/src/main/java/org/hibernate/event/spi/DeleteEvent.java

@@ -5,30 +5,27 @@
 package org.hibernate.event.spi;
 
 /**
- * Defines an event class for the deletion of an entity.
+ * Event class for {@link org.hibernate.Session#remove}.
+ *
+ * @apiNote This class predates JPA, and today should
+ *          really be named {@code RemoveEvent}.
  *
  * @author Steve Ebersole
+ *
+ * @see org.hibernate.Session#remove
  */
 public class DeleteEvent extends AbstractEvent {
 	private final Object object;
 	private String entityName;
 	private boolean cascadeDeleteEnabled;
-	// TODO: The removeOrphan concept is a temporary "hack" for HHH-6484.  This should be removed once action/task
-	// ordering is improved.
+	// TODO: The removeOrphan concept is a temporary "hack" for HHH-6484.
+	//       This should be removed once action/task ordering is improved.
 	private boolean orphanRemovalBeforeUpdates;
 
-	/**
-	 * Constructs a new DeleteEvent instance.
-	 *
-	 * @param object The entity to be deleted.
-	 * @param source The session from which the delete event was generated.
-	 */
 	public DeleteEvent(Object object, EventSource source) {
 		super(source);
 		if (object == null) {
-			throw new IllegalArgumentException(
-					"attempt to create delete event with null entity"
-				);
+			throw new IllegalArgumentException( "attempt to create delete event with null entity" );
 		}
 		this.object = object;
 	}

hibernate-core/src/main/java/org/hibernate/event/spi/DirtyCheckEvent.java

@@ -4,12 +4,15 @@
  */
 package org.hibernate.event.spi;
 
+
 /**
- * Defines an event class for the dirty-checking of a session.
+ * Event class for {@link org.hibernate.Session#isDirty}.
  *
  * @author Steve Ebersole
+ *
+ * @see org.hibernate.Session#isDirty
  */
-public class DirtyCheckEvent extends FlushEvent {
+public class DirtyCheckEvent extends AbstractEvent {
 	private boolean dirty;
 
 	public DirtyCheckEvent(EventSource source) {

hibernate-core/src/main/java/org/hibernate/event/spi/EvictEvent.java

@@ -5,9 +5,13 @@
 package org.hibernate.event.spi;
 
 /**
- *  Defines an event class for the evicting of an entity.
+ * Event class for {@link org.hibernate.Session#evict}
+ * and {@link org.hibernate.Session#detach}.
  *
  * @author Steve Ebersole
+ *
+ * @see org.hibernate.Session#evict
+ * @see org.hibernate.Session#detach
  */
 public class EvictEvent extends AbstractEvent {
 

hibernate-core/src/main/java/org/hibernate/event/spi/FlushEvent.java

@@ -5,9 +5,11 @@
 package org.hibernate.event.spi;
 
 /**
- * Defines an event class for the flushing of a session.
+ * Event class for stateful session flush.
  *
  * @author Steve Ebersole
+ *
+ * @see org.hibernate.Session#flush
  */
 public class FlushEvent extends AbstractEvent {
 	private int numberOfEntitiesProcessed;

hibernate-core/src/main/java/org/hibernate/event/spi/LockEvent.java

@@ -9,9 +9,11 @@
 import org.hibernate.LockOptions;
 
 /**
- *  Defines an event class for the locking of an entity.
+ * Event class for {@link org.hibernate.Session#lock}.
  *
  * @author Steve Ebersole
+ *
+ * @see org.hibernate.Session#lock
  */
 public class LockEvent extends AbstractEvent {
 

hibernate-core/src/main/java/org/hibernate/event/spi/MergeEvent.java

@@ -5,9 +5,11 @@
 package org.hibernate.event.spi;
 
 /**
- * An event class for merge() and saveOrUpdateCopy()
+ * Event class for {@link org.hibernate.Session#merge}.
  *
  * @author Gavin King
+ *
+ * @see org.hibernate.Session#merge
  */
 public class MergeEvent extends AbstractEvent {