컬렉션을 나타내는 엔터티 만들기

지원되지 않는 필드 유형

Hibernate ORM은 해당 유형에 대한 다른 매핑이 없는 경우 java.io.Serializable을(를) 구현하는 모든 Java 유형을 이진 데이터로 직렬화합니다. 데이터가 이 형식으로 저장되지 않도록 Hibernate ORM 확장은 다음 유형을 거부하고 애플리케이션이 시작될 때 예외를 발생시킵니다. 이 검사는 기본 키, 일반 필드, 포함 가능한 속성 및 컬렉션 요소에 적용됩니다.

다음 표는 지원되지 않는 필드 유형과 지원되는 대안을 설명합니다.

스키마 한정자

@Table 어노테이션은 컬렉션 이름 앞에 접두사를 붙이는 선택 사항인 schema 요소를 허용합니다. 두 요소를 모두 설정하면 Hibernate ORM 확장이 엔티티를 <schema name>.<collection name>라는 이름의 컬렉션에 매핑합니다.

스키마 한정자는 컬렉션의 이름만 변경합니다. 스키마는 별도의 MongoDB 데이터베이스가 아닙니다. 모든 스키마 한정 컬렉션은 SessionFactory 인스턴스가 연결되는 데이터베이스에 상주합니다. 이러한 컬렉션은 하나의 데이터베이스를 공유하므로 트랜잭션이 여러 스키마에 걸쳐 있을 수 있습니다.

스키마 한정자를 적용하려면 다음 구문을 사용하세요.

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

예시

이 샘플 Movie.java 클래스는 다음 정보를 포함하는 Movie 엔티티를 정의합니다.

• @Entity 클래스를 최대 절전 모드 ORM 엔터티로 표시하는 주석

• @Table Atlas 샘플 데이터 세트의 컬렉션 에 엔터티를매핑하는 주석 movies

• @Id 및 id 필드 기본 키 지정하고 자동 ObjectId 생성을 구성하는 @ObjectIdGenerator 주석

  팁

  기본 키 값

  이 예시에서는 ObjectId 필드를 엔터티의 기본 키로 지정하지만, @Id 주석을 사용하여 String 또는 int 필드를 기본 키로 설정할 수도 있습니다. 자세한 내용은 지원되지 않는 필드 유형을 참조하세요.

• 영화 데이터를 나타내는 비공개 필드

• 엔터티 인스턴스화를 위한 기본 생성자 및 매개변수화된 생성자

• 엔터티의 필드에 대한 액세스 제공하는 Getter 및 setter 메서드

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

엔티티에 시퀀스 생성 ID 추가

@GeneratedValue 및 @SequenceGenerator 주석을 사용하여 시퀀스로 생성된 ID를 엔터티에 추가할 수 있습니다. 다음 예시는 movies_SEQ 카운터에서 50 블록 단위로 ID를 예약합니다.

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

주석은 Hibernate ORM 확장이 ID를 어떻게 생성하는지를 제어합니다:

• @GeneratedValue Hibernate ORM 확장에게 id 필드의 값을 생성하도록 지시합니다. 그 strategy 및 generator 속성은 확장기능이 ID를 만들는 방식을 정의합니다.

  • strategy: AUTO 또는 SEQUENCE. AUTO을 사용하면 Hibernate ORM 확장은 시퀀스를 사용하고, @SequenceGenerator을 선언할 필요가 없습니다. SEQUENCE을 사용하면, Hibernate ORM 확장은 generator 속성으로 이름이 지정된 시퀀스 생성기를 사용합니다.

  • generator: 사용할 @SequenceGenerator의 이름입니다. 이 속성을 생략하면 Hibernate ORM 확장은 movies 테이블의 경우 movies_SEQ와 같이 엔티티의 테이블 이름을 따서 시퀀스 이름을 지정합니다.

• @SequenceGenerator 시퀀스 생성기를 접의합니다:

  • name: @GeneratedValue generator 속성이 참조하는 이름입니다.

  • sequenceName: 카운터 문서의 이름입니다. 생략하면 Hibernate ORM 확장이 생성자의 name을(를) 사용합니다.

  • initialValue: 첫 번째 생성된 ID가 시작되는 값. 기본값은 1입니다.

  • allocationSize: 각 블록에 예약된 ID의 수입니다.

ID가 저장되는 위치

Hibernate ORM 확장은 hibernate_sequences이라는 고정 컬렉션에 카운터 문서를 저장합니다. 각 시퀀스는 다음 필드가 있는 하나의 카운터 문서를 사용합니다.

• _id 은 시퀀스 이름입니다.

• next_value Hibernate ORM 확장이 다음 ID를 생성하기 위해 증가시키는 카운터 값입니다. 이는 시퀀스 생성기의 initialValue과 일치해야 하며, 기본값은 1입니다.

• increment 한 번에 예약되는 ID의 수입니다. 시퀀스 생성기의 allocationSize 값과 일치해야 합니다. 일치하지 않으면 SessionFactory이(가) 시작되지 않습니다.

Hibernate ORM 확장은 블록 단위로 ID를 가져옵니다. 이렇게 하면 데이터베이스에 문의해야 하는 횟수가 줄어듭니다. 동시에 이루어진 요청은 각각 다른 ID를 받습니다.

스키마 관리 활성화

스키마 관리는 엔터티에 필요한 데이터베이스 객체를 생성하는 Hibernate ORM의 방식입니다. Hibernate ORM 확장은 이를 사용하여 시퀀스로 생성된 ID에 대한 카운터 문서를 생성합니다.

스키마 관리를 활성화하려면 hibernate.properties 또는 persistence.xml 파일에서 jakarta.persistence.schema-generation.database.action 속성을 설정하세요. 다음 값 중 하나를 사용합니다.

• create: 카운터 문서를 생성하고 SessionFactory이(가) 닫힐 때 해당 문서를 유지합니다.

• create-drop: SessionFactory이 열릴 때 카운터 문서를 생성하고 닫힐 때 제거합니다.

다음 예시에서는 create을(를) 사용합니다.

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

스키마 관리 및 수동 카운터 설정 비활성화

스키마 관리를 해제하려면 시퀀스 생성 ID에 대한 카운터 문서를 수동으로 만들 수 있습니다. 다음 속성을 설정합니다.

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

그리고 나서 각 시큰스에 대해 hibernate_sequences 컬렉션에서 카운터 문서 하나를 만듭니다. 카운터 문서의 _id은 시퀀스 생성기의 sequenceName와 일치해야 합니다.

다음 예제에서는 MongoDB Java 드라이버를 사용하여 movies_SEQ 카운터 문서를 지정한 데이터베이스의 hibernate_sequences 컬렉션에 삽입합니다.

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

삽입을 통해 표시된 카운터 문서를 생성합니다. next_value을(를) 생성기의 initialValue (으)로 설정하고 increment을(를) 해당 allocationSize(으)로 설정합니다.

엔티티 저장 및 생성된 ID 읽기

다음 예시는 새로운 Movie 엔티티를 저장하고 생성된 ID를 출력합니다. ID는 시퀀스의 시작점에 따라 다릅니다. 1에서 시작하는 새 카운터의 출력은 다음과 같습니다.

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

지원되지 않는 구성

Hibernate ORM 확장은 다음의 시퀀스 관련 전략, 형식 및 구성을 지원하지 않습니다.

• IDENTITY 그리고 TABLE 생성 전략

• BigInteger 및 BigDecimal 생성된 식별자 유형

• . 문자를 포함하는 시퀀스 이름 또는 스키마

• 3부 이름 또는 catalog 속성과 같이 카탈로그로 한정된 시퀀스 이름

• 시퀀스 options

• @GenericGenerator 및 @TableGenerator 생성기, @IdGeneratorType 주석을 사용하는 사용자 지정 생성기, identity, table 또는 increment와 같은 명명된 레거시 생성기

• 엔티티를 hibernate_sequences 컬렉션에 매핑

• insert ... select 생성된 ID의 내장 할당이 필요한 성명서

UUID가 저장되는 위치

Hibernate ORM 확장은 java.util.UUID 값을 하위 유형 4의 BSON Binary 값으로 저장합니다. 다음 예시 문서는 생성된 UUID가 있는 _id 필드를 포함합니다.

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

@Id 필드가 String인 경우, Hibernate ORM 확장은 생성된 UUID를 BSON Binary 값이 아닌 BSON String로 저장합니다.

BSON 필드 유형 매핑에 대해 자세히 학습 보려면 이 가이드의 MongoDB BSON 필드 섹션을 참조하세요.

엔티티 저장 및 생성된 UUID 읽기

다음 예시는 새로운 UuidItem 엔티티를 저장하고 생성된 ID를 출력합니다.

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

UUID 제한 사항

UUID로 생성된 ID를 사용할 때 Hibernate ORM 확장에는 다음과 같은 제한 사항이 있습니다.

• Hibernate ORM 확장은 레거시 식별자 생성기 이름 uuid, uuid.hex, uuid2, guid을 지원하지 않습니다. 이러한 이름 중 하나를 지정하면 애플리케이션이 시작될 때 Hibernate ORM 확장이 FeatureNotSupportedException를 throw합니다. 대신 @UuidGenerator 또는 @GeneratedValue(strategy = GenerationType.UUID)을 사용하세요.

• 엔티티를 지속하기 전에 @UuidGenerator @Id 필드에 값을 할당하면 Hibernate ORM 확장에서 jakarta.persistence.EntityExistsException가 발생합니다. UUID 값을 직접 할당하려면 @Id 필드에서 생성기 주석을 제거하세요.

복합 키 저장

Hibernate ORM 확장은 복합 키를 _id 하위 문서로 저장합니다. 앞의 Book 엔티티는 다음 형식으로 문서를 생성합니다.

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

Hibernate ORM 확장은 _id 하위 문서의 구성 요소를 선언한 순서가 아니라 구성 요소 이름순으로 정렬합니다. 이 순서는 임베디드 가능 항목을 클래스로 선언하든 기록으로 선언하든 동일합니다.

복합 키 제한 사항

다음 방법 중 하나로 복합 키를 선언하면 애플리케이션이 시작될 때 Hibernate ORM 확장이 FeatureNotSupportedException을(를) throw합니다.

• @jakarta.persistence.IdClass 어노테이션 또는 여러 @Id 속성으로 선언된 비집계 식별자입니다. 대신 @EmbeddedId로 키를 선언하세요.

• 식별자로 임베딩할 수 있는 @Struct 애그리게이션입니다. 대신 일반 @Embeddable을(를) 사용하세요.

• 중첩된 @Embeddable 또는 컬렉션과 같이 기본 값이 아닌 구성 요소입니다. 복합 키의 모든 구성 요소는 기본 값이어야 합니다.

• @jakarta.persistence.MapsId 주석을 사용하는 파생 ID를 포함하여 식별자 내의 연결입니다.

또한 > 또는 <과 같은 순서 연산자를 사용하여 전체 복합 식별자를 비교할 수 없습니다. 대신 개별 구성 요소를 비교하세요.

일대일 관계

일대일 관계 한 데이터베이스 의 기록 다른 데이터베이스 의 정확히 하나의 기록 와 연결되는 경우입니다. MongoDB 에서는 내장된 문서 필드 가 있는 컬렉션 만들어 일대일 관계 모델링할 수 있습니다. 하이버네이트 ORM 확장을 사용하면 @Struct 애그리게이션 임베더블을 사용하여 내장된 문서 필드를 생성할 수 있습니다.

이 예시에서는 이 가이드의 엔터티 정의 예시 와 유사한 엔터티에 @Struct 애그리게이션 임베딩 가능 유형이 있는 필드를 정의합니다. 샘플 Movie.java 클래스에는 다음 정보가 포함되어 있습니다.

• @Entity 및 엔티티를 정의하고 이를 movies 컬렉션 에 매핑하는 @Table 주석

• @Id 및 id 필드 기본 키 지정하는 @ObjectIdGenerator 주석

• 영화의 제목을 나타내는 String 필드

• @Struct 영화 시상 및 스튜디오 정보를 나타내는 임베딩 가능한 필드 애그리게이션

다음 예시 각 Movie 엔터티가 하나의 Awards 임베딩 가능 항목 및 하나의 Studio 임베딩 가능 항목과 연결되어 있으므로 일대일 관계 나타냅니다.

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

다음 샘플 코드는 Awards @Struct 임베딩 가능 애그리게이션을 생성합니다.

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

다음 샘플 코드는 Studio @Struct 임베딩 가능한 애그리게이션을 생성합니다.

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

일대다 관계

일대다 관계 는 한 데이터베이스 의 기록 다른 데이터베이스 의 여러 레코드와 연결된 경우를 말합니다. MongoDB 에서는 내장된 문서 목록을 저장하는 컬렉션 필드 정의하여 일대다 관계 모델링할 수 있습니다. 하이버네이트 ORM 확장을 사용하면 @Struct 애그리게이션 임베더블 목록을 사용하여 내장된 문서 필드를 생성할 수 있습니다.

이 예시에서는 이 가이드의 엔터티 정의 예시 와 유사하게 엔터티에 @Struct 애그리게이션 임베더블 목록을 저장하는 필드를 정의합니다. 샘플 Movie.java 클래스에는 다음 정보가 포함되어 있습니다.

• @Entity 및 엔티티를 정의하고 이를 movies 컬렉션 에 매핑하는 @Table 주석

• @Id 및 id 필드 기본 키 지정하는 @ObjectIdGenerator 주석

• 영화의 제목을 나타내는 String 필드

• 작성기 정보를 나타내는 여러 Writer @Struct 애그리게이션 임베더블을 저장하는 목록 필드

다음 예시 각 Movie 엔터티가 여러 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
}

다음 샘플 코드는 Writer @Struct 임베딩 가능한 애그리게이션을 생성합니다.

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

중첩된 임베딩 가능 항목

flattened embeddable을 @Struct aggregate embeddable 내에 중첩할 수 있습니다. flattened embeddable은 @Embeddable 주석은 포함하지만 @Struct 주석은 포함하지 않는 클래스입니다. Hibernate ORM 확장은 flattened embeddable의 필드를 별도의 중첩된 문서가 아닌 부모 내장된 문서의 필드로 저장합니다.

다음 샘플 코드는 Address 평면화된 임베딩 가능 항목을 필드로 포함하는 Studio @Struct 애그리게이션 임베딩 가능 항목을 생성합니다.

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

다음 샘플 코드는 Address 평면화된 임베딩 가능 항목을 생성합니다. 이 클래스는 @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
}

Studio 필드를 포함하는 엔티티를 유지하면 Address 필드가 Studio 필드의 내장된 문서의 필드가 됩니다. 다음 예시 문서에는 Address 평면화된 임베더블의 필드를 저장하는 studio 라는 Studio 필드가 있습니다.

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