DATAMONGO-1798 - Polishing.

Introduce FieldType to express the desired field type to use for MongoDB Id conversion. Adapt Querydsl Id conversion so Id values are converted in the QueryMapper and no longer in SpringDataMongodbSerializer.

Adapt tests. Move MongoId from o.s.d.mongodb to o.s.d.m.c.core. Javadoc, reference docs.

Original pull request: #617.

src/main/asciidoc/reference/mapping.adoc

@@ -53,7 +53,9 @@ The following outlines what field will be mapped to the `_id` document field:
 
 The following outlines what type conversion, if any, will be done on the property mapped to the _id document field.
 
-* If a field named `id` is declared as a String or BigInteger in the Java class it will be converted to and stored as an ObjectId if possible. ObjectId as a field type is also valid. If you specify a value for `id` in your application, the conversion to an ObjectId is detected to the MongoDBdriver. If the specified `id` value cannot be converted to an ObjectId, then the value will be stored as is in the document's _id field.
+* If a field named `id` is declared as a String or BigInteger in the Java class it will be converted to and stored as an ObjectId if possible. ObjectId as a field type is also valid. If you specify a value for `id` in your application, the conversion to an ObjectId is detected to the MongoDB driver. If the specified `id` value cannot be converted to an ObjectId, then the value will be stored as is in the document's _id field. This also applies if the field is annotated with `@Id`.
+* If a field is annotated with `@MongoId` in the Java class it will be converted to and stored as using its actual type. No further conversion happens unless `@MongoId` declares a desired field type.
+* If a field is annotated with `@MongoId(FieldType.…)` in the Java class it will be attempted to convert the value to the declared `FieldType.`
 * If a field named `id` id field is not declared as a String, BigInteger, or ObjectID in the Java class then you should assign it a value in your application so it can be stored 'as-is' in the document's _id field.
 * If no field named `id` is present in the Java class then an implicit `_id` file will be generated by the driver but not mapped to a property or field of the Java class.
 
@@ -384,6 +386,7 @@ IMPORTANT: Automatic index creation is only done for types annotated with `@Docu
 The MappingMongoConverter can use metadata to drive the mapping of objects to documents. The following annotations are available:
 
 * `@Id`: Applied at the field level to mark the field used for identity purpose.
+* `@MongoId`: Applied at the field level to mark the field used for identity purpose. Accepts an optional `FieldType` to customize id conversion.
 * `@Document`: Applied at the class level to indicate this class is a candidate for mapping to the database. You can specify the name of the collection where the database will be stored.
 * `@DBRef`: Applied at the field to indicate it is to be stored using a com.mongodb.DBRef.
 * `@Indexed`: Applied at the field level to describe how to index the field.

src/main/asciidoc/reference/mongodb.adoc

@@ -669,8 +669,8 @@ If no field or property specified in the previous sets of rules is present in th
 
 When querying and updating, `MongoTemplate` uses the converter that corresponds to the preceding rules for saving documents so that field names and types used in your queries can match what is in your domain classes.
 
-Some environments however require a different approach to mapping `Id` values. Maybe data has feed to mongodb not running throught the Spring Data mapping layer, an thus containing plain `String` values as `id` that represent a valid `ObjectId`.
-Reading documents from the store back to the domain type works just fine but querying for documents via their `id` is cumbersome due to the `ObjectId` conversion. Therefore documents cannot be retrieved that way.
+Some environments require a customized approach to map `Id` values such as data stored in MongoDB that did not run through the Spring Data mapping layer. Documents can contain `_id` values that can be represented either as `ObjectId` or as `String`.
+Reading documents from the store back to the domain type works just fine. Querying for documents via their `id` can be cumbersome due to the implicit `ObjectId` conversion. Therefore documents cannot be retrieved that way.
 For those cases `@MongoId` provides more control over the actual id mapping attempts.
 
 .`@MongoId` mapping
@@ -686,12 +686,12 @@ public class PlainObjectId {
 }
 
 public class StringToObjectId {
-  @MongoId(ObjectId.class) String id; <3>
+  @MongoId(FieldType.OBJECT_ID) String id; <3>
 }
 ----
-<1> The id is treated as `String` no matter what.
+<1> The id is treated as `String` without further conversion.
 <2> The id is treated as `ObjectId`.
-<3> The id is treated as `ObjectId` if the given `String` is a valid ObjectId hex, otherwise as String.
+<3> The id is treated as `ObjectId` if the given `String` is a valid `ObjectId` hex, otherwise as `String`. Corresponds to `@Id` usage.
 ====
 
 [[mongo-template.type-mapping]]