DATAMONGO-1391 - Support Mongo 3.2 syntax for $unwind in aggregation.

We now support both, the simple {$unwind: path} and the MongoDB 3.2 {$unwind: {…}} syntax.

Original Pull Request: #355

Author: mp911de

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

@@ -193,13 +193,56 @@ public static ProjectionOperation project(Fields fields) {
 	/**
 	 * Factory method to create a new {@link UnwindOperation} for the field with the given name.
 	 *
-	 * @param fieldName must not be {@literal null} or empty.
+	 * @param field must not be {@literal null} or empty.
 	 * @return
 	 */
 	public static UnwindOperation unwind(String field) {
 		return new UnwindOperation(field(field));
 	}
 
+	/**
+	 * Factory method to create a new {@link UnwindOperation} for the field with the given name and
+	 * {@code preserveNullAndEmptyArrays}. Note that extended unwind is supported in MongoDB version 3.2+.
+	 *
+	 * @param field must not be {@literal null} or empty.
+	 * @param preserveNullAndEmptyArrays {@literal true} to output the document if path is {@literal null}, missing or
+	 *          array is empty.
+	 * @return
+	 * @since 1.10
+	 */
+	public static UnwindOperation unwind(String field, boolean preserveNullAndEmptyArrays) {
+		return new UnwindOperation(field(field), preserveNullAndEmptyArrays);
+	}
+
+	/**
+	 * Factory method to create a new {@link UnwindOperation} for the field with the given name and to include the index
+	 * field as {@code arrayIndex}. Note that extended unwind is supported in MongoDB version 3.2+.
+	 *
+	 * @param field must not be {@literal null} or empty.
+	 * @param arrayIndex must not be {@literal null} or empty.
+	 * @return
+	 * @since 1.10
+	 */
+	public static UnwindOperation unwind(String field, String arrayIndex) {
+		return new UnwindOperation(field(field), field(arrayIndex), false);
+	}
+
+	/**
+	 * Factory method to create a new {@link UnwindOperation} for the field with the given name, to include the index
+	 * field as {@code arrayIndex} and {@code preserveNullAndEmptyArrays}. Note that extended unwind is supported in
+	 * MongoDB version 3.2+.
+	 *
+	 * @param field must not be {@literal null} or empty.
+	 * @param arrayIndex must not be {@literal null} or empty.
+	 * @param preserveNullAndEmptyArrays {@literal true} to output the document if path is {@literal null}, missing or
+	 *          array is empty.
+	 * @return
+	 * @since 1.10
+	 */
+	public static UnwindOperation unwind(String field, String arrayIndex, boolean preserveNullAndEmptyArrays) {
+		return new UnwindOperation(field(field), field(arrayIndex), preserveNullAndEmptyArrays);
+	}
+
 	/**
 	 * Creates a new {@link GroupOperation} for the given fields.
 	 *

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2013-2014 the original author or authors.
+ * Copyright 2013-2016 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.
@@ -30,6 +30,7 @@
  * 
  * @author Oliver Gierke
  * @author Thomas Darimont
+ * @author Mark Paluch
  * @since 1.3
  */
 public final class ExposedFields implements Iterable<ExposedField> {
@@ -203,8 +204,13 @@ private int exposedFieldsCount() {
 	public Iterator<ExposedField> iterator() {
 
 		CompositeIterator<ExposedField> iterator = new CompositeIterator<ExposedField>();
-		iterator.add(syntheticFields.iterator());
-		iterator.add(originalFields.iterator());
+		if (!syntheticFields.isEmpty()) {
+			iterator.add(syntheticFields.iterator());
+		}
+
+		if (!originalFields.isEmpty()) {
+			iterator.add(originalFields.iterator());
+		}
 
 		return iterator;
 	}

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2013-2015 the original author or authors.
+ * Copyright 2013-2016 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.
@@ -28,29 +28,207 @@
  * @see http://docs.mongodb.org/manual/reference/aggregation/unwind/#pipe._S_unwind
  * @author Thomas Darimont
  * @author Oliver Gierke
+ * @author Mark Paluch
  * @since 1.3
  */
-public class UnwindOperation implements AggregationOperation {
+public class UnwindOperation
+		implements AggregationOperation, FieldsExposingAggregationOperation.InheritsFieldsAggregationOperation {
 
 	private final ExposedField field;
+	private final ExposedField arrayIndex;
+	private final boolean preserveNullAndEmptyArrays;
 
 	/**
 	 * Creates a new {@link UnwindOperation} for the given {@link Field}.
 	 * 
 	 * @param field must not be {@literal null}.
 	 */
 	public UnwindOperation(Field field) {
+		this(new ExposedField(field, true), false);
+	}
+
+	/**
+	 * Creates a new {@link UnwindOperation} using Mongo 3.2 syntax.
+	 * 
+	 * @param field must not be {@literal null}.
+	 * @param preserveNullAndEmptyArrays {@literal true} to output the document if path is {@literal null}, missing or
+	 *          array is empty.
+	 * @since 1.10
+	 */
+	public UnwindOperation(Field field, boolean preserveNullAndEmptyArrays) {
+		Assert.notNull(field, "Field must not be null!");
+
+		this.field = new ExposedField(field, true);
+		this.arrayIndex = null;
+		this.preserveNullAndEmptyArrays = preserveNullAndEmptyArrays;
+	}
+
+	/**
+	 * Creates a new {@link UnwindOperation} using Mongo 3.2 syntax.
+	 * 
+	 * @param field must not be {@literal null}.
+	 * @param arrayIndex optional field name to expose the field array index, must not be {@literal null}.
+	 * @param preserveNullAndEmptyArrays {@literal true} to output the document if path is {@literal null}, missing or
+	 *          array is empty.
+	 * @since 1.10
+	 */
+	public UnwindOperation(Field field, Field arrayIndex, boolean preserveNullAndEmptyArrays) {
+
+		Assert.notNull(field, "Field must not be null!");
+		Assert.notNull(arrayIndex, "ArrayIndex must not be null!");
 
-		Assert.notNull(field);
 		this.field = new ExposedField(field, true);
+		this.arrayIndex = new ExposedField(arrayIndex, true);
+		this.preserveNullAndEmptyArrays = preserveNullAndEmptyArrays;
 	}
 
-	/* 
+	/*
 	 * (non-Javadoc)
 	 * @see org.springframework.data.mongodb.core.aggregation.AggregationOperation#toDocument(org.springframework.data.mongodb.core.aggregation.AggregationOperationContext)
 	 */
 	@Override
 	public Document toDocument(AggregationOperationContext context) {
-		return new Document("$unwind", context.getReference(field).toString());
+
+		String unwindField = context.getReference(field).toString();
+		Object unwindArg;
+
+		if (preserveNullAndEmptyArrays || arrayIndex != null) {
+
+			Document builder = new Document().append("path", unwindField);
+			builder = builder.append("preserveNullAndEmptyArrays", preserveNullAndEmptyArrays);
+
+			if (arrayIndex != null) {
+				builder = builder.append("includeArrayIndex", arrayIndex.getName());
+			}
+
+			unwindArg = builder;
+		} else {
+			unwindArg = unwindField;
+		}
+
+		return new Document("$unwind", unwindArg);
+	}
+
+	@Override
+	public ExposedFields getFields() {
+		return arrayIndex != null ? ExposedFields.from(arrayIndex) : ExposedFields.from();
 	}
+
+	/**
+	 * Get a builder that allows creation of {@link LookupOperation}.
+	 *
+	 * @return
+	 */
+	public static PathBuilder newUnwind() {
+		return UnwindOperationBuilder.newBuilder();
+	}
+
+	public static interface PathBuilder {
+
+		/**
+		 * @param path the path to unwind, must not be {@literal null} or empty.
+		 * @return
+		 */
+		IndexBuilder path(String path);
+	}
+
+	public static interface IndexBuilder {
+
+		/**
+		 * Exposes the array index as {@code field}.
+		 * 
+		 * @param field field name to expose the field array index, must not be {@literal null} or empty.
+		 * @return
+		 */
+		EmptyArraysBuilder arrayIndex(String field);
+
+		/**
+		 * Do not expose the array index.
+		 * 
+		 * @return
+		 */
+		EmptyArraysBuilder noArrayIndex();
+	}
+
+	public static interface EmptyArraysBuilder {
+
+		/**
+		 * Output documents if the array is null or empty.
+		 * 
+		 * @return
+		 */
+		UnwindOperation preserveNullAndEmptyArrays();
+
+		/**
+		 * Do not output documents if the array is null or empty.
+		 * 
+		 * @return
+		 */
+		UnwindOperation skipNullAndEmptyArrays();
+	}
+
+	/**
+	 * Builder for fluent {@link UnwindOperation} creation.
+	 *
+	 * @author Mark Paluch
+	 * @since 1.10
+	 */
+	public static final class UnwindOperationBuilder implements PathBuilder, IndexBuilder, EmptyArraysBuilder {
+
+		private Field field;
+		private Field arrayIndex;
+
+		private UnwindOperationBuilder() {}
+
+		/**
+		 * Creates new builder for {@link UnwindOperation}.
+		 *
+		 * @return never {@literal null}.
+		 */
+		public static PathBuilder newBuilder() {
+			return new UnwindOperationBuilder();
+		}
+
+		@Override
+		public UnwindOperation preserveNullAndEmptyArrays() {
+
+			if (arrayIndex != null) {
+				return new UnwindOperation(field, arrayIndex, true);
+			}
+
+			return new UnwindOperation(field, true);
+		}
+
+		@Override
+		public UnwindOperation skipNullAndEmptyArrays() {
+
+			if (arrayIndex != null) {
+				return new UnwindOperation(field, arrayIndex, false);
+			}
+
+			return new UnwindOperation(field, false);
+		}
+
+		@Override
+		public EmptyArraysBuilder arrayIndex(String field) {
+			Assert.hasText(field, "'ArrayIndex' must not be null or empty!");
+			arrayIndex = Fields.field(field);
+			return this;
+		}
+
+		@Override
+		public EmptyArraysBuilder noArrayIndex() {
+			arrayIndex = null;
+			return this;
+		}
+
+		@Override
+		public UnwindOperationBuilder path(String path) {
+			Assert.hasText(path, "'Path' must not be null or empty!");
+			field = Fields.field(path);
+			return this;
+		}
+
+	}
+
 }

spring-data-mongodb/src/test/java/org/springframework/data/mongodb/core/aggregation/AggregationTests.java

@@ -238,6 +238,64 @@ public void shouldAggregateEmptyCollection() {
 		assertThat(tagCount.size(), is(0));
 	}
 
+	/**
+	 * @see DATAMONGO-1391
+	 */
+	@Test
+	public void shouldUnwindWithIndex() {
+
+		MongoCollection<Document> coll = mongoTemplate.getCollection(INPUT_COLLECTION);
+
+		coll.insertOne(createDocument("Doc1", "spring", "mongodb", "nosql"));
+		coll.insertOne(createDocument("Doc2"));
+
+		Aggregation agg = newAggregation( //
+				project("tags"), //
+				unwind("tags", "n"), //
+				project("n") //
+						.and("tag").previousOperation(), //
+				sort(DESC, "n") //
+		);
+
+		AggregationResults<TagCount> results = mongoTemplate.aggregate(agg, INPUT_COLLECTION, TagCount.class);
+
+		assertThat(results, is(notNullValue()));
+
+		List<TagCount> tagCount = results.getMappedResults();
+
+		assertThat(tagCount, is(notNullValue()));
+		assertThat(tagCount.size(), is(3));
+	}
+
+	/**
+	 * @see DATAMONGO-1391
+	 */
+	@Test
+	public void shouldUnwindPreserveEmpty() {
+
+		MongoCollection<Document> coll = mongoTemplate.getCollection(INPUT_COLLECTION);
+
+		coll.insertOne(createDocument("Doc1", "spring", "mongodb", "nosql"));
+		coll.insertOne(createDocument("Doc2"));
+
+		Aggregation agg = newAggregation( //
+				project("tags"), //
+				unwind("tags", "n", true), //
+				sort(DESC, "n") //
+		);
+
+		AggregationResults<Document> results = mongoTemplate.aggregate(agg, INPUT_COLLECTION, Document.class);
+
+		assertThat(results, is(notNullValue()));
+
+		List<Document> tagCount = results.getMappedResults();
+
+		assertThat(tagCount, is(notNullValue()));
+		assertThat(tagCount.size(), is(4));
+		assertThat(tagCount.get(0), isBsonObject().containing("n", 2L));
+		assertThat(tagCount.get(3), isBsonObject().notContaining("n"));
+	}
+
 	@Test
 	public void shouldDetectResultMismatch() {