Spring Data JPA: Entities, Relationships, and Repositories

@Entity
@Table(name = "orders", indexes = {
    @Index(name = "idx_orders_customer_id", columnList = "customer_id"),
    @Index(name = "idx_orders_status", columnList = "status")
})
public class Order {
 
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
 
    @Column(name = "customer_id", nullable = false)
    private Long customerId;
 
    @Enumerated(EnumType.STRING)
    @Column(nullable = false, length = 20)
    private OrderStatus status;
 
    @Column(name = "total_amount", precision = 19, scale = 4, nullable = false)
    private BigDecimal totalAmount;
 
    @Column(name = "created_at", nullable = false, updatable = false)
    private Instant createdAt;
 
    @Version
    private Long version;
 
    protected Order() {
        // required by JPA — never call directly
    }
 
    public Order(Long customerId, BigDecimal totalAmount) {
        this.customerId = customerId;
        this.totalAmount = totalAmount;
        this.status = OrderStatus.PENDING;
        this.createdAt = Instant.now();
    }
 
    // getters, no public setters for immutable fields
}

@Id
@GeneratedValue(strategy = GenerationType.SEQUENCE, generator = "order_seq")
@SequenceGenerator(name = "order_seq", sequenceName = "order_id_seq", allocationSize = 50)
private Long id;

CREATE SEQUENCE order_id_seq START WITH 1 INCREMENT BY 50;

@Entity
public class Order {
    @Id
    @GeneratedValue(strategy = GenerationType.SEQUENCE, generator = "order_seq")
    private Long id;
 
    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "customer_id", nullable = false)
    private Customer customer;
}

@Entity
public class Customer {
    @Id
    @GeneratedValue(strategy = GenerationType.SEQUENCE, generator = "customer_seq")
    private Long id;
 
    @OneToMany(mappedBy = "customer", cascade = CascadeType.ALL, orphanRemoval = true)
    private List<Order> orders = new ArrayList<>();
 
    public void addOrder(Order order) {
        orders.add(order);
        order.setCustomer(this);   // keep both sides in sync
    }
 
    public void removeOrder(Order order) {
        orders.remove(order);
        order.setCustomer(null);
    }
}

@Entity
public class Product {
    @Id @GeneratedValue(strategy = GenerationType.SEQUENCE, generator = "product_seq")
    private Long id;
 
    @ManyToMany
    @JoinTable(
        name = "product_category",
        joinColumns = @JoinColumn(name = "product_id"),
        inverseJoinColumns = @JoinColumn(name = "category_id")
    )
    private Set<Category> categories = new HashSet<>();
}

@Entity
@Table(name = "product_category")
public class ProductCategory {
    @EmbeddedId
    private ProductCategoryId id;
 
    @ManyToOne @MapsId("productId")
    @JoinColumn(name = "product_id")
    private Product product;
 
    @ManyToOne @MapsId("categoryId")
    @JoinColumn(name = "category_id")
    private Category category;
 
    @Column(name = "added_at")
    private Instant addedAt;
}
 
@Embeddable
public class ProductCategoryId implements Serializable {
    private Long productId;
    private Long categoryId;
    // equals/hashCode required for composite keys
}

@Embeddable
public class Address {
    @Column(name = "street") private String street;
    @Column(name = "city") private String city;
    @Column(name = "postal_code") private String postalCode;
    @Column(name = "country") private String country;
    // equals/hashCode by value, no @Id
}
 
@Entity
public class Customer {
    @Id
    @GeneratedValue(strategy = GenerationType.SEQUENCE, generator = "customer_seq")
    private Long id;
 
    @Embedded
    private Address billingAddress;
 
    @Embedded
    @AttributeOverrides({
        @AttributeOverride(name = "street", column = @Column(name = "shipping_street")),
        @AttributeOverride(name = "city", column = @Column(name = "shipping_city"))
    })
    private Address shippingAddress;
}

public interface OrderRepository extends JpaRepository<Order, Long> {
}

public interface OrderRepository extends JpaRepository<Order, Long> {
 
    List<Order> findByCustomerId(Long customerId);
 
    List<Order> findByStatusAndCreatedAtAfter(OrderStatus status, Instant since);
 
    Optional<Order> findFirstByCustomerIdOrderByCreatedAtDesc(Long customerId);
 
    boolean existsByCustomerIdAndStatus(Long customerId, OrderStatus status);
 
    long countByStatus(OrderStatus status);
 
    List<Order> findByTotalAmountGreaterThanEqual(BigDecimal amount);
 
    List<Order> findByCustomerIdIn(Collection<Long> customerIds);
 
    @EntityGraph(attributePaths = {"lineItems", "customer"})
    List<Order> findByStatus(OrderStatus status);
}

public interface OrderRepository extends JpaRepository<Order, Long> {
 
    @Query("""
        SELECT o FROM Order o
        WHERE o.customer.id = :customerId
          AND o.status = :status
        ORDER BY o.createdAt DESC
        """)
    List<Order> findRecentOrders(@Param("customerId") Long customerId,
                                  @Param("status") OrderStatus status);
 
    @Query(value = """
        SELECT * FROM orders
        WHERE created_at >= :since
        ORDER BY created_at DESC
        LIMIT :limit
        """, nativeQuery = true)
    List<Order> findRecentOrdersNative(@Param("since") Instant since,
                                        @Param("limit") int limit);
 
    @Modifying
    @Query("UPDATE Order o SET o.status = :status WHERE o.id = :id")
    int updateStatus(@Param("id") Long id, @Param("status") OrderStatus status);
 
    @Query("""
        SELECT new com.example.orders.dto.OrderSummary(o.id, o.status, o.totalAmount)
        FROM Order o WHERE o.customer.id = :customerId
        """)
    List<OrderSummary> findSummariesByCustomer(@Param("customerId") Long customerId);
}

public interface OrderSummaryView {
    Long getId();
    OrderStatus getStatus();
    BigDecimal getTotalAmount();
}
 
public interface OrderRepository extends JpaRepository<Order, Long> {
    List<OrderSummaryView> findByCustomerId(Long customerId);
}

@Configuration
@EnableJpaAuditing
public class JpaAuditingConfig {
}
 
@MappedSuperclass
@EntityListeners(AuditingEntityListener.class)
public abstract class Auditable {
 
    @CreatedDate
    @Column(name = "created_at", nullable = false, updatable = false)
    private Instant createdAt;
 
    @LastModifiedDate
    @Column(name = "updated_at", nullable = false)
    private Instant updatedAt;
 
    @CreatedBy
    @Column(name = "created_by", updatable = false)
    private String createdBy;
 
    @LastModifiedBy
    @Column(name = "updated_by")
    private String updatedBy;
}
 
@Entity
public class Order extends Auditable {
    // inherits createdAt, updatedAt, createdBy, updatedBy
}

@Bean
public AuditorAware<String> auditorAware() {
    return () -> Optional.ofNullable(SecurityContextHolder.getContext().getAuthentication())
        .map(Authentication::getName);
}

public interface OrderRepositoryCustom {
    List<Order> findWithDynamicFilters(OrderFilterCriteria criteria);
}
 
public class OrderRepositoryImpl implements OrderRepositoryCustom {
    private final EntityManager entityManager;
 
    public OrderRepositoryImpl(EntityManager entityManager) {
        this.entityManager = entityManager;
    }
 
    @Override
    public List<Order> findWithDynamicFilters(OrderFilterCriteria criteria) {
        // CriteriaBuilder logic here — see the Pagination & Specifications guide
        return List.of();
    }
}