Các Annotation của Hibernate

Bài viết được sự cho phép của tác giả Giang Phan

Hibernate sử dụng các Annotation để mô tả các thông tin cho một Entity. Chúng ta có thể sử dụng các Annotation nằm trong package javax.persistence của Java Persistence API hoặc sử dụng các annotation trong API của hibernate nằm trong package org.hibernate.annotations. Tuy nhiên, tôi khuyến khích các bạn sử dụng các Annotation của Java Persistence API bởi vì sau này chúng ta muốn chuyển sang một ORM khác sẽ dễ dàng hơn mà không phải thay đổi code.

Trong bài này, tôi sẽ hướng dẫn các Annotation thông dụng nhất của Java Persistence API để mô tả thông tin cho một Entity.

@Entity

@Entity được sử dụng để chú thích một class là một Entity.

Thuộc tính name của @Entity là không bắt buộc. Việc chỉ định rõ name của @Entity cho phép viết ngắn câu HSQL.

Entity khớp với một bảng lấy theo tên theo thứ tự ưu tiên:

1. name trong @Table.
2. name trong @Entity.
3. name của class.

@Table

Một table trong database có thể có nhiều ràng buộc unique (duy nhất). Chúng ta có thể sử dụng @Table để mô tả các ràng buộc này.

@Table cho phép chú thích tên bảng thông qua thuộc tính name (thuộc tính này không bắt buộc).

Nếu không chỉ rõ tên bảng trong phần tử name, Hibernate sẽ dựa vào phần tử name của @Entity sau đó mới tới tên của class.

@Column

@Column được sử dụng để chỉ định thông tin chi tiết của cột mà một field của entity sẽ được ánh xạ với một column trong database.

• Thuộc tính name được sử dụng để chị định tên cột nào trong database map với tên field được chú thích. Nếu không chỉ định, Hibernate sẽ lấy tên field map với tên cột trong database.
• Thuộc tính length cho phép kích thước của cột. @Column không chỉ rõ phần tử length, mặc định nó là 255.
• Thuộc tính nullable cho phép cột được đánh dấu KHÔNG NULL khi schema được tạo ra. Giá trị nullable mặc định là true.
• Thuộc tính unique cho phép cột được đánh dấu chỉ chứa các giá trị duy nhất.

Chúng ta có thể không cần chỉ định @Column cho tất cả các field nếu tên field và tên column và tên trong database là giống nhau.

@Transient

Trong một số trường hợp, trong entity class có chứa một field mà field này không tồn tồn tại trong database. Khi đó chúng ta sẽ gặp lỗi “java.sql.SQLSyntaxErrorException: Unknown column ‘additionalPropery’ in ‘field list’”.

Để tránh lỗi này, chúng ta có thể sử dụng @Transient để thông báo rằng thuộc tính/ phương thức này không liên quan gì tới một cột nào dưới database. Khi đó, Hibernate sẽ bỏ qua field này.

@Temporal

@Temporal sử dụng để chú thích cho cột dữ liệu ngày tháng và thời gian (date time).

Có 3 giá trị cho TemporalType:

• TemporalType.DATE : chú thích cột sẽ lưu trữ ngày tháng năm (bỏ đi thời gian).
• TemporalType.TIME : chú thích cột sẽ lưu trữ thời gian (Giờ phút giây).
• TemporalType.TIMESTAMP : chú thích cột sẽ lưu trữ ngày tháng và cả thời gian.

@Id

@Id được sử dụng để mô tả đây là Id (Identity) của Entity, nó tương đương với cột đó là khóa chính (Primary Key) của table trong database.

Khóa chính có thể là một trường duy nhất hoặc kết hợp nhiều trường tùy thuộc vào cấu trúc bảng trong database.

Ví dụ:

CREATE TABLE `user` (
`id` bigint(20) unsigned NOT NULL AUTO_INCREMENT,
`fullname` varchar(255) COLLATE utf8mb4_unicode_ci DEFAULT NULL,
`username` varchar(255) CHARACTER SET utf8mb4 DEFAULT '',
`password` varchar(255) COLLATE utf8mb4_unicode_ci DEFAULT NULL,
`created_at` datetime DEFAULT NULL ON UPDATE current_timestamp(),
`modified_at` datetime DEFAULT NULL ON UPDATE current_timestamp(),
PRIMARY KEY (`id`),
UNIQUE KEY `unique_user_username` (`username`)
) ENGINE=InnoDB AUTO_INCREMENT=3 DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

Ta có thể tạo Entity tương ứng với database trên như sau:

package com.gpcoder.entities;

import java.util.Date;

import javax.persistence.Column;
import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.GenerationType;
import javax.persistence.Id;
import javax.persistence.Table;
import javax.persistence.Temporal;
import javax.persistence.TemporalType;
import javax.persistence.Transient;

import lombok.Data;

@Data
@Entity(name = "User")
@Table(name = "user")
public class User {

@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;

@Column
private String fullname;

@Column(nullable = false, length = 255, unique = true)
private String username;

@Column(nullable = false)
private String password;

@Column(name = "created_at")
@Temporal(value = TemporalType.TIMESTAMP)
private Date createdAt;

@Column(name = "modified_at")
@Temporal(value = TemporalType.TIMESTAMP)
private Date modifiedAt;

@Transient
private String additionalPropery;
}

@GeneratedValue

@GeneratedValue được sử dụng để Hibernate tự động tạo ra giá trị và gán vào cho một cột trong trường hợp insert mới một Entity vào database. Nó có thể gắn trên cột Id hoặc một cột nào đó.

Annotation này cũng được sử dụng cùng với @Generator.

Theo mặc định, chú thích @Id sẽ tự động xác định chiến lược tạo primary key, nhưng có thể ghi đè bằng cách áp dụng chú thích @GeneratedValue có hai tham số strategy và generator.

GenerationType.AUTO

Column được đánh dấu bởi @GeneratedValue(strategy= AUTO) sẽ được gán giá trị tự động, giá trị đó có thể được sinh ra bởi SEQUENCE hoặc tự tăng (Nếu cột này có kiểu IDENTITY). Nó phụ thuộc vào loại database.

Với Oracle, PostgreSQL, Hibernate nó sẽ gọi một Sequence có tên Hibernate_Sequence để tạo ra một giá trị tăng dần để gán giá trị cho cột này. Với các DB khác chẳng hạn như MySQL, DB2, SQL Server, Sysbase cột có thể là kiểu IDENTITY và giá trị của nó có thể tự tăng.

GenerationType.IDENTITY

Cột có kiểu IDENTITY chỉ được hỗ trợ bởi một vài loại cơ sở dữ liệu, không phải là tất cả, ví dụ MySQL, DB2, SQL Server, Sybase và PostgreSQL. Oracle không hỗ trợ cột kiểu này.

GenerationType.SEQUENCE

SEQUENCE là một đối tượng trong cơ sở dữ liệu, lưu trữ một giá trị tăng dần sau mỗi lần gọi nó để lấy giá trị tiếp theo, và được hỗ trợ bởi Oracle, DB2, và Postgres.

GenerationType.TABLE

Khi sử dụng GenerationType.TABLE , chúng ta cần định nghĩa một table hibernate_sequences như sau:

CREATE TABLE `hibernate_sequences` (
`sequence_name` char(255) NOT NULL,
`next_val` decimal(19,0) DEFAULT NULL,
PRIMARY KEY (`sequence_name`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

Ta có bảng Category sử dụng GenerationType.TABLE như sau:

@Data
@Entity
@Table
public class Category {

@Id
@GeneratedValue(strategy = GenerationType.TABLE)
private Long id;

@Column
private String name;
}

Hibernate cho phép chúng ta tạo Id table dựa trên org.hibernate.id.enhified.TableGenerator xác định một bảng có thể chứa nhiều giá trị được đặt tên cho bất kỳ Entity nào.

Chẳng hạn, chúng ta có table table_identifier, bảng này sử dụng để quản lý các id tự tăng của các Entity. Cấu trúc table này như sau:

CREATE TABLE `table_identifier` (
`column_name` varchar(255) NOT NULL,
`value_column_name` decimal(19,0) DEFAULT NULL,
PRIMARY KEY (`column_name`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

Thêm 1 record cho bảng này: column_name = category , value_column_name = 10.

Chúng ta sẽ sử dụng GenerationType.TABLE với custom bảng table_identifier như sau:

package com.gpcoder.entities;

import javax.persistence.Column;
import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.GenerationType;
import javax.persistence.Id;
import javax.persistence.Table;
import javax.persistence.TableGenerator;

import lombok.Data;

@Data
@Entity
@Table
public class Category {

@Id
//@GeneratedValue(strategy = GenerationType.TABLE)
@GeneratedValue(
strategy = GenerationType.TABLE,
generator = "table-generator"
)
@TableGenerator(
name = "table-generator",
table = "table_identifier",
pkColumnName = "column_name",
valueColumnName = "value_column_name",
pkColumnValue = "category",
allocationSize = 5
)
private Long id;

@Column
private String name;
}

Mỗi lần 1 Category được thêm vào database, giá trị value_column_name trong table table_identifier ứng với column_name=category sẽ được cộng thêm 5 (allocationSize) và giá trị này sẽ là id của record được thêm vào table category.

UUID

UUID là một lớp của Java cho phép bạn tạo ra một chuỗi 36 ký tự ngẫu nhiên. Và với 36 ký tự xác suất trùng nhau là vô cùng bé. Chúng ta có thể sử dụng UUID với @GeneratedValue để Hibernate tạo ra một chuỗi ngẫu nhiên kiểu này gán cho giá trị của cột.

Ví dụ:

@Entity
@Table
public class UserVerification {

@Id
@GeneratedValue
private UUID id;

private String value;
}

@Lob

@Lob thường chú thích cùng với @Column để nói rằng cột đó có kiểu BLOB hoặc CLOB. Trong một số Database có phân biệt TINY, MEDIUM, LARGE BLOB/CLOB, còn một số database thì không.

Phần tử length trong @Column trong trường hợp này sẽ quyết định nó map vào BLOB/ CLOB nào. Trong trường hợp cho phép BLOB/CLOB tối đa hãy để length = Integer.MAX_VALUE.

Ví dụ:

@Entity
@Table
public class User {

@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;

@Lob
@Column(name = "avatar", nullable = true, length = Integer.MAX_VALUE)
private byte[] avatar;
}

@ManyToOne

@ManyToOne mô tả một quan hệ  N-1 (Nhiều – Một), nó thường được sử dụng cùng với @JoinColumn.

Hibernate có các công cụ cho phép tạo ra các lớp Entity từ các bảng trong Database và Hibernate cũng cho phép tạo ra bảng từ các lớp Entity, bao gồm cả giàng buộc giữa các bảng (Foreign Key). Annotation @ForeignKey cho phép chỉ định rõ tên Foreign Key sẽ được tạo ra.

FetchType.LAZY

LAZY nói với Hibernate rằng, hãy tải dữ liệu một cách lười biếng, nghĩa là chỉ tải khi được gọi (khi cần thiết).

Chẳng hạn bạn có một đối tượng Account, và gọi phương thức getOpenBranch() nó trả về một đối tượng Branch, đối tượng Branch chỉ trường (field) branchId được gán giá trị, các trường khác thì không.

Thực tế hibernate chưa tải dữ liệu từ bản ghi tương ứng của bảng BRANCH vào đối tượng này. Nó chỉ thực hiện truy vấn dữ liệu khi bạn làm gì đó với đối tượng Branch vừa có được, chẳng hạn gọi phương thức branch.getName().

FetchType.EAGER

EAGER nói với Hibernate rằng, hãy truy vấn toàn bộ các cột của bảng liên quan.

Chẳng hạn bạn có đối tượng Account, và gọi phương thức getOpenBranch() trả về đối tượng Branch đã có sẵn các giá trị cho các trường ( name, address, …). Thực tế dữ liệu của nó có được cùng trong 1 lần truy vấn với bảng Account.

Lưu ý: nên sử dụng LAZY thay vì EAGER vì lý do hiệu năng chương trình.

@Entity
@Table
public class Post {

@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;

// ...

@ManyToOne(fetch = FetchType.EAGER)
@JoinColumn(name = "category_id", nullable = false,
foreignKey = @ForeignKey(name = "fk_post_category"))
private Category category;
}

@OneToMany

@OneToMany mô tả quan hệ 1-N (Một – Nhiều). Nó là đảo ngược của @ManyToOne, và vì vậy nó dựa vào @ManyToOne để định nghĩa ra @OneToMany.

@Entity
@Table
public class Category {

@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;

@OneToMany(fetch = FetchType.LAZY, mappedBy = "category")
private Set posts;
}

@OneToOne

@OneToOne mô tả quan hệ 1-1 (Một – Một).

@Entity
@Table(name = "user_profile")
public class UserProfile {

@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;

// ...

@OneToOne(fetch = FetchType.LAZY)
@PrimaryKeyJoinColumn(name = "user_id", foreignKey = @ForeignKey(name = "fk_user_profile"))
private User user;
}

@Entity(name = "User")
@Table(name = "user")
public class User {

@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;

// ...

@OneToOne(fetch = FetchType.LAZY, mappedBy = "user", cascade = CascadeType.ALL)
private UserProfile userProfile;
}

@ManyToMany

@ManyToMany mô tả quan hệ N-N (Nhiều – Nhiều).

@Entity
@Table
public class Role {

@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;

@ManyToMany(fetch = FetchType.LAZY, mappedBy = "roles")
private Set users;
}

@Entity(name = "User")
@Table(name = "user")
public class User {

@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;

// ...

@ManyToMany(fetch = FetchType.LAZY, cascade = CascadeType.ALL)
@JoinTable(name = "user_roles",
joinColumns = { @JoinColumn(name = "user_id", nullable = false, updatable = false) },
inverseJoinColumns = { @JoinColumn(name = "role_id", nullable = false, updatable = false) })
private Set roles;
}

@OrderBy

@OrderBy được sử dụng để sắp xếp một danh sách, vì vậy nó có thể được sử dụng cùng với @OneToMany, @ManyToMany.

@Entity
@Table
public class Category {

// ...

@OneToMany(fetch = FetchType.LAZY, mappedBy = "category")
@OrderBy("title")
private Set posts;
}

Trên đây là các Annotation thường được sử dụng để tạo các Hibernate Entity cho các database table. Trong các bài viết kế tiếp, tôi sẽ hướng dẫn các bảng tạo Hibernate Entity một cách tự động từ table có sẵn, chúng ta không cần tạo Entity một cách thủ công.

Tài liệu tham khảo:

• https://docs.jboss.org/hibernate/orm/5.4/userguide/html_single/Hibernate_User_Guide.html