Refine documentation of BeforeConvert/BeforeSave lifecycle hooks.

Closes #1448

Author: mp911de

spring-data-cassandra/src/main/java/org/springframework/data/cassandra/core/mapping/event/AfterConvertEvent.java

@@ -23,7 +23,7 @@
 import com.datastax.oss.driver.api.core.cql.Row;
 
 /**
- * Event to be triggered after converting a {@link Row}.
+ * Event to be triggered after converting a {@link Row} into an entity.
  *
  * @author Mark Paluch
  * @since 2.1

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

@@ -53,7 +53,7 @@ public AfterLoadEvent(Row source, Class<T> type, CqlIdentifier tableName) {
 	/**
 	 * Returns the type for which the {@link AfterLoadEvent} shall be invoked for.
 	 *
-	 * @return
+	 * @return the type for which the {@link AfterLoadEvent} shall be invoked for.
 	 */
 	public Class<T> getType() {
 		return type;

spring-data-cassandra/src/main/java/org/springframework/data/cassandra/core/mapping/event/BeforeConvertCallback.java

@@ -18,13 +18,17 @@
 import org.springframework.data.mapping.callback.EntityCallback;
 
 import com.datastax.oss.driver.api.core.CqlIdentifier;
+import com.datastax.oss.driver.api.core.cql.Statement;
 
 /**
- * Callback being invoked before a domain object is converted to be persisted.
+ * Callback being invoked before a domain object is converted to be persisted. Entity callback invoked before converting
+ * a domain object to a {@code INSERT}/{@code UPDATE} {@link Statement}. This is useful to apply changes to the domain
+ * objects to that these will be reflected in the generated {@link Statement}.
  *
  * @author Mark Paluch
  * @since 2.2
  * @see org.springframework.data.mapping.callback.EntityCallbacks
+ * @see BeforeSaveCallback
  */
 @FunctionalInterface
 public interface BeforeConvertCallback<T> extends EntityCallback<T> {

spring-data-cassandra/src/main/java/org/springframework/data/cassandra/core/mapping/event/BeforeSaveCallback.java

@@ -21,19 +21,24 @@
 import com.datastax.oss.driver.api.core.cql.Statement;
 
 /**
- * Entity callback triggered before save of a row.
+ * Entity callback invoked before inserting or updating a row in the database. Before save is invoked after
+ * {@link BeforeConvertCallback converting the entity} into a {@link Statement}. This is useful to let the mapping layer
+ * derive values into the statement while the save callback can either update the domain object without reflecting the
+ * changes in the statement. Another use is to inspect the {@link Statement}.
  *
  * @author Mark Paluch
  * @since 2.2
  * @see org.springframework.data.mapping.callback.EntityCallbacks
+ * @see BeforeConvertCallback
  */
 @FunctionalInterface
 public interface BeforeSaveCallback<T> extends EntityCallback<T> {
 	// TODO: Mutable statements
 	/**
-	 * Entity callback method invoked before a domain object is saved. Can return either the same of a modified instance
-	 * of the domain object and can modify {@link Statement} contents. This method is called after converting the
-	 * {@code entity} to {@link Statement} so effectively the row is used as outcome of invoking this callback.
+	 * Entity callback method invoked before save. That is, before running the {@code INSERT}/{@code UPDATE}
+	 * {@link Statement} derived from the intent to save an object. Can return either the same of a modified instance of
+	 * the domain object and can inspect the {@link Statement} contents. This method is called after converting the
+	 * {@code entity} to {@link Statement} so effectively the entity is propagated as outcome of invoking this callback.
 	 *
 	 * @param entity the domain object to save.
 	 * @param tableName name of the table.

spring-data-cassandra/src/main/java/org/springframework/data/cassandra/core/mapping/event/BeforeSaveEvent.java

@@ -21,7 +21,10 @@
 import com.datastax.oss.driver.api.core.cql.Statement;
 
 /**
- * {@link CassandraMappingEvent} triggered before save of an object.
+ * {@link CassandraMappingEvent Mapping event} triggered before inserting or updating a row in the database. Before save
+ * is invoked after {@link BeforeConvertCallback converting the entity} into a {@link Statement}. This is useful to let
+ * the mapping layer derive values into the statement while the save callback can either update the domain object
+ * without reflecting the changes in the statement. Another use is to inspect the {@link Statement}.
  *
  * @author Lukasz Antoniak
  * @author Mark Paluch

spring-data-cassandra/src/main/java/org/springframework/data/cassandra/core/mapping/event/ReactiveBeforeConvertCallback.java

@@ -19,13 +19,17 @@
 import org.springframework.data.mapping.callback.EntityCallback;
 
 import com.datastax.oss.driver.api.core.CqlIdentifier;
+import com.datastax.oss.driver.api.core.cql.Statement;
 
 /**
- * Callback being invoked before a domain object is converted to be persisted.
+ * Callback being invoked before a domain object is converted to be persisted. Entity callback invoked before converting
+ * a domain object to a {@code INSERT}/{@code UPDATE} {@link Statement}. This is useful to apply changes to the domain
+ * objects to that these will be reflected in the generated {@link Statement}.
  *
  * @author Mark Paluch
  * @since 2.2
  * @see org.springframework.data.mapping.callback.ReactiveEntityCallbacks
+ * @see ReactiveBeforeSaveCallback
  */
 @FunctionalInterface
 public interface ReactiveBeforeConvertCallback<T> extends EntityCallback<T> {

spring-data-cassandra/src/main/java/org/springframework/data/cassandra/core/mapping/event/ReactiveBeforeSaveCallback.java

@@ -22,19 +22,24 @@
 import com.datastax.oss.driver.api.core.cql.Statement;
 
 /**
- * Entity callback triggered before save of a row.
+ * Entity callback invoked before inserting or updating a row in the database. Before save is invoked after
+ * {@link BeforeConvertCallback converting the entity} into a {@link Statement}. This is useful to let the mapping layer
+ * derive values into the statement while the save callback can either update the domain object without reflecting the
+ * changes in the statement. Another use is to inspect the {@link Statement}.
  *
  * @author Mark Paluch
  * @since 2.2
  * @see org.springframework.data.mapping.callback.ReactiveEntityCallbacks
+ * @see ReactiveBeforeConvertCallback
  */
 @FunctionalInterface
 public interface ReactiveBeforeSaveCallback<T> extends EntityCallback<T> {
 	// TODO: Mutable statements
 	/**
-	 * Entity callback method invoked before a domain object is saved. Can return either the same of a modified instance
-	 * of the domain object and can modify {@link Statement} contents. This method is called after converting the
-	 * {@code entity} to {@link Statement} so effectively the row is used as outcome of invoking this callback.
+	 * Entity callback method invoked before save. That is, before running the {@code INSERT}/{@code UPDATE}
+	 * {@link Statement} derived from the intent to save an object. Can return either the same of a modified instance of
+	 * the domain object and can inspect the {@link Statement} contents. This method is called after converting the
+	 * {@code entity} to {@link Statement} so effectively the entity is propagated as outcome of invoking this callback.
 	 *
 	 * @param entity the domain object to save.
 	 * @param tableName name of the table.

src/main/antora/modules/ROOT/pages/cassandra/events.adoc

@@ -21,7 +21,7 @@ Declaring these beans in your Spring `ApplicationContext` will cause them to be
 
 The `AbstractCassandraEventListener` has the following callback methods:
 
-* `onBeforeSave`: Called in `CassandraTemplate.insert(…)` and `.update(…)` operations before inserting or updating a row in the database.
+* `onBeforeSave`: Called in `CassandraTemplate.insert(…)` and `.update(…)` operations before inserting or updating a row in the database but after creating the `Statement`.
 * `onAfterSave`: Called in `CassandraTemplate…insert(…)` and `.update(…)` operations after inserting or updating a row in the database.
 * `onBeforeDelete`: Called in `CassandraTemplate.delete(…)` operations before deleting row from the database.
 * `onAfterDelete`: Called in `CassandraTemplate.delete(…)` operations after deleting row from the database.
@@ -34,7 +34,7 @@ Complex types used as properties within an aggregate root are not subject to eve
 include::{commons}@data-commons::page$entity-callbacks.adoc[leveloffset=+1]
 
 [[cassandra.entity-callbacks]]
-=== Store specific EntityCallbacks
+=== Store-specific EntityCallbacks
 
 Spring Data for Apache Cassandra uses the `EntityCallback` API for its auditing support and reacts on the following callbacks.
 
@@ -49,7 +49,8 @@ Spring Data for Apache Cassandra uses the `EntityCallback` API for its auditing
 | `ReactiveBeforeConvertCallback`
 `BeforeConvertCallback`
 | `onBeforeConvert(T entity, CqlIdentifier tableName)`
-| Invoked before a domain object is converted to `com.datastax.driver.core.Statement`.
+| Invoked before a domain object is converted to `Statement`.
+Domain objects can be updated to include the change in the `Statement`.
 | `Ordered.LOWEST_PRECEDENCE`
 
 | `ReactiveAuditingEntityCallback`
@@ -62,7 +63,7 @@ Spring Data for Apache Cassandra uses the `EntityCallback` API for its auditing
 `BeforeSaveCallback`
 | `onBeforeSave(T entity, CqlIdentifier tableName, Statement statement)`
 | Invoked before a domain object is saved. +
-Can modify the target, to be persisted, `com.datastax.driver.core.Statement` containing all mapped entity information.
+Can modify the target object after the `Statement` has been created. The provided statement contains all mapped entity information but changes to the domain object are not included in the `Statement`.
 | `Ordered.LOWEST_PRECEDENCE`
 
 |===