Polishing.

Rename Granularities/Granularity to Granularity and GranularityDefinition to proivide a more natural wording towards using predefined granularities.

Validate presence of referenced properties through the TimeSeries annotation.

Tweak Javadoc, reformat code, add unit tests.

See #3731
Original pull request: #3732.

Author: mp911de

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/CollectionOptions.java

@@ -20,8 +20,8 @@
 import org.springframework.data.mongodb.core.mapping.Field;
 import org.springframework.data.mongodb.core.query.Collation;
 import org.springframework.data.mongodb.core.schema.MongoJsonSchema;
-import org.springframework.data.mongodb.core.timeseries.Granularities;
 import org.springframework.data.mongodb.core.timeseries.Granularity;
+import org.springframework.data.mongodb.core.timeseries.GranularityDefinition;
 import org.springframework.data.mongodb.core.validation.Validator;
 import org.springframework.data.util.Optionals;
 import org.springframework.lang.Nullable;
@@ -100,7 +100,7 @@ public static CollectionOptions empty() {
 	/**
 	 * Quick way to set up {@link CollectionOptions} for a Time Series collection. For more advanced settings use
 	 * {@link #timeSeries(TimeSeriesOptions)}.
-	 * 
+	 *
 	 * @param timeField The name of the property which contains the date in each time series document. Must not be
 	 *          {@literal null}.
 	 * @return new instance of {@link CollectionOptions}.
@@ -454,12 +454,13 @@ public static class TimeSeriesOptions {
 
 		private final String timeField;
 
-		@Nullable //
-		private String metaField;
+		private @Nullable final String metaField;
+
+		private final GranularityDefinition granularity;
 
-		private Granularity granularity;
+		private TimeSeriesOptions(String timeField, @Nullable String metaField, GranularityDefinition granularity) {
 
-		private TimeSeriesOptions(String timeField, @Nullable String metaField, Granularity granularity) {
+			Assert.hasText(timeField, "Time field must not be empty or null!");
 
 			this.timeField = timeField;
 			this.metaField = metaField;
@@ -475,7 +476,7 @@ private TimeSeriesOptions(String timeField, @Nullable String metaField, Granular
 		 * @return new instance of {@link TimeSeriesOptions}.
 		 */
 		public static TimeSeriesOptions timeSeries(String timeField) {
-			return new TimeSeriesOptions(timeField, null, Granularities.DEFAULT);
+			return new TimeSeriesOptions(timeField, null, Granularity.DEFAULT);
 		}
 
 		/**
@@ -492,12 +493,13 @@ public TimeSeriesOptions metaField(String metaField) {
 		}
 
 		/**
-		 * Select the {@link Granularity} parameter to define how data in the time series collection is organized. Select
-		 * one that is closest to the time span between incoming measurements.
+		 * Select the {@link GranularityDefinition} parameter to define how data in the time series collection is organized.
+		 * Select one that is closest to the time span between incoming measurements.
 		 *
 		 * @return new instance of {@link TimeSeriesOptions}.
+		 * @see Granularity
 		 */
-		public TimeSeriesOptions granularity(Granularity granularity) {
+		public TimeSeriesOptions granularity(GranularityDefinition granularity) {
 			return new TimeSeriesOptions(timeField, metaField, granularity);
 		}
 
@@ -520,7 +522,7 @@ public String getMetaField() {
 		/**
 		 * @return never {@literal null}.
 		 */
-		public Granularity getGranularity() {
+		public GranularityDefinition getGranularity() {
 			return granularity;
 		}
 	}

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/EntityOperations.java

@@ -38,7 +38,7 @@
 import org.springframework.data.mongodb.core.query.Collation;
 import org.springframework.data.mongodb.core.query.Criteria;
 import org.springframework.data.mongodb.core.query.Query;
-import org.springframework.data.mongodb.core.timeseries.Granularities;
+import org.springframework.data.mongodb.core.timeseries.Granularity;
 import org.springframework.lang.Nullable;
 import org.springframework.util.Assert;
 import org.springframework.util.ClassUtils;
@@ -898,11 +898,23 @@ public CollectionOptions getCollectionOptions() {
 			if (entity.isAnnotationPresent(TimeSeries.class)) {
 
 				TimeSeries timeSeries = entity.getRequiredAnnotation(TimeSeries.class);
+
+				if (entity.getPersistentProperty(timeSeries.timeField()) == null) {
+					throw new MappingException(String.format("Time series field '%s' does not exist in type %s",
+							timeSeries.timeField(), entity.getName()));
+				}
+
 				TimeSeriesOptions options = TimeSeriesOptions.timeSeries(timeSeries.timeField());
 				if (StringUtils.hasText(timeSeries.metaField())) {
+
+					if (entity.getPersistentProperty(timeSeries.metaField()) == null) {
+						throw new MappingException(
+								String.format("Meta field '%s' does not exist in type %s", timeSeries.metaField(), entity.getName()));
+					}
+
 					options = options.metaField(timeSeries.metaField());
 				}
-				if (!Granularities.DEFAULT.equals(timeSeries.granularity())) {
+				if (!Granularity.DEFAULT.equals(timeSeries.granularity())) {
 					options = options.granularity(timeSeries.granularity());
 				}
 				collectionOptions = collectionOptions.timeSeries(options);

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/MongoTemplate.java

@@ -99,7 +99,7 @@
 import org.springframework.data.mongodb.core.query.Query;
 import org.springframework.data.mongodb.core.query.UpdateDefinition;
 import org.springframework.data.mongodb.core.query.UpdateDefinition.ArrayFilter;
-import org.springframework.data.mongodb.core.timeseries.Granularities;
+import org.springframework.data.mongodb.core.timeseries.Granularity;
 import org.springframework.data.mongodb.core.validation.Validator;
 import org.springframework.data.mongodb.util.BsonUtils;
 import org.springframework.data.projection.SpelAwareProxyProjectionFactory;
@@ -2436,14 +2436,15 @@ protected MongoCollection<Document> doCreateCollection(String collectionName, Do
 				co.validationOptions(options);
 			}
 
-			if(collectionOptions.containsKey("timeseries")) {
+			if (collectionOptions.containsKey("timeseries")) {
 
 				Document timeSeries = collectionOptions.get("timeseries", Document.class);
-				com.mongodb.client.model.TimeSeriesOptions options = new com.mongodb.client.model.TimeSeriesOptions(timeSeries.getString("timeField"));
-				if(timeSeries.containsKey("metaField")) {
+				com.mongodb.client.model.TimeSeriesOptions options = new com.mongodb.client.model.TimeSeriesOptions(
+						timeSeries.getString("timeField"));
+				if (timeSeries.containsKey("metaField")) {
 					options.metaField(timeSeries.getString("metaField"));
 				}
-				if(timeSeries.containsKey("granularity")) {
+				if (timeSeries.containsKey("granularity")) {
 					options.granularity(TimeSeriesGranularity.valueOf(timeSeries.getString("granularity").toUpperCase()));
 				}
 				co.timeSeriesOptions(options);
@@ -2604,17 +2605,18 @@ protected Document convertToDocument(@Nullable CollectionOptions collectionOptio
 			collectionOptions.getValidationOptions().ifPresent(it -> it.getValidator() //
 					.ifPresent(val -> doc.put("validator", getMappedValidator(val, targetType))));
 
-			collectionOptions.getTimeSeriesOptions().map(operations.forType(targetType)::mapTimeSeriesOptions).ifPresent(it -> {
+			collectionOptions.getTimeSeriesOptions().map(operations.forType(targetType)::mapTimeSeriesOptions)
+					.ifPresent(it -> {
 
-				Document timeseries = new Document("timeField", it.getTimeField());
-				if(StringUtils.hasText(it.getMetaField())) {
-					timeseries.append("metaField", it.getMetaField());
-				}
-				if(!Granularities.DEFAULT.equals(it.getGranularity())) {
-					timeseries.append("granularity", it.getGranularity().name().toLowerCase());
-				}
-				doc.put("timeseries", timeseries);
-			});
+						Document timeseries = new Document("timeField", it.getTimeField());
+						if (StringUtils.hasText(it.getMetaField())) {
+							timeseries.append("metaField", it.getMetaField());
+						}
+						if (!Granularity.DEFAULT.equals(it.getGranularity())) {
+							timeseries.append("granularity", it.getGranularity().name().toLowerCase());
+						}
+						doc.put("timeseries", timeseries);
+					});
 		}
 
 		return doc;
@@ -2849,9 +2851,9 @@ private void executeQueryInternal(CollectionCallback<FindIterable<Document>> col
 				.initiateFind(getAndPrepareCollection(doGetDatabase(), collectionName), collectionCallback::doInCollection)
 				.iterator()) {
 
-				while (cursor.hasNext()) {
-					callbackHandler.processDocument(cursor.next());
-				}
+			while (cursor.hasNext()) {
+				callbackHandler.processDocument(cursor.next());
+			}
 		} catch (RuntimeException e) {
 			throw potentiallyConvertRuntimeException(e, exceptionTranslator);
 		}
@@ -3175,17 +3177,17 @@ private class ReadDocumentCallback<T> implements DocumentCallback<T> {
 
 		public T doWith(Document document) {
 
-				maybeEmitEvent(new AfterLoadEvent<>(document, type, collectionName));
-				T entity = reader.read(type, document);
+			maybeEmitEvent(new AfterLoadEvent<>(document, type, collectionName));
+			T entity = reader.read(type, document);
 
-				if (entity == null) {
-					throw new MappingException(String.format("EntityReader %s returned null", reader));
-				}
+			if (entity == null) {
+				throw new MappingException(String.format("EntityReader %s returned null", reader));
+			}
 
-				maybeEmitEvent(new AfterConvertEvent<>(document, entity, collectionName));
-				entity = maybeCallAfterConvert(entity, document, collectionName);
+			maybeEmitEvent(new AfterConvertEvent<>(document, entity, collectionName));
+			entity = maybeCallAfterConvert(entity, document, collectionName);
 
-				return entity;
+			return entity;
 		}
 	}
 
@@ -3237,8 +3239,8 @@ public T doWith(Document document) {
 
 			Object result = targetType.isInterface() ? projectionFactory.createProjection(targetType, entity) : entity;
 
-				maybeEmitEvent(new AfterConvertEvent<>(document, result, collectionName));
-				return (T) maybeCallAfterConvert(result, document, collectionName);
+			maybeEmitEvent(new AfterConvertEvent<>(document, result, collectionName));
+			return (T) maybeCallAfterConvert(result, document, collectionName);
 		}
 	}
 

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/ReactiveMongoTemplate.java

@@ -17,7 +17,6 @@
 
 import static org.springframework.data.mongodb.core.query.SerializationUtils.*;
 
-import org.springframework.data.mongodb.core.timeseries.Granularities;
 import reactor.core.publisher.Flux;
 import reactor.core.publisher.Mono;
 import reactor.util.function.Tuple2;
@@ -111,6 +110,7 @@
 import org.springframework.data.mongodb.core.query.Query;
 import org.springframework.data.mongodb.core.query.UpdateDefinition;
 import org.springframework.data.mongodb.core.query.UpdateDefinition.ArrayFilter;
+import org.springframework.data.mongodb.core.timeseries.Granularity;
 import org.springframework.data.mongodb.core.validation.Validator;
 import org.springframework.data.mongodb.util.BsonUtils;
 import org.springframework.data.projection.SpelAwareProxyProjectionFactory;
@@ -975,7 +975,8 @@ public <O> Flux<O> aggregate(Aggregation aggregation, String collectionName, Cla
 		return doAggregate(aggregation, collectionName, null, outputType);
 	}
 
-	protected <O> Flux<O> doAggregate(Aggregation aggregation, String collectionName,  @Nullable Class<?> inputType, Class<O> outputType) {
+	protected <O> Flux<O> doAggregate(Aggregation aggregation, String collectionName, @Nullable Class<?> inputType,
+			Class<O> outputType) {
 
 		Assert.notNull(aggregation, "Aggregation pipeline must not be null!");
 		Assert.hasText(collectionName, "Collection name must not be null or empty!");
@@ -987,19 +988,18 @@ protected <O> Flux<O> doAggregate(Aggregation aggregation, String collectionName
 		AggregationDefinition ctx = queryOperations.createAggregation(aggregation, inputType);
 
 		if (LOGGER.isDebugEnabled()) {
-			LOGGER.debug("Streaming aggregation: {} in collection {}", serializeToJsonSafely(ctx.getAggregationPipeline()), collectionName);
+			LOGGER.debug("Streaming aggregation: {} in collection {}", serializeToJsonSafely(ctx.getAggregationPipeline()),
+					collectionName);
 		}
 
 		ReadDocumentCallback<O> readCallback = new ReadDocumentCallback<>(mongoConverter, outputType, collectionName);
-		return execute(collectionName,
-				collection -> aggregateAndMap(collection, ctx.getAggregationPipeline(), ctx.isOutOrMerge(), options,
-						readCallback,
-						ctx.getInputType()));
+		return execute(collectionName, collection -> aggregateAndMap(collection, ctx.getAggregationPipeline(),
+				ctx.isOutOrMerge(), options, readCallback, ctx.getInputType()));
 	}
 
 	private <O> Flux<O> aggregateAndMap(MongoCollection<Document> collection, List<Document> pipeline,
-			boolean isOutOrMerge,
-			AggregationOptions options, ReadDocumentCallback<O> readCallback, @Nullable Class<?> inputType) {
+			boolean isOutOrMerge, AggregationOptions options, ReadDocumentCallback<O> readCallback,
+			@Nullable Class<?> inputType) {
 
 		AggregatePublisher<Document> cursor = collection.aggregate(pipeline, Document.class)
 				.allowDiskUse(options.isAllowDiskUse());
@@ -2510,10 +2510,10 @@ protected CreateCollectionOptions convertToCreateCollectionOptions(@Nullable Col
 
 			TimeSeriesOptions options = new TimeSeriesOptions(it.getTimeField());
 
-			if(StringUtils.hasText(it.getMetaField())) {
+			if (StringUtils.hasText(it.getMetaField())) {
 				options.metaField(it.getMetaField());
 			}
-			if(!Granularities.DEFAULT.equals(it.getGranularity())) {
+			if (!Granularity.DEFAULT.equals(it.getGranularity())) {
 				options.granularity(TimeSeriesGranularity.valueOf(it.getGranularity().name().toUpperCase()));
 			}
 

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/mapping/TimeSeries.java

@@ -22,7 +22,7 @@
 import java.lang.annotation.Target;
 
 import org.springframework.core.annotation.AliasFor;
-import org.springframework.data.mongodb.core.timeseries.Granularities;
+import org.springframework.data.mongodb.core.timeseries.Granularity;
 
 /**
  * Identifies a domain object to be persisted to a MongoDB Time Series collection.
@@ -50,8 +50,9 @@
 	String collection() default "";
 
 	/**
-	 * The name of the property which contains the date in each time series document. <br />
-	 * {@link Field#name() Annotated fieldnames} will be considered during the mapping process.
+	 * Name of the property which contains the date in each time series document. <br />
+	 * Translation of property names to {@link Field#name() annotated fieldnames} will be considered during the mapping
+	 * process.
 	 *
 	 * @return never {@literal null}.
 	 */
@@ -60,19 +61,19 @@
 	/**
 	 * The name of the field which contains metadata in each time series document. Should not be the {@literal id} nor
 	 * {@link #timeField()} nor point to an {@literal array} or {@link java.util.Collection}. <br />
-	 * {@link Field#name() Annotated fieldnames} will be considered during the mapping process.
+	 * Translation of property names to {@link Field#name() annotated fieldnames} will be considered during the mapping
+	 * process.
 	 *
 	 * @return empty {@link String} by default.
 	 */
 	String metaField() default "";
 
 	/**
-	 * Select the {@link Granularities granularity} parameter to define how data in the time series collection is
-	 * organized.
+	 * Select the {@link Granularity granularity} parameter to define how data in the time series collection is organized.
 	 *
-	 * @return {@link Granularities#DEFAULT server default} by default.
+	 * @return {@link Granularity#DEFAULT server default} by default.
 	 */
-	Granularities granularity() default Granularities.DEFAULT;
+	Granularity granularity() default Granularity.DEFAULT;
 
 	/**
 	 * Defines the collation to apply when executing a query or creating indexes.

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/timeseries/Granularity.java

@@ -16,12 +16,30 @@
 package org.springframework.data.mongodb.core.timeseries;
 
 /**
- * The Granularity of time series data that is closest to the time span between incoming measurements.
+ * {@link GranularityDefinition Granularities} available for Time Series data.
  *
  * @author Christoph Strobl
  * @since 3.3
  */
-public interface Granularity {
+public enum Granularity implements GranularityDefinition {
 
-	String name();
+	/**
+	 * Server default value to indicate no explicit value should be sent.
+	 */
+	DEFAULT,
+
+	/**
+	 * High frequency ingestion.
+	 */
+	SECONDS,
+
+	/**
+	 * Medium frequency ingestion.
+	 */
+	MINUTES,
+
+	/**
+	 * Low frequency ingestion.
+	 */
+	HOURS
 }

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/timeseries/Granularities.java spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/timeseries/GranularityDefinition.java

@@ -16,30 +16,12 @@
 package org.springframework.data.mongodb.core.timeseries;
 
 /**
- * {@link Granularity Granularities} available for Time Series data.
+ * The Granularity of time series data that is closest to the time span between incoming measurements.
  *
  * @author Christoph Strobl
  * @since 3.3
  */
-public enum Granularities implements Granularity {
+public interface GranularityDefinition {
 
-	/**
-	 * Server default value to indicate no explicit value should be sent.
-	 */
-	DEFAULT,
-
-	/**
-	 * High frequency ingestion.
-	 */
-	SECONDS,
-
-	/**
-	 * Medium frequency ingestion.
-	 */
-	MINUTES,
-
-	/**
-	 * Low frequency ingestion.
-	 */
-	HOURS
+	String name();
 }