Update Documentation

Author: christophstrobl

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

@@ -519,13 +519,15 @@ private void readAssociation(Association<MongoPersistentProperty> association, P
 
 			if (conversionService.canConvert(DocumentPointer.class, property.getActualType())) {
 
-				// collection like special treatment
-				accessor.setProperty(property, conversionService.convert(new DocumentPointer() {
+				DocumentPointer<?> pointer = new DocumentPointer<Object>() {
 					@Override
 					public Object getPointer() {
 						return value;
 					}
-				}, property.getActualType()));
+				};
+
+				// collection like special treatment
+				accessor.setProperty(property, conversionService.convert(pointer, property.getActualType()));
 			} else {
 				accessor.setProperty(property,
 						dbRefResolver.resolveReference(property, value, referenceReader, context::convert));

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

@@ -16,9 +16,19 @@
 package org.springframework.data.mongodb.core.mapping;
 
 /**
+ * A custom pointer to a linked document to be used along with {@link DocumentReference} for storing the linkage value.
+ * 
  * @author Christoph Strobl
  */
 @FunctionalInterface
 public interface DocumentPointer<T> {
+
+	/**
+	 * The actual pointer value. This can be any simple type, like a {@link String} or {@link org.bson.types.ObjectId} or
+	 * a {@link org.bson.Document} holding more information like the target collection, multiple fields forming the key,
+	 * etc.
+	 * 
+	 * @return the value stored in MongoDB and used for constructing the {@link DocumentReference#lookup() lookup query}.
+	 */
 	T getPointer();
 }

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

@@ -24,8 +24,69 @@
 import org.springframework.data.annotation.Reference;
 
 /**
+ * A {@link DocumentReference} offers an alternative way of linking entities in MongoDB. While the goal is the same as
+ * when using {@link DBRef}, the store representation is different and can be literally anything, a single value, an
+ * entire {@link org.bson.Document}, basically everything that can be stored in MongoDB. By default, the mapping layer
+ * will use the referenced entities {@literal id} value for storage and retrieval.
+ * 
+ * <pre class="code">
+ * public class Account {
+ *   private String id;
+ *   private Float total;
+ * }
+ *
+ * public class Person {
+ *   private String id;
+ *   &#64;DocumentReference
+ *   private List&lt;Account&gt; accounts;
+ * }
+ * 
+ * Account account = ...
+ *
+ * mongoTemplate.insert(account);
+ *
+ * template.update(Person.class)
+ *   .matching(where("id").is(...))
+ *   .apply(new Update().push("accounts").value(account))
+ *   .first();
+ * </pre>
+ * 
+ * {@link #lookup()} allows to define custom queries that are independent from the {@literal id} field and in
+ * combination with {@link org.springframework.data.convert.WritingConverter writing converters} offer a flexible way of
+ * defining links between entities.
+ * 
+ * <pre class="code">
+ * public class Book {
+ * 	 private ObjectId id;
+ * 	 private String title;
+ *
+ * 	 &#64;Field("publisher_ac")
+ * 	 &#64;DocumentReference(lookup = "{ 'acronym' : ?#{#target} }")
+ * 	 private Publisher publisher;
+ * }
+ *
+ * public class Publisher {
+ *
+ * 	 private ObjectId id;
+ * 	 private String acronym;
+ * 	 private String name;
+ *
+ * 	 &#64;DocumentReference(lazy = true)
+ * 	 private List&lt;Book&gt; books;
+ * }
+ *
+ * &#64;WritingConverter
+ * public class PublisherReferenceConverter implements Converter&lt;Publisher, DocumentPointer&lt;String&gt;&gt; {
+ *
+ *    public DocumentPointer&lt;String&gt; convert(Publisher source) {
+ * 		return () -> source.getAcronym();
+ *    }
+ * }
+ * </pre>
+ *
  * @author Christoph Strobl
  * @since 3.3
+ * @see <a href="https://docs.mongodb.com/manual/reference/database-references/#std-label-document-references">MongoDB Reference Documentation</a>
  */
 @Documented
 @Retention(RetentionPolicy.RUNTIME)
@@ -36,15 +97,36 @@
 	/**
 	 * The database the linked entity resides in.
 	 *
-	 * @return empty String by default.
+	 * @return empty String by default. Uses the default database provided buy the {@link org.springframework.data.mongodb.MongoDatabaseFactory}.
 	 */
 	String db() default "";
 
+	/**
+	 * The database the linked entity resides in.
+	 *
+	 * @return empty String by default. Uses the property type for collection resolution.
+	 */
 	String collection() default "";
 
+	/**
+	 * The single document lookup query. In case of an {@link java.util.Collection} or {@link java.util.Map} property
+	 * the individual lookups are combined via an `$or` operator.
+	 *
+	 * @return an {@literal _id} based lookup.
+	 */
 	String lookup() default "{ '_id' : ?#{#target} }";
 
+	/**
+	 * A specific sort.
+	 *
+	 * @return empty String by default.
+	 */
 	String sort() default "";
 
+	/**
+	 * Controls whether the referenced entity should be loaded lazily. This defaults to {@literal false}.
+	 *
+	 * @return {@literal false} by default.
+	 */
 	boolean lazy() default false;
 }

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

@@ -38,6 +38,7 @@
 import org.junit.jupiter.api.extension.ExtendWith;
 import org.springframework.core.convert.converter.Converter;
 import org.springframework.data.annotation.Id;
+import org.springframework.data.annotation.PersistenceConstructor;
 import org.springframework.data.convert.WritingConverter;
 import org.springframework.data.mongodb.core.convert.LazyLoadingTestUtils;
 import org.springframework.data.mongodb.core.mapping.DocumentPointer;
@@ -73,7 +74,8 @@ public class MongoTemplateDocumentReferenceTests {
 		});
 
 		cfg.configureConversion(it -> {
-			it.customConverters(new ReferencableConverter());
+			it.customConverters(new ReferencableConverter(), new SimpleObjectRefWithReadingConverterToDocumentConverter(),
+					new DocumentToSimpleObjectRefWithReadingConverter());
 		});
 
 		cfg.configureMappingContext(it -> {
@@ -793,6 +795,28 @@ void updateReferenceMapWithValue() {
 		assertThat(target).containsEntry("mapValueRef", new Document("beastie", "ref-1").append("rise", "ref-2"));
 	}
 
+	@Test // GH-3602
+	void useReadingWriterConverterPairForLoading() {
+
+		SingleRefRoot root = new SingleRefRoot();
+		root.id = "root-1";
+		root.withReadingConverter = new SimpleObjectRefWithReadingConverter("ref-1", "value-1");
+
+		template.save(root.withReadingConverter);
+
+		template.save(root);
+
+		Document target = template.execute(db -> {
+			return db.getCollection(template.getCollectionName(SingleRefRoot.class))
+					.find(Filters.eq("_id", root.id)).first();
+		});
+
+		assertThat(target).containsEntry("withReadingConverter", new Document("ref-key-from-custom-write-converter", root.withReadingConverter.id));
+
+		SingleRefRoot loaded = template.findOne(query(where("id").is(root.id)), SingleRefRoot.class);
+		assertThat(loaded.withReadingConverter).isInstanceOf(SimpleObjectRefWithReadingConverter.class);
+	}
+
 	@Data
 	static class SingleRefRoot {
 
@@ -868,9 +892,10 @@ static class SimpleObjectRef {
 	@Setter
 	static class SimpleObjectRefWithReadingConverter extends SimpleObjectRef {
 
-		public SimpleObjectRefWithReadingConverter(String id, String value, String id1, String value1) {
+		public SimpleObjectRefWithReadingConverter(String id, String value) {
 			super(id, value);
 		}
+
 	}
 
 	@Data
@@ -927,17 +952,12 @@ public DocumentPointer convert(ReferenceAble source) {
 	class DocumentToSimpleObjectRefWithReadingConverter
 			implements Converter<DocumentPointer<Document>, SimpleObjectRefWithReadingConverter> {
 
-		private final MongoTemplate template;
-
-		public DocumentToSimpleObjectRefWithReadingConverter(MongoTemplate template) {
-			this.template = template;
-		}
-
 		@Nullable
 		@Override
 		public SimpleObjectRefWithReadingConverter convert(DocumentPointer<Document> source) {
-			return template.findOne(query(where("id").is(source.getPointer().get("the-ref-key-you-did-not-expect"))),
-					SimpleObjectRefWithReadingConverter.class);
+
+			Document document = client.getDatabase(DB_NAME).getCollection("simple-object-ref").find(Filters.eq("_id", source.getPointer().get("ref-key-from-custom-write-converter"))).first();
+			return new SimpleObjectRefWithReadingConverter(document.getString("_id"), document.getString("value"));
 		}
 	}
 
@@ -948,7 +968,7 @@ class SimpleObjectRefWithReadingConverterToDocumentConverter
 		@Nullable
 		@Override
 		public DocumentPointer<Document> convert(SimpleObjectRefWithReadingConverter source) {
-			return () -> new Document("the-ref-key-you-did-not-expect", source.getId());
+			return () -> new Document("ref-key-from-custom-write-converter", source.getId());
 		}
 	}
 
@@ -980,4 +1000,15 @@ public Object toReference() {
 			return id;
 		}
 	}
+
+	static class ReferencedObject {}
+
+	class ToDocumentPointerConverter implements Converter<ReferencedObject, DocumentPointer<Document>> {
+
+		@Nullable
+		@Override
+		public DocumentPointer<Document> convert(ReferencedObject source) {
+			return () -> new Document("", source);
+		}
+	}
 }

src/main/asciidoc/new-features.adoc

@@ -1,6 +1,11 @@
 [[new-features]]
 = New & Noteworthy
 
+[[new-features.3.3]]
+== What's New in Spring Data MongoDB 3.3
+
+* Extended support for <<mapping-usage.linking, linking>> entities.
+
 [[new-features.3.2]]
 == What's New in Spring Data MongoDB 3.2