Create Entities to Represent Collections

Unsupported Field Types

Hibernate ORM serializes any Java type that implements java.io.Serializable to binary data when it has no other mapping for that type. To prevent your data from being stored in this format, the Hibernate ORM extension rejects the following types and throws an exception when your application starts. This check applies to primary keys, ordinary fields, embeddable attributes, and collection elements.

The following table describes unsupported field types and their supported alternatives:

Schema Qualifiers

The @Table annotation accepts an optional schema element that prefixes your collection name. When you set both elements, the Hibernate ORM extension maps the entity to a collection named <schema name>.<collection name>.

A schema qualifier changes only the collection's name. A schema is not a separate MongoDB database. Every schema-qualified collection resides in the database that your SessionFactory instance connects to. Because these collections share one database, a transaction can span multiple schemas.

Use the following syntax to apply a schema qualifier:

@Entity
@Table(schema = "<schema name>", name = "<collection name>")
public class <EntityName> {
    // Define your fields, constructors, and methods here
}

Example

This sample Movie.java entity class defines a Movie entity that includes the following information:

• @Entity annotation that marks the class as a Hibernate ORM entity

• @Table annotation that maps the entity to the movies collection from the Atlas sample datasets

• @Id and @ObjectIdGenerator annotations that designate the id field as the primary key and configure automatic ObjectId generation

  Tip

  Primary Key Values

  This example specifies the ObjectId field as the entity's primary key, but you can also set String or int fields as the primary key by using the @Id annotation. To learn more, see Unsupported Field Types.

• Private fields that represent movie data

• Default and parameterized constructors for entity instantiation

• Getter and setter methods that provide access to the entity's fields

package org.example;
import com.mongodb.hibernate.annotations.ObjectIdGenerator;
import org.bson.types.ObjectId;
import java.util.List;
import jakarta.persistence.Entity;
import jakarta.persistence.Id;
import jakarta.persistence.Table;
@Entity
@Table(name = "movies")
public class Movie {
	@Id
	@ObjectIdGenerator
	private ObjectId id;
	private String title;
	private String plot;
	private int year;
	private List<String> cast;
	private List<String> directors;
	public Movie(String title, String plot, int year, List<String> cast, List<String> directors) {
 		this.title = title;
		this.plot = plot;
		this.year = year;
		this.cast = cast;
        this.directors = directors;
 	}
	public Movie() {
	}
	public ObjectId getId() {
		return id;
	}
	public String getTitle() {
		return title;
	}
	public void setTitle(String title) {
		this.title = title;
	}
	public String getPlot() {
		return plot;
	}
	public void setPlot(String plot) {
		this.plot = plot;
	}
	
	public int getYear() {
		return year;
	}
	public void setYear(int year) {
		this.year = year;
	}
	public List<String> getCast() {
		return cast;
	}
	
	public void setCast(List<String> cast) {
		this.cast = cast;
	}
    public List<String> getDirectors() {
        return directors;
    }
    public void setDirectors(List<String> directors) {
        this.directors = directors;
    }
}

Add Sequence-Generated IDs to Your Entity

You can use the @GeneratedValue and @SequenceGenerator annotations to add sequence-generated IDs to your entity. The following example reserves IDs in blocks of 50 from the movies_SEQ counter:

@Id
@GeneratedValue(
    strategy = GenerationType.SEQUENCE,
    generator = "movies_SEQ"
)
@SequenceGenerator(
    name = "movies_SEQ",
    sequenceName = "movies_SEQ",
    allocationSize = 50
)
private Long id;

The annotations control how the Hibernate ORM extension creates the ID:

• @GeneratedValue tells the Hibernate ORM extension to create the value of the id field. Its strategy and generator attributes define how the extension creates the ID:

  • strategy: AUTO or SEQUENCE. With AUTO, the Hibernate ORM extension uses a sequence, and you don't have to declare a @SequenceGenerator. With SEQUENCE, the Hibernate ORM extension uses the sequence generator named by the generator attribute.

  • generator: The name of the @SequenceGenerator to use. If you omit this attribute, the Hibernate ORM extension names the sequence after the entity's table, such as movies_SEQ for the movies table.

• @SequenceGenerator defines the sequence generator:

  • name: The name that the @GeneratedValue generator attribute references.

  • sequenceName: The name of the counter document. If you omit it, the Hibernate ORM extension uses the generator's name.

  • initialValue: The value that the first generated ID starts from. Defaults to 1.

  • allocationSize: The number of IDs reserved in each block.

Where IDs Are Stored

The Hibernate ORM extension stores counter documents in a fixed collection named hibernate_sequences. Each sequence uses one counter document that has the following fields:

• _id is the sequence name.

• next_value is the counter value that the Hibernate ORM extension advances to produce the next IDs. It must match the initialValue of the sequence generator, which defaults to 1.

• increment is the number of IDs reserved at one time. It must match the sequence generator's allocationSize value. If it doesn't, the SessionFactory fails to start.

The Hibernate ORM extension gets IDs in blocks. This reduces the number of times it must contact the database. Requests made at the same time each receive a different ID.

Enable Schema Management

Schema management is Hibernate ORM's way of creating the database objects that your entities need. The Hibernate ORM extension uses it to create the counter documents for sequence-generated IDs.

To enable schema management, set the jakarta.persistence.schema-generation.database.action property in your hibernate.properties or persistence.xml file. Use one of the following values:

• create: Creates the counter documents and keeps them when the SessionFactory closes.

• create-drop: Creates the counter documents when the SessionFactory opens and drops them when it closes.

The following example uses create:

jakarta.persistence.schema-generation.database.action=create

Disable Schema Management and Manual Counter Setup

If you prefer to turn off schema management, you can manually create counter documents for sequence-generated IDs. Set the following property:

jakarta.persistence.schema-generation.database.action=none

Then create one counter document in the hibernate_sequences collection for each sequence. The _id of the counter document must match the sequenceName of the sequence generator.

The following example uses the MongoDB Java driver to insert the movies_SEQ counter document into the hibernate_sequences collection of the database that you indicate:

// Replace the placeholders with your connection string and database name.
MongoClient client = MongoClients.create("<connection string>");
MongoDatabase database = client.getDatabase("<database name>");
database.getCollection("hibernate_sequences").insertOne(
        new Document("_id", "movies_SEQ")
                .append("next_value", new BsonInt64(1))
                .append("increment", new BsonInt64(50)));

{
  "_id": "movies_SEQ",
  "next_value": 1,
  "increment": 50
}

The insert creates the counter document shown. Set next_value to the generator's initialValue and increment to its allocationSize.

Save an Entity and Read Its Generated ID

The following example saves a new Movie entity and prints its generated ID. The ID depends on the starting point of the sequence. For a new counter that starts at 1, the output is:

var movie = new Movie();
movie.setTitle("The Matrix");
session.persist(movie);
System.out.println("Movie created with ID: " + movie.getId());

Movie created with ID: 1

Unsupported Configurations

The Hibernate ORM extension does not support the following sequence-related strategies, types, and configurations:

• IDENTITY and TABLE generation strategies

• BigInteger and BigDecimal generated identifier types

• Sequence names or schemas that contain a . character

• Sequence names qualified by a catalog, such as a three-part name or the catalog attribute

• Sequence options

• @GenericGenerator and @TableGenerator generators, custom generators that use an @IdGeneratorType annotation, and named legacy generators such as identity, table, or increment

• Mapping an entity onto the hibernate_sequences collection

• insert ... select statements that require inline allocation of generated IDs

Composite Key Storage

The Hibernate ORM extension stores a composite key as an _id sub-document. The preceding Book entity produces documents in the following format:

{
  "_id": { "bookNo": 2, "publisherId": 10 },
  "title": "My Book"
}

The Hibernate ORM extension orders the components of the _id sub-document alphabetically by component name, rather than in the order that you declare them. This order is the same whether you declare the embeddable as a class or as a record.

Composite Key Limitations

The Hibernate ORM extension throws a FeatureNotSupportedException when your application starts if you declare a composite key in any of the following ways:

• A non-aggregated identifier, declared either with the @jakarta.persistence.IdClass annotation or with multiple @Id attributes. Declare the key with @EmbeddedId instead.

• A @Struct aggregate embeddable as the identifier. Use a plain @Embeddable instead.

• A component that is not a basic value, such as a nested @Embeddable or a collection. Every component of a composite key must be a basic value.

• An association within the identifier, including derived identity that uses the @jakarta.persistence.MapsId annotation.

You also cannot compare a whole composite identifier by using an ordering operator such as > or <. Compare individual components instead.

One-to-One Relationships

A One-to-One relationship is when a record in one database is associated with exactly one record in another database. In MongoDB, you can create a collection with an embedded document field to model a One-to-One relationship. The Hibernate ORM extension allows you to create embedded document fields by using @Struct aggregate embeddables.

The example defines a field with a @Struct aggregate embeddable type in an entity similar to the Define an Entity example in this guide. The sample Movie.java entity class includes the following information:

• @Entity and @Table annotations that define the entity and map it to the movies collection

• @Id and @ObjectIdGenerator annotations that designate the id field as the primary key

• String field that represents the movie's title

• @Struct aggregate embeddable fields that represent movie awards and studio information

The following example represents a One-to-One relationship because each Movie entity is associated with one Awards embeddable and one Studio embeddable:

@Entity
@Table(name = "movies")
public class Movie {
    @Id
    @ObjectIdGenerator
    private ObjectId id;
    private String title;
    private Awards awards;
    private Studio studio;
    public Movie(String title, Awards awards, Studio studio) {
        this.title = title;
        this.awards = awards;
        this.studio = studio;
    }
    public Movie() {
    }
    // Getter and setter methods
}

The following sample code creates an Awards @Struct aggregate embeddable:

@Embeddable
@Struct(name = "Awards")
public class Awards {
    private int wins;
    private int nominations;
    private String text;
    public Awards(int wins, int nominations, String text) {
       this.wins = wins;
       this.nominations = nominations;
       this.text = text;
    }
    public Awards() {
    }
    // Getter and setter methods
}

The following sample code creates a Studio @Struct aggregate embeddable:

@Embeddable
@Struct(name = "Studio")
public class Studio {
    private String name;
    private String location;
    private int foundedYear;
    public Studio(String name, String location, int foundedYear) {
        this.name = name;
        this.location = location;
        this.foundedYear = foundedYear;
    }
    public Studio() {
    }
    // Getter and setter methods
}

One-to-Many Relationships

A One-to-Many relationship is when a record in one database is associated with many records in another database. In MongoDB, you can define a collection field that stores a list of embedded documents to model a One-to-Many relationship. The Hibernate ORM extension allows you to create embedded document fields by using a list of @Struct aggregate embeddables.

The example defines a field that stores a list of @Struct aggregate embeddables in an entity similar to the Define an Entity Example in this guide. The sample Movie.java entity class includes the following information:

• @Entity and @Table annotations that define the entity and map it to the movies collection

• @Id and @ObjectIdGenerator annotations that designate the id field as the primary key

• String field that represents the movie's title

• List field that stores multiple Writer @Struct aggregate embeddables, which represents writer information

The following example represents a One-to-Many relationship because each Movie entity is associated with multiple Writer embeddables:

@Entity
@Table(name = "movies")
public class Movie {
    @Id
    @ObjectIdGenerator
    @Column(name = "_id")
    private ObjectId id;
    private String title;
    private List<Writer> writers;
    public Movie(String title, List<Writer> writers) {
        this.title = title;
        this.writers = writers;
    }
    public Movie() {
    }
    // Getter and setter methods
}

The following sample code creates a Writer @Struct aggregate embeddable:

@Embeddable
@Struct(name = "Writer")
public class Writer {
    private String name;
    public Writer() {
    }
    public Writer(String name) {
        this.name = name;
    }
    // Getter and setter methods
}

Nested Embeddables

You can nest a flattened embeddable inside a @Struct aggregate embeddable. A flattened embeddable is a class that includes an @Embeddable annotation but not a @Struct annotation. The Hibernate ORM extension stores the fields of a flattened embeddable as fields of the parent embedded document instead of as a separate nested document.

The following sample code creates a Studio @Struct aggregate embeddable that includes an Address flattened embeddable as a field:

@Embeddable
@Struct(name = "Studio")
public class Studio {
    private String name;
    private Address address;
    public Studio() {
    }
    public Studio(String name, Address address) {
        this.name = name;
        this.address = address;
    }
    // Getter and setter methods
}

The following sample code creates the Address flattened embeddable. The class omits the @Struct annotation:

@Embeddable
public class Address {
    private String city;
    private String country;
    public Address() {
    }
    public Address(String city, String country) {
        this.city = city;
        this.country = country;
    }
    // Getter and setter methods
}

When you persist an entity that includes a Studio field, the Address fields become fields of the Studio field's embedded document. The following example document has a Studio field named studio that stores the fields of its Address flattened embeddable:

{
  "_id": { "$oid": "..." },
  "title": "Breathless",
  "studio": {
    "name": "Les Films Impéria",
    "city": "Paris",
    "country": "France"
  }
}