anchor.diff:  to offer various classic mappings between your object model
   and the MongoDB documents.
   
  +[[mongodb-built-in-types]]
  +===== Builtin types
  +
  +Hibernate OGM supports by default the following types:
  +
  +* [classname]+java.lang.String+
  +
  +[source, JSON]
  +----
  +  { "text" : "Hello world!" }
  +----
  +
  +* [classname]+java.lang.Boolean+ (or boolean primitive)
  +
  +[source, JSON]
  +----
  +  { "favorite" : true }
  +----
  +
  +* [classname]+java.lang.Byte+ (or byte primitive)
  +
  +[source, JSON]
  +----
  +  { "display_mask" : "70" }
  +----
  +
  +* [classname]+java.lang.Long+ (or long primitive)
  +
  +[source, JSON]
  +----
  +  { "userId" : NumberLong("-6718902786625749549") }
  +----
  +
  +* [classname]+java.lang.Integer+ (or integer primitive)
  +
  +[source, JSON]
  +----
  +  { "stockCount" : 12309 }
  +----
  +
  +* [classname]+java.lang.Double+ (or double primitive)
  +
  +[source, JSON]
  +----
  +  { "tax_percentage" : 12.34 }
  +----
  +
  +* [classname]+java.math.BigDecimal+
  +
  +[source, JSON]
  +----
  +  { "site_weight" : "21.77" }
  +----
  +
  +* [classname]+java.math.BigInteger+
  +
  +[source, JSON]
  +----
  +  { "site_weight" : "444" }
  +----
  +
  +* [classname]+java.util.Calendar+
  +
  +[source, JSON]
  +----
  +  { "creation" : "2014/11/03 16:19:49:283 +0000" }
  +----
  +
  +* [classname]+java.util.Date+
  +
  +[source, JSON]
  +----
  +  { "last_update" : ISODate("2014-11-03T16:19:49.283Z") }
  +----
  +
  +* [classname]+java.util.UUID+
  +
  +[source, JSON]
  +----
  +  { "serialNumber" : "71f5713d-69c4-4b62-ad15-aed8ce8d10e0" }
  +----
  +
  +* [classname]+java.util.URL+
  +
  +[source, JSON]
  +----
  +  { "url" : "http://www.hibernate.org/" }
  +----
  +
  +* [classname]+java.util.URL+
  +
  +[source, JSON]
  +----
  +  { "url" : "http://www.hibernate.org/" }
  +----
  +
  +* [classname]+java.util.URL+
  +
  +[source, JSON]
  +----
  +  { "url" : "http://www.hibernate.org/" }
  +----
  +
  +* [classname]+org.bson.types.ObjectId+
  +
  +[source, JSON]
  +----
  +  { "object_id" : ObjectId("547d9b40e62048750f25ef77") }
  +----
  +
   ===== Entities
   
  -Entities are stored as MongoDB documents and not as BLOBs
  -which means each entity property will be translated into a document field.
  -You can use the name property of the [classname]+@Table+ and [classname]+@Column+ annotations
  -to rename the collections and the document's fields if you need to.
  -
  -Note that embedded objects are mapped as nested documents.
  -
  -.Example of an entity with an embedded object
  +Entities are stored as MongoDB documents and not as BLOBs:
  +each entity property will be translated into a document field.
  +You can use [classname]+@Table+ and [classname]+@Column+ annotations
  +to rename respectively the collection the document is stored in
  +and the document's field a property is persisted in.
  +
  +.Default JPA mapping for an entity
   ====
   [source, JAVA]
   ----
   @Entity
   public class News {
  +
       @Id
       private String id;
       private String title;
  -    @Column(name="desc")
  -    private String description;
  -    @Embedded
  -    private NewsPaper paper;
  -
  -    //getters, setters ...
  -}
  -
  -@Embeddable
  -public class NewsPaper {
  -    private String name;
  -    private String owner;
  -    //getters, setters ...
  -}
  -----
  -
  -[source, JSON]
  -----
  +
  +    // getters, setters ...
  +}
  +----
  +
  +[source, JSON]
  +----
  +// Stored in the Collection "News"
   {
       "_id" : "1234-5678-0123-4567",
       "title": "On the merits of NoSQL",
  -    "desc": "This paper discuss why NoSQL will save the world for good",
  -    "paper": {
  -        "name": "NoSQL journal of prophecies",
  -        "owner": "Delphy"
  -    }
  +}
  +----
  +====
  +
  +.Rename field and collection using @Table and @Column
  +====
  +[source, JAVA]
  +----
  +@Entity
  +// Overrides the collection name
  +@Table(name = "News_Collection")
  +public class News {
  +
  +    @Id
  +    private String id;
  +
  +    // Overrides the field name
  +    @Column(name = "headline")
  +    private String title;
  +
  +    // getters, setters ...
  +}
  +----
  +
  +[source, JSON]
  +----
  +// Stored in the Collection "News"
  +{
  +    "_id" : "1234-5678-0123-4567",
  +    "headline": "On the merits of NoSQL",
   }
   ----
   ====
   
   ====== Identifiers
   
  -The +_id+ field of a MongoDB document is directly used
  -to store the identifier columns mapped in the entities.
  -You can use simple identifiers (e.g. of type +long+ with a table-based id generator or of type +String+ with a GUID generator)
  -as well as embedded identifiers.
  +[NOTE]
  +====
  +Hibernate OGM always store identifiers using the +_id+ field of a MongoDB document ignoring
  +the name of the property in the entity.
  +====
  +
  +An identifier type may be one of the <<mongodb-built-in-types,built-in types>>
  +or a more complex type represented by an embedded class.
  +When you use a built-in type, the identifier is mapped like a regular property.
  +When you use an embedded class, then the `_id` is representing a nested document
  +containing the embedded class properties.
  +
  +.Define an identifier as a primitive type
  +====
  +[source, JAVA]
  +----
  +@Entity
  +public class Bookmark {
  +
  +    @Id
  +    private String id;
  +
  +    private String title;
  +
  +    // getters, setters ...
  +}
  +----
  +
  +[source, JSON]
  +----
  +{
  +  "_id" : "bookmark_1" 
  +  "title" : "Hibernate OGM documentation"
  +}
  +----
  +====
  +
  +.Define an identifier using @EmbeddedId
  +====
  +[source, JAVA]
  +----
  +@Embeddable
  +public class NewsID implements Serializable {
  +
  +    private String title;
  +    private String author;
  +
  +    // getters, setters ...
  +}
  +
  +@Entity
  +public class News {
  +
  +    @EmbeddedId
  +    private NewsID newsId;
  +    private String content;
  +
  +    // getters, setters ...
  +}
  +----
  +
  +News collection as JSON in MongoDB
  +
  +[source, JSON]
  +----
  +
  +{
  +  "_id" : {
  +      "author" : "Guillaume",
  +      "title" : "How to use Hibernate OGM ?"
  +  },
  +  "content" : "Simple, just like ORM but with a NoSQL database"
  +}
  +
  +----
  +====
   
   Generally, it is recommended though to work with MongoDB's object id data type.
  -This will facilitate the integration with other applications possibly expecting that common MongoDB id type.
  +This will facilitate the integration with other applications expecting that common MongoDB id type.
   To do so, you have two options:
   
  +* Define your id property as +org.bson.types.ObjectId+
   * Define your id property as +String+ and annotate it with +@Type(type="objectid")+
  -* Define your id property as +org.bson.types.ObjectId+
   
   In both cases the id will be stored as native +ObjectId+ in the datastore.
   
  -You can assign id values yourself or (preferably) take advantage of the +IDENTITY+ generation strategy
  -which will automatically assign an id during insert. The following shows an example:
  -
  -.Mapping id as object id in MongoDB
  +.Define an id as ObjectId
  +====
  +[source, JAVA]
  +----
  +@Entity
  +public class News {
  +
  +    @Id
  +    private ObjectId id;
  +
  +    private String title;
  +
  +    // getters, setters ...
  +}
  +----
  +====
  +
  +.Define an id of type String as ObjectId
  +====
  +[source, JAVA]
  +----
  +@Entity
  +public class News {
  +
  +    @Id
  +    @Type(type = "objectid")
  +    private String id;
  +
  +    private String title;
  +
  +    // getters, setters ...
  +}
  +----
  +====
  +
  +====== Identifier generation strategies
  +
  +You can assign id values yourself or let Hibernate OGM generate the value using the
  +[classname]+@GeneratedValue+ annotation.
  +
  +There are 4 different strategies:
  +
  +1. <<mongodb-identity-id-generation-strategy, IDENTITY>> (suggested)
  +2. <<mongodb-table-id-generation-strategy, TABLE>>
  +3. <<mongodb-sequence-id-generation-strategy, SEQUENCE>>
  +4. <<mongodb-auto-id-generation-strategy, AUTO>>
  +
  +[[mongodb-identity-id-generation-strategy]]
  +*1) IDENTITY generation strategy*
  +
  +The preferable strategy, Hibernate OGM will create the identifier upon insertion.
  +To apply this strategy the id must be one of the following:
  +
  +* annotated with +@Type(type="objectid")+
  +* [classname]+org.bson.types.ObjectId+ 
  +
  +like in the following examples:
  +
  +.Define an id of type String as ObjectId
   ====
   [source, JAVA]
   ----
  
positive.code:     @AssociationStorage(AssociationStorageType.IN_ENTITY)
      private Set<Person> visitors;
  
      //...
  }
  ----
  ====
  
negative.code: ----
  ====
  
  .Define an id as ObjectId
  ====
  [source, JAVA]
  ----
  @Entity
  public class News {
  
      @Id
      @GeneratedValue(strategy = GenerationType.IDENTITY)
      private ObjectId id;
  
      private String title;
  
      // getters, setters ...
  }
  ----
  
  [source, JSON]
  ----
  {
      "_id" : ObjectId("5425448830048b67064d40b1"),
      "title" : "Exciting News"
  }
  ----
  ====
  
  [[mongodb-table-id-generation-strategy]]
  *2) TABLE generation strategy*
  
  .Id generation strategy TABLE using default values
  ====
  [source, JAVA]
  ----
  @Entity
  public class GuitarPlayer {
  
      @Id
      @GeneratedValue(strategy = GenerationType.TABLE)
      private Long id;
  
      private String name;
  
      // getters, setters ...
  }
  
  ----
  
  GuitarPlayer collection
  
  [source, JSON]
  ----
  {
      "_id" : NumberLong(1),
      "name" : "Buck Cherry"
  }
  ----
  
  hibernate_sequences collection
  
  [source, JSON]
  ----
  { 
      "_id" : "GuitarPlayer",
      "next_val" : 101
  }
  ----
  ====
  
  .Id generation strategy TABLE using a custom table
  ====
  [source, JAVA]
  ----
  @Entity
  public class GuitarPlayer {
  
      @Id
      @GeneratedValue(strategy = GenerationType.TABLE, generator = "guitarGen")
      @TableGenerator(
          name = "guitarGen",
          table = "GuitarPlayerSequence",
          pkColumnValue = "guitarPlayer",
          valueColumnName = "nextGuitarPlayerId"
      )
      private long id;
  
      // getters, setters ...
  }
  
  ----
  
  GuitarPlayer collection
  
  [source, JSON]
  ----
  {
      "_id" : NumberLong(1),
      "name" : "Buck Cherry"
  }
  ----
  
  GuitarPlayerSequence collection
  
  [source, JSON]
  ----
  {
      "_id" : "guitarPlayer",
      "nextGuitarPlayerId" : 2
  }
  ----
  ====
  
  *3) SEQUENCE generation strategy*
  
  [[mongodb-sequence-id-generation-strategy]]
  .SEQUENCE id generation strategy using default values
  ====
  [source, JAVA]
  ----
  @Entity
  public class Song {
  
    @Id
    @GeneratedValue(strategy = GenerationType.SEQUENCE)
    private Long id;
  
    private String title;
  
    // getters, setters ...
  }
  ----
  
  Song collection
  
  [source, JSON]
  ----
  {
    "_id" : NumberLong(2),
    "title" : "Flower Duet"
  }
  ----
  
  hibernate_sequences collection
  
  [source, JSON]
  ----
  { "_id" : "song_sequence_name", "next_val" : 21 } 
  ----
  ====
  
  [[mongodb-sequence-id-generation-strategy-custom]]
  .SEQUENCE id generation strategy using custom values
  ====
  [source, JAVA]
  ----
  @Entity
  public class Song {
  
    @Id
    @GeneratedValue(strategy = GenerationType.SEQUENCE, generator = "songSequenceGenerator")
    @SequenceGenerator(
        name = "songSequenceGenerator",
        sequenceName = "song_seq",
        initialValue = 2,
        allocationSize = 20
    )
    private Long id;
  
    private String title;
  
    // getters, setters ...
  }
  ----
  
  Song collection
  
  [source, JSON]
  ----
  {
    "_id" : NumberLong(2),
    "title" : "Flower Duet"
  }
  ----
  
  hibernate_sequences collection
  
  [source, JSON]
  ----
  { "_id" : "song_seq", "next_val" : 42 } 
  ----
  ====
  
  [[mongodb-auto-id-generation-strategy]]
  *4) AUTO generation strategy*
  
  [WARNING]
  ====
  Care must be taken when using the +GenerationType.AUTO+ strategy.
  When the property +hibernate.id.new_generator_mappings+ is set to +false+ (default),
  