Convention-based Mapping

MappingMongoConverter has a few conventions for mapping objects to documents when no additional mapping metadata is provided. The conventions are:

  • The short Java class name is mapped to the collection name in the following manner. The class com.bigbank.SavingsAccount maps to the savingsAccount collection name.

  • All nested objects are stored as nested objects in the document and not as DBRefs.

  • The converter uses any Spring Converters registered with it to override the default mapping of object properties to document fields and values.

  • The fields of an object are used to convert to and from fields in the document. Public JavaBean properties are not used.

  • If you have a single non-zero-argument constructor whose constructor argument names match top-level field names of document, that constructor is used. Otherwise, the zero-argument constructor is used. If there is more than one non-zero-argument constructor, an exception will be thrown.

How the _id field is handled in the mapping layer.

MongoDB requires that you have an _id field for all documents. If you don’t provide one the driver will assign a ObjectId with a generated value. The "_id" field can be of any type the, other than arrays, so long as it is unique. The driver naturally supports all primitive types and Dates. When using the MappingMongoConverter there are certain rules that govern how properties from the Java class is mapped to this _id field.

The following outlines what field will be mapped to the _id document field:

  • A field annotated with @Id (org.springframework.data.annotation.Id) will be mapped to the _id field.

  • A field without an annotation but named id will be mapped to the _id field.

  • The default field name for identifiers is _id and can be customized via the @Field annotation.

Table 1. Examples for the translation of _id field definitions
Field definition Resulting Id-Fieldname in MongoDB

String id

_id

@Field String id

_id

@Field("x") String id

x

@Id String x

_id

@Field("x") @Id String x

_id

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 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.

When querying and updating MongoTemplate will use the converter to handle conversions of the Query and Update objects that correspond to the above rules for saving documents so field names and types used in your queries will be able to match what is in your domain classes.