Crie entidades para representar coleções

Tipos de campo não suportados

O Hibernate ORM serializa qualquer tipo Java que implementa java.io.Serializable para dados binários quando não há outro mapeamento para esse tipo. Para evitar que seus dados sejam armazenados neste formato, a extensão Hibernate ORM rejeita os seguintes tipos e lança uma exceção quando seu aplicativo é iniciado. Esta verificação aplica-se a chaves primárias, campos comuns, atributos incorporáveis e elementos de coleção.

A tabela a seguir descreve tipos de campo não suportados e suas alternativas suportadas:

Qualificadores de esquema

A anotação @Table aceita um elemento schema opcional que prefixa o nome da sua coleção. Ao definir ambos os elementos, a extensão Hibernate ORM mapeia a entidade para uma coleção chamada <schema name>.<collection name>.

Um qualificador de esquema altera apenas o nome da coleção. Um esquema não é um banco de dados MongoDB separado. Cada coleção qualificada por esquema reside no banco de dados ao qual sua instância SessionFactory se conecta. Como essas coleções compartilham um banco de dados, uma transação pode abranger vários esquemas.

Use a seguinte sintaxe para aplicar um qualificador de esquema:

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

Exemplo

Esta classe de entidade do Movie.java de amostra define uma entidade do Movie que inclui as seguintes informações:

• @Entity anotação que marca a classe como uma entidade ORM do Hibernar

• @Table anotação que mapeia a entidade para a coleção movies a partir dos conjuntos de dados de amostra do Atlas

• @Id e @ObjectIdGenerator anotações que designam o campo id como a chave primária e configuram a geração automática de ObjectId

  Dica

  Valores de chave primária

  Este exemplo especifica o campo ObjectId como a chave primária da entidade, mas você também pode definir os campos String ou int como a chave primária usando a anotação @Id. Para saber mais, consulte Tipos de campo sem suporte.

• Campos privados que representam dados do filme

• Construtores padrão e parametrizados para instanciação de entidade

• Métodos de getter e setter que fornecem acesso aos campos da entidade

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

Adicione IDs gerados por sequência à sua entidade

Você pode usar as anotações @GeneratedValue e @SequenceGenerator para adicionar IDs gerados por sequência à sua entidade. O exemplo a seguir reserva IDs em blocos de 50 do contador movies_SEQ:

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

As anotações controlam como a extensão Hibernate ORM cria o ID:

• @GeneratedValue informa à extensão Hibernate ORM para criar o valor do campo id. Seus atributos strategy e generator definem como a extensão cria o ID:

  • strategy: AUTO ou SEQUENCE. Com AUTO, a extensão Hibernate ORM usa uma sequência, e você não precisa declarar um @SequenceGenerator. Com SEQUENCE, a extensão Hibernate ORM usa o gerador de sequências nomeado pelo atributo generator.

  • generator: O nome do @SequenceGenerator a ser usado. Se você omitir este atributo, a extensão Hibernate ORM nomeia a sequência após a tabela da entidade, como movies_SEQ para a tabela movies.

• @SequenceGenerator define o gerador de sequência:

  • name: O nome que o atributo @GeneratedValue generator referencia.

  • sequenceName: O nome do documento de contador. Se você omiti-lo, a extensão Hibernate ORM usa o name do gerador.

  • initialValue: O valor a partir do qual o primeiro ID gerado começa. O padrão é 1.

  • allocationSize: O número de IDs reservados em cada bloco.

Onde os IDs são armazenados

A extensão Hibernate ORM armazena documentos de contador em uma coleção fixa chamada hibernate_sequences. Cada sequência usa um documento de contador que possui os seguintes campos:

• _id é o nome da sequência.

• next_value é o valor do contador que a extensão Hibernate ORM avança para produzir os próximos IDs. Ele deve corresponder ao initialValue do gerador de sequência, que é definido como 1 por padrão.

• increment é o número de IDs reservados de uma só vez. Deve corresponder ao valor allocationSize do gerador de sequência. Se não corresponder, o SessionFactory falhará ao iniciar.

A extensão Hibernate ORM obtém IDs em blocos. Isso reduz o número de vezes que ele precisa entrar em contato com o banco de dados. As solicitações feitas ao mesmo tempo recebem cada uma um ID diferente.

Habilitar o gerenciamento de esquema

O gerenciamento de esquema é a maneira do Hibernate ORM de criar os objeto de banco de dados de que suas entidades precisam. A extensão Hibernate ORM a utiliza para criar os documentos de contador para IDs gerados por sequência.

Para habilitar o gerenciamento de esquema, defina a propriedade jakarta.persistence.schema-generation.database.action no seu arquivo hibernate.properties ou persistence.xml. Use um dos seguintes valores:

• create: Cria os documento de contador e os mantém quando o SessionFactory fecha.

• create-drop: Cria os documentos de contador quando o SessionFactory abre e os descarta quando ele fecha.

O exemplo a seguir usa create:

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

Desativar o gerenciamento de esquema e configurar manualmente o contador

Se você preferir desativar o gerenciamento de esquema, poderá criar manualmente documentos de contador para IDs gerados por sequência. Defina a seguinte propriedade:

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

Em seguida, crie um documento de contador na coleção hibernate_sequences para cada sequência. O _id do documento de contador deve corresponder ao sequenceName do gerador de sequências.

O exemplo a seguir usa o driver Java do MongoDB para inserir o documento de contador movies_SEQ na coleção hibernate_sequences do banco de dados que você indicar:

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

A inserção cria o documento de contador mostrado. Defina next_value para initialValue do gerador e increment para seu allocationSize.

Salvar uma entidade e ler seu ID gerado

O exemplo a seguir salva uma nova entidade Movie e imprime seu ID gerado. O ID depende do ponto inicial da sequência. Para um novo contador que começa em 1, a saída é:

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

Configurações não suportadas

A extensão Hibernate ORM não oferece suporte às seguintes estratégias, tipos e configurações relacionados a sequências:

• IDENTITY e TABLE estratégias de geração

• BigInteger e BigDecimal tipos de identificadores gerados

• Nomes de sequência ou esquema que contenham um caractere .

• Nomes de sequência qualificados por um catálogo, como um nome de três partes ou o atributo catalog

• Sequência options

• @GenericGenerator e geradores @TableGenerator, geradores personalizados que usam uma anotação @IdGeneratorType e geradores legados nomeados como identity, table ou increment

• Mapeando uma entidade para a coleção hibernate_sequences

• insert ... select declarações que exigem alocação em linha de IDs gerados

Onde os UUIDs são armazenados

A extensão Hibernate ORM armazena um valor java.util.UUID como um valor BSON Binary com subtipo 4. O seguinte documento de exemplo tem um campo _id com um UUID gerado:

{  "_id": {    "$binary": {      "base64": "FXvL4sBrQoueEByraiJUmA==",      "subType": "04"    }  },  "title": "The Matrix"}

Se o campo @Id for um String, a extensão Hibernate ORM armazena o UUID gerado como um String BSON em vez de um valor Binary BSON.

Para saber mais sobre os mapeamentos de tipo de campo BSON, consulte a seção MongoDB BSON Fields deste guia.

Salve uma entidade e leia seu UUID gerado

O exemplo a seguir salva uma nova entidade UuidItem e imprime seu ID gerado:

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

UuidItem created with ID: 157bcbe2-c06b-428b-9e10-1cab6a225498

Limitações de UUID

A extensão Hibernate ORM tem as seguintes limitações ao usar IDs gerados por UUID:

• A extensão Hibernate ORM não oferece suporte aos nomes de gerador de identificador legado uuid, uuid.hex, uuid2 e guid. Se você especificar um desses nomes, a extensão Hibernate ORM lançará um FeatureNotSupportedException quando seu aplicativo for iniciado. Use @UuidGenerator ou @GeneratedValue(strategy = GenerationType.UUID) em vez disso.

• Se você atribuir o valor de um campo @UuidGenerator @Id antes de persistir a entidade, a extensão Hibernate ORM lançará uma jakarta.persistence.EntityExistsException. Para atribuir valores UUID por conta própria, remova a anotação do gerador do campo @Id.

Armazenamento de chave composta

A extensão Hibernate ORM armazena uma chave composta como um subdocumento _id. A entidade Book anterior produz documentos no seguinte formato:

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

A extensão Hibernate ORM ordena os componentes do subdocumento _id alfabeticamente pelo nome do componente, em vez da ordem em que você os declara. Essa ordem é a mesma, independentemente de você declarar o embeddable como uma classe ou como um registro.

Limitações de chave composta

A extensão Hibernate ORM lança uma FeatureNotSupportedException quando seu aplicativo é iniciado se você declarar uma chave composta de qualquer uma das seguintes maneiras:

• Um identificador não agregado, declarado com a anotação @jakarta.persistence.IdClass ou com vários atributos @Id. Declare a chave com @EmbeddedId em vez disso.

• Um @Struct agregado incorporável como identificador. Use um @Embeddable simples em vez disso.

• Um componente que não é um valor básico, como um @Embeddable aninhado ou uma coleção. Cada componente de uma chave composta deve ser um valor básico.

• Uma associação dentro do identificador, incluindo identidade derivada que usa a anotação @jakarta.persistence.MapsId.

Você também não pode comparar um identificador composto inteiro usando um operador de ordenação como > ou <. Compare componentes individuais em vez disso.

Relacionamentos um-para-um

Um relacionamento um-para-um é quando um registro em um banco de dados está associado a exatamente um registro em outro banco de dados. No MongoDB , você pode criar uma coleção com um campo de documento incorporado para modelar um relacionamento um-para-um. A extensão Hibername ORM permite criar campos de documento incorporado usando @Struct embeddables agregados.

O exemplo define um campo com um tipo incorporável agregado @Struct em uma entidade semelhante ao exemplo Definir uma entidade neste guia. A classe de entidade de amostra Movie.java inclui as seguintes informações:

• @Entity e anotações @Table que definem a entidade e a mapeiam para a coleção movies

• @Id e @ObjectIdGenerator anotações que designam o campo id como a chave primária

• campo de string que representa o título do filme

• @Struct campos incorporáveis agregados que representam prêmios de filme e informações do atlas

O exemplo a seguir representa um relacionamento um-para-um porque cada entidade Movie está associada a um Awards incorporável e a um Studio incorporável:

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

O seguinte código de amostra cria um agregado Awards @Struct incorporável:

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

O seguinte código de amostra cria um agregado Studio @Struct incorporável:

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

Relacionamentos um-para-muitos

Um relacionamento um-para-muitos é quando um registro em um banco de dados está associado a muitos registros em outro banco de dados. No MongoDB, você pode definir um campo de coleção que armazena uma lista de documentos incorporados para modelar um relacionamento um-para-muitos. A extensão Hibername ORM permite criar campos de documento incorporado usando uma lista de @Struct incorporáveis agregados.

O exemplo define um campo que armazena uma lista de @Struct incorporáveis agregados em uma entidade semelhante ao Exemplo de Definir uma Entidade neste guia. A classe de entidade de amostra Movie.java inclui as seguintes informações:

• @Entity e anotações @Table que definem a entidade e a mapeiam para a coleção movies

• @Id e @ObjectIdGenerator anotações que designam o campo id como a chave primária

• campo de string que representa o título do filme

• campo de lista que armazena vários embeddables agregados do Writer @Struct, que representa informações do escritor

O exemplo a seguir representa um relacionamento um-para-muitos porque cada entidade Movie está associada a vários incorporáveis Writer:

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

O seguinte código de amostra cria um agregado Writer @Struct incorporável:

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

Embeddables aninhados

Você pode aninhar um embeddable achatado dentro de um embeddable agregado @Struct. Um embeddable achatado é uma classe que inclui uma anotação @Embeddable, mas não uma anotação @Struct. A extensão Hibernate ORM armazena os campos de um embeddable achatado como campos do documento incorporado pai, em vez de como um documento aninhado separado.

O código de amostra a seguir cria um Studio @Struct agregado incorporável que inclui um Address incorporável achatado como um campo:

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

O código de amostra a seguir cria o Address incorporável achatado. A classe omite a anotação @Struct:

@Embeddablepublic 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
}

Ao persistir uma entidade que inclui um campo Studio, os campos Address tornam-se campos do documento incorporado do campo Studio. O exemplo de documento a seguir tem um campo Studio chamado studio que armazena os campos de seu Address incorporável achatado:

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