1. Entity and Table Mappings

1. @Entity

About

• @Entity is a JPA (Java Persistence API) annotation.

• It marks a plain Java class as an entity bean, which means this class will be mapped to a relational database table.

• When the persistence provider (like Hibernate) sees a class annotated with @Entity, it treats the class as a persistent entity, capable of being managed, saved, deleted, and queried from the database.

Important Points

• Mandatory for persistence: Only classes annotated with @Entity are recognized as entities by the JPA provider.

• No-argument constructor required: The class must have a public or protected no-argument constructor (this is needed by JPA at runtime via reflection).

• Serializable: Although not mandatory by specification, it is recommended that entity classes implement Serializable for best practices, especially in distributed systems.

• Uniquely identifiable: Every entity must have a primary key field, which is annotated with @Id.

• Class cannot be final: The JPA provider may need to subclass or proxy the entity.

• Fields/Properties: The class can either have fields or getter/setter methods that are persisted, depending on whether you use field access or property access (determined by where the @Id is placed).

Syntax and Usage

import jakarta.persistence.Entity;

@Entity
public class Employee {
    @Id
    private Long id;

    private String name;
    private String department;
}

Here:

• Employee is now a managed entity.

• JPA will create a table for it or map it to an existing table.

Rules for Using @Entity

Rule	Description
Entity name	If no name is specified, the class name is used as the entity name.
Table name	If no @Table annotation is present, the table name defaults to the entity name (case-sensitive, depending on database).
Must not be final	JPA providers use proxies; final classes cannot be proxied easily.
Must have a primary key	Without an @Id, the entity cannot be managed.
No-arg constructor	Required by the persistence provider.

Optional Attributes of @Entity

@Entity(name = "EmployeeEntity")

• name: Defines the name of the entity (used in JPQL queries). Defaults to the class name if not provided.

• Note: The name has nothing to do with the table name in the database (that's handled by @Table).

2. @Table

About

• @Table is a JPA annotation used to customize the database table that an entity is mapped to.

• By default, if @Table is not specified, JPA uses the class name as the table name.

• @Table allows developers to control the table name, schema, catalog, and indexes.

Important Points

• Customization of mapping: @Table tells JPA what actual database table should back the entity.

• Optional: It is not mandatory. Without @Table, the entity will map to a table named exactly like the entity class.

• Defines schema/catalog: It can specify the database schema or catalog in multi-schema setups.

• Define unique constraints: You can define database-level unique constraints across one or more columns.

Syntax and Usage

import jakarta.persistence.Entity;
import jakarta.persistence.Table;

@Entity
@Table(name = "employees", schema = "company", catalog = "corporate")
public class Employee {
    @Id
    private Long id;
    private String name;
}

Here:

• employees is the actual table name in the company schema of the corporate catalog.

• The Employee entity will persist records into corporate.company.employees.

Attributes of @Table

Attribute	Description	Example
name	The name of the database table.	@Table(name = "employees")
schema	Name of the database schema.	@Table(schema = "company")
catalog	Name of the database catalog.	@Table(catalog = "corporate")
uniqueConstraints	Defines unique constraints on one or more columns.	@Table(uniqueConstraints = @UniqueConstraint(columnNames = {"email"}))
indexes	Defines indexes on one or more columns (since JPA 2.1).	@Table(indexes = @Index(name = "idx_name", columnList = "name"))

Practical Details About Attributes

name

• Specifies the table's name in the database.

• If omitted, the entity class name is used.

• If different from the entity name, always specify name.

@Table(name = "emp_details")

schema

• Useful when your database is logically divided into schemas (especially common in Oracle, PostgreSQL).

• If your table resides in a different schema, you must specify it.

@Table(schema = "hr")

catalog

• Refers to the database catalog.

• Rarely used compared to schema.

• In some RDBMS like MySQL, catalog and database are the same.

@Table(catalog = "employees_db")

uniqueConstraints

• You can define one or more columns that must have unique values.

• It generates a UNIQUE constraint at the database level.

@Table(uniqueConstraints = @UniqueConstraint(columnNames = {"email"}))

Means the email column must be unique for all rows.

indexes

• Introduced in JPA 2.1.

• Specifies index creation on columns.

• Helps in performance optimization at the database level.

@Table(indexes = @Index(name = "idx_employee_name", columnList = "name"))

Creates an index named idx_employee_name on the name column.