JPA entities

An entity is a Java class mapped to a database table: each instance is a row, each field a column.

🔎 Unravel this example

At a glance

Mental model

An entity is a form that mirrors one row of a spreadsheet.

What happens, in order

1@Entity marks the class, @Id its primary key, @GeneratedValue says the database or a sequence supplies the key, and @Column tunes a column (name, length, nullable)
2Inside a transaction, entities you load become managed: the persistence context remembers their original stateChanging a field is enough; at commit Hibernate generates the UPDATE (dirty checking). No explicit save is needed for managed entities.
3@Enumerated(EnumType.STRING) stores the enum name instead of its ordinal number, which survives reordering the enum

Remember

Entities need a no-argument constructor (can be protected) and should not be final, because Hibernate creates subclasses (proxies) for lazy loading
Implement equals and hashCode carefully: using a generated database id means a new entity has a null id until saved, which breaks hash-based sets
The EntityManager (Hibernate Session) holds a first-level cache: loading the same id twice in one transaction returns the same object and one query

Watch out

Using ordinal enum storageEntities as API response objectsBroken equals/hashCode on generated idsExpecting changes to be saved outside a transaction

Example (highlighted lines explain it)

@Entity@Table(name = "customers")public class Customer {    @Id    @GeneratedValue(strategy = GenerationType.IDENTITY)    private Long id;    @Column(nullable = false, length = 120)    private String email;    @Enumerated(EnumType.STRING)    private Status status;}

line 1 uses Entity, the core of JPA entities
line 2 uses Table, the core of JPA entities
line 4 uses Id, the core of JPA entities
line 5 uses GeneratedValue, the core of JPA entities
line 8 uses Column, the core of JPA entities
line 11 uses Enumerated, the core of JPA entities

Read the full explanation (about 1 min)

An entity is a Java class mapped to a database table: each instance is a row, each field a column. The JPA provider (usually Hibernate) tracks changes to loaded entities and writes them back.

A mental model

An entity is a form that mirrors one row of a spreadsheet. Hibernate keeps the originals in a drawer; when you change a field and commit, it compares the form with the original and writes only what changed.

How it works

@Entity marks the class, @Id its primary key, @GeneratedValue says the database or a sequence supplies the key, and @Column tunes a column (name, length, nullable).

Inside a transaction, entities you load become managed: the persistence context remembers their original state. Changing a field is enough; at commit Hibernate generates the UPDATE (dirty checking). No explicit save is needed for managed entities.

@Enumerated(EnumType.STRING) stores the enum name instead of its ordinal number, which survives reordering the enum.

Going deeper

Entities need a no-argument constructor (can be protected) and should not be final, because Hibernate creates subclasses (proxies) for lazy loading.

Implement equals and hashCode carefully: using a generated database id means a new entity has a null id until saved, which breaks hash-based sets. A business key or a stable surrogate is safer.

Do not expose entities straight to the API. Map them to DTOs to avoid lazy-loading errors and accidental field leaks.

Under the hood

The EntityManager (Hibernate Session) holds a first-level cache: loading the same id twice in one transaction returns the same object and one query. On flush Hibernate orders and batches the pending INSERT, UPDATE and DELETE statements.

Common mistakes

Using ordinal enum storage.
Entities as API response objects.
Broken equals/hashCode on generated ids.
Expecting changes to be saved outside a transaction.

How Unravel recognises it

When you paste code, Unravel looks for these signs of jpa entities. Spotting them yourself is a good habit when you read unfamiliar code:

Annotations: @Entity @Table @Id @GeneratedValue @Column @Embeddable @Embedded @PersistenceContext @MappedSuperclass @Enumerated
Types: EntityManager

Part of a learning path

How a Spring request really works · previous: @Transactional · next: Lazy loading and the N+1 query problem
JPA and Hibernate in depth · next: JPA relationships, cascade and orphan removal

Related concepts

Lazy loading and the N+1 query problemPersistence @TransactionalSpring JDBC and prepared statementsPersistence

Builds on this

Spring Data repositoriesPersistence JPA relationships, cascade and orphan removalPersistence Optimistic and pessimistic lockingPersistence JPA inheritance mappingPersistence Persistence context, flush and dirty checkingPersistence JPQL, native queries and the Criteria APIPersistence

Frequently asked questions

What is JPA entities?

An entity is a Java class mapped to a database table: each instance is a row, each field a column. The JPA provider (usually Hibernate) tracks changes to loaded entities and writes them back.

What are the most common mistakes with JPA entities?

Using ordinal enum storage. Entities as API response objects. Broken equals/hashCode on generated ids. Expecting changes to be saved outside a transaction.

How can I see JPA entities in real code?

Paste your own Java into Unravel and it will point out where jpa entities appears, explain how it works at the detail level you choose, and draw the flow of the code around it.