From 552360d8253b9ccdc6ec8aa7bb65b40a28a15c0a Mon Sep 17 00:00:00 2001 From: Mark Paluch Date: Fri, 10 Nov 2023 10:19:10 +0100 Subject: [PATCH] Refine documentation of BeforeConvert/BeforeSave lifecycle hooks. Closes #1448 --- .../core/mapping/event/AfterConvertEvent.java | 2 +- .../core/mapping/event/AfterLoadEvent.java | 2 +- .../core/mapping/event/BeforeConvertCallback.java | 6 +++++- .../core/mapping/event/BeforeSaveCallback.java | 13 +++++++++---- .../core/mapping/event/BeforeSaveEvent.java | 5 ++++- .../event/ReactiveBeforeConvertCallback.java | 6 +++++- .../mapping/event/ReactiveBeforeSaveCallback.java | 13 +++++++++---- 7 files changed, 34 insertions(+), 13 deletions(-) diff --git a/spring-data-cassandra/src/main/java/org/springframework/data/cassandra/core/mapping/event/AfterConvertEvent.java b/spring-data-cassandra/src/main/java/org/springframework/data/cassandra/core/mapping/event/AfterConvertEvent.java index 1d87678b7..d9b310583 100644 --- a/spring-data-cassandra/src/main/java/org/springframework/data/cassandra/core/mapping/event/AfterConvertEvent.java +++ b/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.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 diff --git a/spring-data-cassandra/src/main/java/org/springframework/data/cassandra/core/mapping/event/AfterLoadEvent.java b/spring-data-cassandra/src/main/java/org/springframework/data/cassandra/core/mapping/event/AfterLoadEvent.java index 97b6c8fe0..7f5de7242 100644 --- a/spring-data-cassandra/src/main/java/org/springframework/data/cassandra/core/mapping/event/AfterLoadEvent.java +++ b/spring-data-cassandra/src/main/java/org/springframework/data/cassandra/core/mapping/event/AfterLoadEvent.java @@ -51,7 +51,7 @@ public AfterLoadEvent(Row source, Class 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 getType() { return type; diff --git a/spring-data-cassandra/src/main/java/org/springframework/data/cassandra/core/mapping/event/BeforeConvertCallback.java b/spring-data-cassandra/src/main/java/org/springframework/data/cassandra/core/mapping/event/BeforeConvertCallback.java index ce6f17224..1a567f420 100644 --- a/spring-data-cassandra/src/main/java/org/springframework/data/cassandra/core/mapping/event/BeforeConvertCallback.java +++ b/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 extends EntityCallback { diff --git a/spring-data-cassandra/src/main/java/org/springframework/data/cassandra/core/mapping/event/BeforeSaveCallback.java b/spring-data-cassandra/src/main/java/org/springframework/data/cassandra/core/mapping/event/BeforeSaveCallback.java index 77ec20c3e..1706f4551 100644 --- a/spring-data-cassandra/src/main/java/org/springframework/data/cassandra/core/mapping/event/BeforeSaveCallback.java +++ b/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 extends EntityCallback { // 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. diff --git a/spring-data-cassandra/src/main/java/org/springframework/data/cassandra/core/mapping/event/BeforeSaveEvent.java b/spring-data-cassandra/src/main/java/org/springframework/data/cassandra/core/mapping/event/BeforeSaveEvent.java index 75a3a6a27..c19fd4621 100644 --- a/spring-data-cassandra/src/main/java/org/springframework/data/cassandra/core/mapping/event/BeforeSaveEvent.java +++ b/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.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 diff --git a/spring-data-cassandra/src/main/java/org/springframework/data/cassandra/core/mapping/event/ReactiveBeforeConvertCallback.java b/spring-data-cassandra/src/main/java/org/springframework/data/cassandra/core/mapping/event/ReactiveBeforeConvertCallback.java index f5d1a4ed6..e3481eb2f 100644 --- a/spring-data-cassandra/src/main/java/org/springframework/data/cassandra/core/mapping/event/ReactiveBeforeConvertCallback.java +++ b/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 extends EntityCallback { diff --git a/spring-data-cassandra/src/main/java/org/springframework/data/cassandra/core/mapping/event/ReactiveBeforeSaveCallback.java b/spring-data-cassandra/src/main/java/org/springframework/data/cassandra/core/mapping/event/ReactiveBeforeSaveCallback.java index b39620d4d..92c3a60f7 100644 --- a/spring-data-cassandra/src/main/java/org/springframework/data/cassandra/core/mapping/event/ReactiveBeforeSaveCallback.java +++ b/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 extends EntityCallback { // 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.