Refine documentation of BeforeConvert/BeforeSave lifecycle hooks.

Closes #1448

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

@@ -21,7 +21,7 @@ import com.datastax.oss.driver.api.core.CqlIdentifier;
 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

@@ -51,7 +51,7 @@ public class AfterLoadEvent<T> extends CassandraMappingEvent<Row> {
 	/**
 	 * 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 @@ package org.springframework.data.cassandra.core.mapping.event;
 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.CqlIdentifier;
 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

@@ -19,7 +19,10 @@ import com.datastax.oss.driver.api.core.CqlIdentifier;
 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.reactivestreams.Publisher;
 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.CqlIdentifier;
 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.