Entity

An entity is a Java class that maps to a database table. JPA (Java Persistence API) handles the mapping automatically.

Basic Entity

@Entity
@Table(name = "products")
public class Product {

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

    @Column(nullable = false, length = 255)
    private String name;

    @Column(length = 2000)
    private String description;

    @Column(nullable = false, precision = 10, scale = 2)
    private BigDecimal price;

    @Column(nullable = false)
    private Integer stockQuantity;

    @Column(nullable = false)
    private Boolean active = true;

    @CreationTimestamp
    private LocalDateTime createdAt;

    @UpdateTimestamp
    private LocalDateTime updatedAt;

    // Constructors
    public Product() {}

    public Product(String name, String description, BigDecimal price, Integer stockQuantity) {
        this.name = name;
        this.description = description;
        this.price = price;
        this.stockQuantity = stockQuantity;
        this.active = true;
    }

    // Getters and Setters
    public Long getId() { return id; }
    public String getName() { return name; }
    public void setName(String name) { this.name = name; }
    public BigDecimal getPrice() { return price; }
    public void setPrice(BigDecimal price) { this.price = price; }
    // ... other getters/setters
}

Key JPA Annotations

Entity Relationships

One-to-Many (Category → Products):

@Entity
@Table(name = "categories")
public class Category {

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

    @Column(nullable = false)
    private String name;

    @OneToMany(mappedBy = "category", cascade = CascadeType.ALL, fetch = FetchType.LAZY)
    private List<Product> products = new ArrayList<>();
}

Many-to-One (Product → Category):

@Entity
@Table(name = "products")
public class Product {

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

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

Many-to-Many (Product ↔ Tag):

@Entity
@Table(name = "products")
public class Product {

    @ManyToMany(fetch = FetchType.LAZY)
    @JoinTable(
        name = "product_tags",
        joinColumns = @JoinColumn(name = "product_id"),
        inverseJoinColumns = @JoinColumn(name = "tag_id")
    )
    private Set<Tag> tags = new HashSet<>();
}

Fetch Types

Best Practice: Always use FetchType.LAZY and fetch eagerly only when needed with @EntityGraph or JPQL joins.

Never Use Entities as API Responses

// BAD: Exposes internal data, causes lazy loading issues, circular references
@GetMapping("/{id}")
public Product getProduct(@PathVariable Long id) {
    return productRepository.findById(id).orElseThrow();
    // Returns JSON with password hashes, internal fields, lazy-loaded collections
}

// GOOD: Convert to DTO
@GetMapping("/{id}")
public ProductDto getProduct(@PathVariable Long id) {
    return productService.getProduct(id);
    // Returns only the data the client needs
}

Avoid LazyInitializationException

// BAD: Lazy collection accessed outside transaction
@Entity
public class Order {
    @OneToMany(fetch = FetchType.LAZY)
    private List<OrderItem> items;
}

// In service — throws LazyInitializationException:
Order order = orderRepository.findById(id).orElseThrow();
order.getItems().size(); // Error! Transaction is closed

// SOLUTION 1: Fetch join in query
@Query("SELECT o FROM Order o JOIN FETCH o.items WHERE o.id = :id")
Order findByIdWithItems(@Param("id") Long id);

// SOLUTION 2: Use @EntityGraph
@EntityGraph(attributePaths = {"items"})
@Query("SELECT o FROM Order o WHERE o.id = :id")
Order findByIdWithItems(@Param("id") Long id);

// SOLUTION 3: Use FetchType.EAGER (not recommended — causes N+1)

Entity Design Rules

1. Private fields + getters/setters — encapsulation
2. No-arg constructor required — JPA needs to instantiate entities
3. Use @GeneratedValue — let the database generate IDs
4. Use BigDecimal for money — never double/float
5. Add @Column constraints — nullable, length, precision
6. Use @CreationTimestamp/@UpdateTimestamp — for audit trail