Datastore auditing (spring-attic#1513)

fixes spring-attic#1113
Datastore auditing support

Author: ChengyuanZhao

docs/src/main/asciidoc/datastore.adoc

@@ -1199,6 +1199,61 @@ Spring Data Cloud Datastore publishes events extending the Spring Framework's `A
 | `AfterDeleteEvent`|Published immediately after delete operations are executed by `DatastoreTemplate`| The keys sent to Cloud Datastore. The target entities, ID values, or entity type originally specified for the delete operation.
 |===
 
+=== Auditing
+
+Spring Data Cloud Datastore supports the `@LastModifiedDate` and `@LastModifiedBy` auditing annotations for properties:
+
+[source,java]
+----
+@Entity
+public class SimpleEntity {
+    @Id
+    String id;
+
+    @LastModifiedBy
+    String lastUser;
+
+    @LastModifiedDate
+    DateTime lastTouched;
+}
+----
+
+Upon insert, update, or save, these properties will be set automatically by the framework before Datastore entities are generated and saved to Cloud Datastore.
+
+To take advantage of these features, add the `@EnableDatastoreAuditing` annotation to your configuration class and provide a bean for an `AuditorAware<A>` implementation where the type `A` is the desired property type annotated by `@LastModifiedBy`:
+
+[source,java]
+----
+@Configuration
+@EnableDatastoreAuditing
+public class Config {
+
+    @Bean
+    public AuditorAware<String> auditorProvider() {
+        return () -> Optional.of("YOUR_USERNAME_HERE");
+    }
+}
+----
+
+The `AuditorAware` interface contains a single method that supplies the value for fields annotated by `@LastModifiedBy` and can be of any type.
+One alternative is to use Spring Security's `User` type:
+
+[source,java]
+----
+class SpringSecurityAuditorAware implements AuditorAware<User> {
+
+  public Optional<User> getCurrentAuditor() {
+
+    return Optional.ofNullable(SecurityContextHolder.getContext())
+			  .map(SecurityContext::getAuthentication)
+			  .filter(Authentication::isAuthenticated)
+			  .map(Authentication::getPrincipal)
+			  .map(User.class::cast);
+  }
+}
+----
+
+You can also set a custom provider for properties annotated `@LastModifiedDate` by providing a bean for `DateTimeProvider` and providing the bean name to `@EnableDatastoreAuditing(dateTimeProviderRef = "customDateTimeProviderBean")`.
 
 === Sample
 

docs/src/main/asciidoc/spanner.adoc

@@ -1323,7 +1323,7 @@ public class Config {
 }
 ----
 
-The `AuditorAware` interface contains a single method that supplies the value for fields annotated by `@LastModofiedBy` and can be of any type.
+The `AuditorAware` interface contains a single method that supplies the value for fields annotated by `@LastModifiedBy` and can be of any type.
 One alternative is to use Spring Security's `User` type:
 
 [source,java]

spring-cloud-gcp-data-datastore/src/main/java/org/springframework/cloud/gcp/data/datastore/core/DatastoreTemplate.java

@@ -141,13 +141,13 @@ public <T> T findById(Object id, Class<T> entityClass) {
 	@Override
 	public <T> T save(T instance, Key... ancestors) {
 		List<T> instances = Collections.singletonList(instance);
-		saveEntities(instances, getEntitiesForSave(instances, new HashSet<>(), ancestors));
+		saveEntities(instances, ancestors);
 		return instance;
 	}
 
 	@Override
 	public <T> Iterable<T> saveAll(Iterable<T> entities, Key... ancestors) {
-		saveEntities((List<T>) entities, getEntitiesForSave(entities, new HashSet<>(), ancestors));
+		saveEntities((List<T>) entities, ancestors);
 		return entities;
 	}
 
@@ -163,9 +163,10 @@ private <T> List<Entity> getEntitiesForSave(Iterable<T> entities, Set<Key> persi
 		return entitiesForSave;
 	}
 
-	private <T> void saveEntities(List<T> instances, List<Entity> entities) {
-		if (!entities.isEmpty()) {
-			maybeEmitEvent(new BeforeSaveEvent(entities, instances));
+	private <T> void saveEntities(List<T> instances, Key[] ancestors) {
+		if (!instances.isEmpty()) {
+			maybeEmitEvent(new BeforeSaveEvent(instances));
+			List<Entity> entities = getEntitiesForSave(instances, new HashSet<>(), ancestors);
 			getDatastoreReadWriter().put(entities.toArray(new Entity[0]));
 			maybeEmitEvent(new AfterSaveEvent(entities, instances));
 		}

spring-cloud-gcp-data-datastore/src/main/java/org/springframework/cloud/gcp/data/datastore/core/mapping/event/AfterSaveEvent.java

@@ -17,6 +17,7 @@
 package org.springframework.cloud.gcp.data.datastore.core.mapping.event;
 
 import java.util.List;
+import java.util.Objects;
 
 import com.google.cloud.datastore.Entity;
 
@@ -26,6 +27,9 @@
  * @author Chengyuan Zhao
  */
 public class AfterSaveEvent extends SaveEvent {
+
+	private final List<Entity> datastoreEntities;
+
 	/**
 	 * Constructor.
 	 *
@@ -34,6 +38,33 @@ public class AfterSaveEvent extends SaveEvent {
 	 * @param javaEntities The original Java entities being saved. Each entity may result in
 	 */
 	public AfterSaveEvent(List<Entity> datastoreEntities, List javaEntities) {
-		super(datastoreEntities, javaEntities);
+		super(javaEntities);
+		this.datastoreEntities = datastoreEntities;
+	}
+
+	/**
+	 * Get the Cloud Datastore entities that were saved.
+	 * @return The entities that were saved in Cloud Datastore.
+	 */
+	public List<Entity> getDatastoreEntities() {
+		return this.datastoreEntities;
+	}
+
+	@Override
+	public boolean equals(Object o) {
+		if (this == o) {
+			return true;
+		}
+		if (o == null || getClass() != o.getClass()) {
+			return false;
+		}
+		AfterSaveEvent that = (AfterSaveEvent) o;
+		return getDatastoreEntities().containsAll(that.getDatastoreEntities())
+				&& Objects.equals(getTargetEntities(), that.getTargetEntities());
+	}
+
+	@Override
+	public int hashCode() {
+		return Objects.hash(getDatastoreEntities(), getTargetEntities());
 	}
 }

spring-cloud-gcp-data-datastore/src/main/java/org/springframework/cloud/gcp/data/datastore/core/mapping/event/BeforeSaveEvent.java

@@ -18,8 +18,6 @@
 
 import java.util.List;
 
-import com.google.cloud.datastore.Entity;
-
 /**
  * An event published immediately before a save event to Cloud Datastore.
  *
@@ -29,11 +27,9 @@ public class BeforeSaveEvent extends SaveEvent {
 	/**
 	 * Constructor.
 	 *
-	 * @param datastoreEntities The Cloud Datastore entities that are being saved. These
-	 *     include any referenced or descendant entities of the original entities being saved.
 	 * @param javaEntities The original Java entities being saved. Each entity may result in
 	 */
-	public BeforeSaveEvent(List<Entity> datastoreEntities, List javaEntities) {
-		super(datastoreEntities, javaEntities);
+	public BeforeSaveEvent(List javaEntities) {
+		super(javaEntities);
 	}
 }

spring-cloud-gcp-data-datastore/src/main/java/org/springframework/cloud/gcp/data/datastore/core/mapping/event/SaveEvent.java

@@ -19,10 +19,7 @@
 import java.util.List;
 import java.util.Objects;
 
-import com.google.cloud.datastore.Entity;
-
 import org.springframework.context.ApplicationEvent;
-import org.springframework.util.Assert;
 
 /**
  * An event published when entities are saved to Cloud Datastore.
@@ -31,36 +28,22 @@
  */
 public class SaveEvent extends ApplicationEvent {
 
-	private final List javaEntities;
-
 	/**
 	 * Constructor.
 	 *
-	 * @param datastoreEntities The Cloud Datastore entities that are being saved. These
-	 *     include any referenced or descendant entities of the original entities being saved.
-	 * @param javaEntities The original Java entities being saved. Each entity may result in
+	 * @param entities The original Java entities being saved. Each entity may result in
 	 *     multiple Datastore entities being saved due to relationships.
 	 */
-	public SaveEvent(List<Entity> datastoreEntities, List javaEntities) {
-		super(datastoreEntities);
-		Assert.notNull(javaEntities, "The entities being saved must not be null.");
-		this.javaEntities = javaEntities;
-	}
-
-	/**
-	 * Get the Cloud Datastore entities that were saved.
-	 * @return The entities that were saved in Cloud Datastore.
-	 */
-	public List<Entity> getDatastoreEntities() {
-		return (List<Entity>) getSource();
+	public SaveEvent(List entities) {
+		super(entities);
 	}
 
 	/**
 	 * Get the original Java objects that were saved.
 	 * @return The original Java objects that were saved to Cloud Datastore.
 	 */
-	public List getJavaEntities() {
-		return this.javaEntities;
+	public List getTargetEntities() {
+		return (List) getSource();
 	}
 
 	@Override
@@ -72,12 +55,11 @@ public boolean equals(Object o) {
 			return false;
 		}
 		SaveEvent that = (SaveEvent) o;
-		return getDatastoreEntities().containsAll(that.getDatastoreEntities())
-				&& Objects.equals(getJavaEntities(), that.getJavaEntities());
+		return Objects.equals(getTargetEntities(), that.getTargetEntities());
 	}
 
 	@Override
 	public int hashCode() {
-		return Objects.hash(getDatastoreEntities(), getJavaEntities());
+		return Objects.hash(getTargetEntities());
 	}
 }

spring-cloud-gcp-data-datastore/src/main/java/org/springframework/cloud/gcp/data/datastore/repository/config/DatastoreAuditingRegistrar.java

@@ -0,0 +1,68 @@
+/*
+ * Copyright 2017-2019 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.cloud.gcp.data.datastore.repository.config;
+
+import java.lang.annotation.Annotation;
+
+import org.springframework.beans.factory.config.BeanDefinition;
+import org.springframework.beans.factory.support.BeanDefinitionBuilder;
+import org.springframework.beans.factory.support.BeanDefinitionRegistry;
+import org.springframework.cloud.gcp.data.datastore.repository.support.DatastoreAuditingEventListener;
+import org.springframework.data.auditing.AuditingHandler;
+import org.springframework.data.auditing.config.AuditingBeanDefinitionRegistrarSupport;
+import org.springframework.data.auditing.config.AuditingConfiguration;
+
+/**
+ * Registers the annotations and classes for providing auditing support in Spring Data
+ * Cloud Datastore.
+ *
+ * @author Chengyuan Zhao
+ * @since 1.2
+ */
+public class DatastoreAuditingRegistrar extends AuditingBeanDefinitionRegistrarSupport {
+
+	private static final String AUDITING_HANDLER_BEAN_NAME = "datastoreAuditingHandler";
+
+	private static final String MAPPING_CONTEXT_BEAN_NAME = "datastoreMappingContext";
+
+	@Override
+	protected Class<? extends Annotation> getAnnotation() {
+		return EnableDatastoreAuditing.class;
+	}
+
+	@Override
+	protected void registerAuditListenerBeanDefinition(BeanDefinition auditingHandlerDefinition,
+			BeanDefinitionRegistry registry) {
+		Class<?> listenerClass = DatastoreAuditingEventListener.class;
+		BeanDefinitionBuilder builder = BeanDefinitionBuilder.rootBeanDefinition(listenerClass)
+				.addConstructorArgReference(AUDITING_HANDLER_BEAN_NAME);
+
+		registerInfrastructureBeanWithId(builder.getRawBeanDefinition(), listenerClass.getName(), registry);
+	}
+
+	@Override
+	protected BeanDefinitionBuilder getAuditHandlerBeanDefinitionBuilder(AuditingConfiguration configuration) {
+		BeanDefinitionBuilder builder = configureDefaultAuditHandlerAttributes(configuration,
+				BeanDefinitionBuilder.rootBeanDefinition(AuditingHandler.class));
+		return builder.addConstructorArgReference(MAPPING_CONTEXT_BEAN_NAME);
+	}
+
+	@Override
+	protected String getAuditingHandlerBeanName() {
+		return AUDITING_HANDLER_BEAN_NAME;
+	}
+}

spring-cloud-gcp-data-datastore/src/main/java/org/springframework/cloud/gcp/data/datastore/repository/config/EnableDatastoreAuditing.java

@@ -0,0 +1,75 @@
+/*
+ * Copyright 2017-2019 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.cloud.gcp.data.datastore.repository.config;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Inherited;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.springframework.context.annotation.Import;
+import org.springframework.data.auditing.DateTimeProvider;
+import org.springframework.data.domain.AuditorAware;
+
+/**
+ * The annotation used to activate auditing functionality.
+ *
+ * @author Chengyuan Zhao
+ * @since 1.2
+ */
+@Inherited
+@Documented
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+@Import(DatastoreAuditingRegistrar.class)
+public @interface EnableDatastoreAuditing {
+
+	/**
+	 * Configures a {@link AuditorAware} bean to be used to lookup the current principal.
+	 *
+	 * @return the name of a custom auditor provider. If blank then one will be looked up bean
+	 * type.
+	 */
+	String auditorAwareRef() default "";
+
+	/**
+	 * Configures whether the creation and modification dates are set. Defaults to
+	 * {@literal true}.
+	 *
+	 * @return whether dates are set by the auditing functionality.
+	 */
+	boolean setDates() default true;
+
+	/**
+	 * Configures whether the entity shall be marked as modified on creation. Defaults to
+	 * {@literal true}.
+	 *
+	 * @return whether an entity is marked as modified when it is created.
+	 */
+	boolean modifyOnCreate() default true;
+
+	/**
+	 * Configures a {@link DateTimeProvider} bean name that allows customizing the
+	 * {@link org.joda.time.DateTime} to be used for setting creation and modification dates.
+	 *
+	 * @return the name of the custom time provider. If blank then one will be looked up bean
+	 * type.
+	 */
+	String dateTimeProviderRef() default "";
+}