Enhance support for linking documents.

[christophstrobl]

Using @DocumentReference offers an alternative way of linking entities in MongoDB. While the goal is the same as when using @DBRef, the store representation is different. Document references, do not follow a specific format. They can be literally anything, a single value, an entire document, basically everything that can be stored in MongoDB.
By default, the mapping layer will use the referenced entities id value for storage and retrieval, like in the sample below.

@Document
public class Account {

  @Id
  private String id;
  private Float total;
}

@Document
public class Person {

  @Id
  private String id;

  @DocumentReference
  private List<Account> accounts;
}

Account account = ...

tempate.insert(account);

template.update(Person.class)
  .matching(where("id").is("6c78727"))
  .apply(new Update().push("accounts").value(account)) 
  .first();

{
  "_id" : "6c78727",
  "accounts" : [ "6509b9e", "d3e21be" ] 
}

The sample above uses an _id based fetch query ({ '_id' : ?#{#target} }) for data retrieval and resolves linked entities eagerly.

@DocumentReference(lookup=...) allows to define custom queries that are independent from the _id field and therefore offer a flexible way of defining links between entities as demonstrated in the sample below, where the Publisher of a book is referenced by its acronym instead of the internal id.

@Document
public class Book {

  @Id
  private ObjectId id;
  private String title;
  private List<String> author;

  @Field("publisher_ac")
  @DocumentReference(lookup = "{ 'acronym' : ?#{#target} }")
  private Publisher publisher;
}

@Document
public class Publisher {

  @Id
  private ObjectId id;
  private String acronym;
  private String name;

  @DocumentReference(lazy = true)
  private List<Book> books;

}

{
  "_id" : "9a48e32",
  "title" : "The Warded Man",
  "author" : ["Peter V. Brett"],
  "publisher_ac" : "DR"
}

The above snipped shows the reading side of things when working with custom linked objects. To make the writing part aware of the modified document pointer a custom converter, capable of the transformation into a DocumentPointer, like the one below, needs to be registered.

@WritingConverter
class PublisherReferenceConverter implements Converter<Publisher, DocumentPointer<String>> {

	@Override
	public DocumentPointer<String> convert(Publisher source) {
		return () -> source.getAcronym();
	}
}

[mp911de]

That's merged and polished now.

[yihtserns]

#3602

(Manually link because nobody linked these two related things)