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 119ba3a49..198223a70 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 @@ -23,7 +23,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 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 3291e8844..991ec314b 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 @@ -53,7 +53,7 @@ public class AfterLoadEvent extends CassandraMappingEvent { /** * 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 @@ 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 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.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 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 7bb3ddba2..d4d8caad0 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 @@ -21,7 +21,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 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.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 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.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 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/src/main/antora/modules/ROOT/pages/cassandra/events.adoc b/src/main/antora/modules/ROOT/pages/cassandra/events.adoc index aef888686..2f55ea504 100644 --- a/src/main/antora/modules/ROOT/pages/cassandra/events.adoc +++ b/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` |===