Improve and clarify documentation of callbacks.

This also removes deprecated Events and Callbacks.

Closes #1236

Author: schauder

spring-data-jdbc/src/main/java/org/springframework/data/jdbc/core/JdbcAggregateTemplate.java

@@ -402,10 +402,7 @@ private <T> Iterable<T> triggerAfterConvert(Iterable<T> all) {
 
 	private <T> T triggerAfterConvert(T entity) {
 
-		publisher.publishEvent(new AfterLoadEvent<>(entity));
 		publisher.publishEvent(new AfterConvertEvent<>(entity));
-
-		entity = entityCallbacks.callback(AfterLoadCallback.class, entity);
 		return entityCallbacks.callback(AfterConvertCallback.class, entity);
 	}
 

spring-data-jdbc/src/main/java/org/springframework/data/jdbc/repository/support/JdbcQueryLookupStrategy.java

@@ -36,8 +36,6 @@
 import org.springframework.data.relational.core.mapping.RelationalPersistentEntity;
 import org.springframework.data.relational.core.mapping.event.AfterConvertCallback;
 import org.springframework.data.relational.core.mapping.event.AfterConvertEvent;
-import org.springframework.data.relational.core.mapping.event.AfterLoadCallback;
-import org.springframework.data.relational.core.mapping.event.AfterLoadEvent;
 import org.springframework.data.repository.core.NamedQueries;
 import org.springframework.data.repository.core.RepositoryMetadata;
 import org.springframework.data.repository.query.QueryLookupStrategy;
@@ -328,11 +326,9 @@ public T mapRow(ResultSet rs, int rowNum) throws SQLException {
 
 			if (entity != null) {
 
-				publisher.publishEvent(new AfterLoadEvent<>(entity));
 				publisher.publishEvent(new AfterConvertEvent<>(entity));
 
 				if (callbacks != null) {
-					entity = callbacks.callback(AfterLoadCallback.class, entity);
 					return callbacks.callback(AfterConvertCallback.class, entity);
 				}
 			}

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

@@ -46,7 +46,6 @@
 import org.springframework.data.relational.core.mapping.RelationalMappingContext;
 import org.springframework.data.relational.core.mapping.event.AfterConvertCallback;
 import org.springframework.data.relational.core.mapping.event.AfterDeleteCallback;
-import org.springframework.data.relational.core.mapping.event.AfterLoadCallback;
 import org.springframework.data.relational.core.mapping.event.AfterSaveCallback;
 import org.springframework.data.relational.core.mapping.event.BeforeConvertCallback;
 import org.springframework.data.relational.core.mapping.event.BeforeDeleteCallback;
@@ -254,30 +253,6 @@ public void callbackOnDelete() {
 		verify(callbacks).callback(AfterDeleteCallback.class, second);
 	}
 
-	@Test // DATAJDBC-393
-	public void callbackOnLoad() {
-
-		SampleEntity alfred1 = new SampleEntity(23L, "Alfred");
-		SampleEntity alfred2 = new SampleEntity(23L, "Alfred E.");
-
-		SampleEntity neumann1 = new SampleEntity(42L, "Neumann");
-		SampleEntity neumann2 = new SampleEntity(42L, "Alfred E. Neumann");
-
-		when(dataAccessStrategy.findAll(SampleEntity.class)).thenReturn(asList(alfred1, neumann1));
-
-		when(callbacks.callback(any(Class.class), eq(alfred1), any())).thenReturn(alfred2);
-		when(callbacks.callback(any(Class.class), eq(alfred2), any())).thenReturn(alfred2);
-		when(callbacks.callback(any(Class.class), eq(neumann1), any())).thenReturn(neumann2);
-		when(callbacks.callback(any(Class.class), eq(neumann2), any())).thenReturn(neumann2);
-
-		Iterable<SampleEntity> all = template.findAll(SampleEntity.class);
-
-		verify(callbacks).callback(AfterLoadCallback.class, alfred1);
-		verify(callbacks).callback(AfterLoadCallback.class, neumann1);
-
-		assertThat(all).containsExactly(alfred2, neumann2);
-	}
-
 	@Test // DATAJDBC-101
 	public void callbackOnLoadSorted() {
 
@@ -290,16 +265,12 @@ public void callbackOnLoadSorted() {
 		when(dataAccessStrategy.findAll(SampleEntity.class, Sort.by("name"))).thenReturn(asList(alfred1, neumann1));
 
 		when(callbacks.callback(any(Class.class), eq(alfred1), any())).thenReturn(alfred2);
-		when(callbacks.callback(any(Class.class), eq(alfred2), any())).thenReturn(alfred2);
 		when(callbacks.callback(any(Class.class), eq(neumann1), any())).thenReturn(neumann2);
-		when(callbacks.callback(any(Class.class), eq(neumann2), any())).thenReturn(neumann2);
 
 		Iterable<SampleEntity> all = template.findAll(SampleEntity.class, Sort.by("name"));
 
-		verify(callbacks).callback(AfterLoadCallback.class, alfred1);
-		verify(callbacks).callback(AfterConvertCallback.class, alfred2);
-		verify(callbacks).callback(AfterLoadCallback.class, neumann1);
-		verify(callbacks).callback(AfterConvertCallback.class, neumann2);
+		verify(callbacks).callback(AfterConvertCallback.class, alfred1);
+		verify(callbacks).callback(AfterConvertCallback.class, neumann1);
 
 		assertThat(all).containsExactly(alfred2, neumann2);
 	}
@@ -316,16 +287,12 @@ public void callbackOnLoadPaged() {
 		when(dataAccessStrategy.findAll(SampleEntity.class, PageRequest.of(0, 20))).thenReturn(asList(alfred1, neumann1));
 
 		when(callbacks.callback(any(Class.class), eq(alfred1), any())).thenReturn(alfred2);
-		when(callbacks.callback(any(Class.class), eq(alfred2), any())).thenReturn(alfred2);
 		when(callbacks.callback(any(Class.class), eq(neumann1), any())).thenReturn(neumann2);
-		when(callbacks.callback(any(Class.class), eq(neumann2), any())).thenReturn(neumann2);
 
 		Iterable<SampleEntity> all = template.findAll(SampleEntity.class, PageRequest.of(0, 20));
 
-		verify(callbacks).callback(AfterLoadCallback.class, alfred1);
-		verify(callbacks).callback(AfterConvertCallback.class, alfred2);
-		verify(callbacks).callback(AfterLoadCallback.class, neumann1);
-		verify(callbacks).callback(AfterConvertCallback.class, neumann2);
+		verify(callbacks).callback(AfterConvertCallback.class, alfred1);
+		verify(callbacks).callback(AfterConvertCallback.class, neumann1);
 
 		assertThat(all).containsExactly(alfred2, neumann2);
 	}

spring-data-jdbc/src/test/java/org/springframework/data/jdbc/repository/JdbcRepositoryIntegrationTests.java

@@ -50,7 +50,6 @@
 import org.springframework.data.domain.Pageable;
 import org.springframework.data.domain.Slice;
 import org.springframework.data.jdbc.core.mapping.AggregateReference;
-import org.springframework.data.relational.repository.Lock;
 import org.springframework.data.jdbc.repository.query.Modifying;
 import org.springframework.data.jdbc.repository.query.Query;
 import org.springframework.data.jdbc.repository.support.JdbcRepositoryFactory;
@@ -60,8 +59,8 @@
 import org.springframework.data.jdbc.testing.TestDatabaseFeatures;
 import org.springframework.data.relational.core.mapping.event.AbstractRelationalEvent;
 import org.springframework.data.relational.core.mapping.event.AfterConvertEvent;
-import org.springframework.data.relational.core.mapping.event.AfterLoadEvent;
 import org.springframework.data.relational.core.sql.LockMode;
+import org.springframework.data.relational.repository.Lock;
 import org.springframework.data.repository.CrudRepository;
 import org.springframework.data.repository.core.NamedQueries;
 import org.springframework.data.repository.core.support.PropertiesBasedNamedQueries;
@@ -312,7 +311,7 @@ public void queryMethodShouldEmitEvents() {
 
 		repository.findAllWithSql();
 
-		assertThat(eventListener.events).hasSize(2).hasOnlyElementsOfTypes(AfterLoadEvent.class, AfterConvertEvent.class);
+		assertThat(eventListener.events).hasSize(1).hasOnlyElementsOfType(AfterConvertEvent.class);
 	}
 
 	@Test // DATAJDBC-318

spring-data-jdbc/src/test/java/org/springframework/data/jdbc/repository/SimpleJdbcRepositoryEventsUnitTests.java

@@ -190,9 +190,7 @@ public void publishesEventsOnFindAll() {
 		assertThat(publisher.events) //
 				.extracting(e -> (Class) e.getClass()) //
 				.containsExactly( //
-						AfterLoadEvent.class, //
 						AfterConvertEvent.class, //
-						AfterLoadEvent.class, //
 						AfterConvertEvent.class //
 				);
 	}
@@ -211,9 +209,7 @@ public void publishesEventsOnFindAllById() {
 		assertThat(publisher.events) //
 				.extracting(e -> (Class) e.getClass()) //
 				.containsExactly( //
-						AfterLoadEvent.class, //
 						AfterConvertEvent.class, //
-						AfterLoadEvent.class, //
 						AfterConvertEvent.class //
 				);
 	}
@@ -231,7 +227,6 @@ public void publishesEventsOnFindById() {
 		assertThat(publisher.events) //
 				.extracting(e -> (Class) e.getClass()) //
 				.containsExactly( //
-						AfterLoadEvent.class, //
 						AfterConvertEvent.class //
 				);
 	}
@@ -250,9 +245,7 @@ public void publishesEventsOnFindAllSorted() {
 		assertThat(publisher.events) //
 				.extracting(e -> (Class) e.getClass()) //
 				.containsExactly( //
-						AfterLoadEvent.class, //
 						AfterConvertEvent.class, //
-						AfterLoadEvent.class, //
 						AfterConvertEvent.class //
 				);
 	}
@@ -272,9 +265,7 @@ public void publishesEventsOnFindAllPaged() {
 		assertThat(publisher.events) //
 				.extracting(e -> (Class) e.getClass()) //
 				.containsExactly( //
-						AfterLoadEvent.class, //
 						AfterConvertEvent.class, //
-						AfterLoadEvent.class, //
 						AfterConvertEvent.class //
 				);
 	}

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

@@ -51,9 +51,7 @@ public void onApplicationEvent(AbstractRelationalEvent<?> event) {
 			return;
 		}
 
-		if (event instanceof AfterLoadEvent) {
-			onAfterLoad((AfterLoadEvent<E>) event);
-		} else if (event instanceof AfterConvertEvent) {
+		if (event instanceof AfterConvertEvent) {
 			onAfterConvert((AfterConvertEvent<E>) event);
 		} else if (event instanceof AfterDeleteEvent) {
 			onAfterDelete((AfterDeleteEvent<E>) event);
@@ -104,20 +102,6 @@ protected void onAfterSave(AfterSaveEvent<E> event) {
 		}
 	}
 
-	/**
-	 * Captures {@link AfterLoadEvent}.
-	 *
-	 * @param event will never be {@literal null}.
-	 * @deprecated use {@link #onAfterConvert(AfterConvertEvent)} instead.
-	 */
-	@Deprecated
-	protected void onAfterLoad(AfterLoadEvent<E> event) {
-
-		if (LOG.isDebugEnabled()) {
-			LOG.debug(String.format("onAfterLoad(%s)", event.getEntity()));
-		}
-	}
-
 	/**
 	 * Captures {@link AfterConvertEvent}.
 	 *

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

@@ -18,7 +18,22 @@
 import org.springframework.data.mapping.callback.EntityCallback;
 
 /**
- * An {@link EntityCallback} that gets invoked after an aggregate was saved.
+ * An {@link EntityCallback} that gets invoked after an aggregate was saved to the database.
+ * <p>
+ * The persisting process works as follows:
+ * <ol>
+ * <li>A decision is made, if the aggregate is new and therefore should be inserted or if it is not new and therefore
+ * should be updated.</li>
+ * <li>{@link BeforeConvertCallback} and {@link BeforeConvertEvent} get published.</li>
+ * <li>An {@link org.springframework.data.relational.core.conversion.AggregateChange} object is created for the
+ * aggregate. It includes the {@link org.springframework.data.relational.core.conversion.DbAction} instances to be
+ * executed. This means that all the deletes, updates and inserts to be performed are determined. These actions
+ * reference entities of the aggregates in order to access values to be used in the SQL statements. This step also
+ * determines if the id of an entity gets passed to the database or if the database is expected to generate that id.</li>
+ * <li>{@link BeforeSaveCallback} and {@link BeforeSaveEvent} get published.</li>
+ * <li>SQL statements get applied to the database.</li>
+ * <li>{@link AfterSaveCallback} and {@link AfterSaveEvent} get published.</li>
+ * </ol>
  *
  * @author Jens Schauder
  * @author Mark Paluch

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

@@ -19,6 +19,21 @@
 
 /**
  * Gets published after a new instance or a changed instance was saved in the database.
+ * <p>
+ * The persisting process works as follows:
+ * <ol>
+ * <li>A decision is made, if the aggregate is new and therefore should be inserted or if it is not new and therefore
+ * should be updated.</li>
+ * <li>{@link BeforeConvertCallback} and {@link BeforeConvertEvent} get published.</li>
+ * <li>An {@link org.springframework.data.relational.core.conversion.AggregateChange} object is created for the
+ * aggregate. It includes the {@link org.springframework.data.relational.core.conversion.DbAction} instances to be
+ * executed. This means that all the deletes, updates and inserts to be performed are determined. These actions
+ * reference entities of the aggregates in order to access values to be used in the SQL statements. This step also
+ * determines if the id of an entity gets passed to the database or if the database is expected to generate that id.</li>
+ * <li>{@link BeforeSaveCallback} and {@link BeforeSaveEvent} get published.</li>
+ * <li>SQL statements get applied to the database.</li>
+ * <li>{@link AfterSaveCallback} and {@link AfterSaveEvent} get published.</li>
+ * </ol>
  *
  * @author Jens Schauder
  */