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. You cannot use a java.util.UUID field as the primary key. 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;
    }
}

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"
  }
}