The first entity

An entity is a Java class whose objects Hibernate stores in the database. One entity class corresponds to one table, one object to one row, one field to one column. To make a class an entity, you add a couple of annotations.

The Post class

Create the file src/main/java/com/example/blog/Post.java:

// src/main/java/com/example/blog/Post.java
package com.example.blog;
 
import jakarta.persistence.Entity;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.Id;
 
@Entity
public class Post {
 
    @Id
    @GeneratedValue
    private Long id;
 
    private String title;
    private String body;
 
    protected Post() {
    }
 
    public Post(String title, String body) {
        this.title = title;
        this.body = body;
    }
 
    public Long getId() {
        return id;
    }
 
    public String getTitle() {
        return title;
    }
 
    public String getBody() {
        return body;
    }
}

Annotation	Meaning
`@Entity`	The class is stored in the database
`@Id`	This field is the primary key
`@GeneratedValue`	Hibernate assigns the key value itself

All other fields become columns automatically. The table is named after the class, and the columns after the fields.

Requirements for an entity

a constructor without parameters — Hibernate uses it to create objects when it reads rows. It may be protected, so that your own code uses the normal constructor;
the class and its persistent methods must not be final — Hibernate creates subclasses for lazy loading;
an @Id field. The type Long (not long) is convenient: null means "not saved yet".

A record cannot be an entity: its fields are final, and Hibernate needs to change them.

Registering the class

List the entity in the persistence unit in persistence.xml, before the <properties> element:

<!-- src/main/resources/META-INF/persistence.xml -->
<persistence-unit name="blog">
  <class>com.example.blog.Post</class>
  <properties>
    <!-- the properties from the previous lesson -->
  </properties>
</persistence-unit>

Saving posts

// src/main/java/com/example/blog/Main.java
package com.example.blog;
 
import jakarta.persistence.EntityManagerFactory;
import jakarta.persistence.Persistence;
 
public class Main {
    public static void main(String[] args) {
        try (EntityManagerFactory emf = Persistence.createEntityManagerFactory("blog")) {
            emf.runInTransaction(em -> {
                Post first = new Post("Hello, Hibernate", "My first post");
                Post second = new Post("Entities", "A class becomes a table");
                em.persist(first);
                em.persist(second);
                IO.println("Saved with id " + first.getId() + " and " + second.getId());
            });
        }
    }
}

runInTransaction opens a transaction, passes an EntityManager into the lambda and commits at the end. persist hands an object to Hibernate for saving. After mvn compile exec:java the console shows:

Hibernate: create sequence Post_SEQ start with 1 increment by 50
Hibernate: create table Post (id bigint not null, body varchar(255), title varchar(255), primary key (id))
Hibernate: select next value for Post_SEQ
Hibernate: select next value for Post_SEQ
Saved with id 1 and 2
Hibernate: insert into Post (body,title,id) values (?,?,?)
Hibernate: insert into Post (body,title,id) values (?,?,?)

Hibernate created the Post table and the Post_SEQ sequence for the keys. Note the order: the ids are known right after persist, but the insert statements run only when the transaction is committed. Why this is so — in the next lesson.

Common mistake

If you forget the <class> line, Hibernate knows nothing about the entity and fails on the first persist:

Exception in thread "main" java.lang.IllegalArgumentException: Unknown entity type 'com.example.blog.Post' ('Post' does not belong to this persistence unit)

In plain Java SE every new entity has to be added to persistence.xml. Spring Boot and Quarkus find entities by scanning packages, so there this line is not needed.

Thanks for reading!