1# Data Access - Spring Data JPA
2 
3## JPA Entity Pattern
4 
5```java
6@Entity
7@Table(name = "users", indexes = {
8    @Index(name = "idx_email", columnList = "email", unique = true),
9    @Index(name = "idx_username", columnList = "username")
10})
11@EntityListeners(AuditingEntityListener.class)
12@Getter @Setter
13@NoArgsConstructor
14@AllArgsConstructor
15@Builder
16public class User {
17 
18    @Id
19    @GeneratedValue(strategy = GenerationType.IDENTITY)
20    private Long id;
21 
22    @Column(nullable = false, unique = true, length = 100)
23    private String email;
24 
25    @Column(nullable = false, length = 100)
26    private String password;
27 
28    @Column(nullable = false, unique = true, length = 50)
29    private String username;
30 
31    @Column(nullable = false)
32    @Builder.Default
33    private Boolean active = true;
34 
35    @OneToMany(mappedBy = "user", cascade = CascadeType.ALL, orphanRemoval = true)
36    @Builder.Default
37    private List<Address> addresses = new ArrayList<>();
38 
39    @ManyToMany
40    @JoinTable(
41        name = "user_roles",
42        joinColumns = @JoinColumn(name = "user_id"),
43        inverseJoinColumns = @JoinColumn(name = "role_id")
44    )
45    @Builder.Default
46    private Set<Role> roles = new HashSet<>();
47 
48    @CreatedDate
49    @Column(nullable = false, updatable = false)
50    private LocalDateTime createdAt;
51 
52    @LastModifiedDate
53    @Column(nullable = false)
54    private LocalDateTime updatedAt;
55 
56    @Version
57    private Long version;
58 
59    // Helper methods for bidirectional relationships
60    public void addAddress(Address address) {
61        addresses.add(address);
62        address.setUser(this);
63    }
64 
65    public void removeAddress(Address address) {
66        addresses.remove(address);
67        address.setUser(null);
68    }
69}
70```
71 
72## Spring Data JPA Repository
73 
74```java
75@Repository
76public interface UserRepository extends JpaRepository<User, Long>,
77                                       JpaSpecificationExecutor<User> {
78 
79    Optional<User> findByEmail(String email);
80 
81    Optional<User> findByUsername(String username);
82 
83    boolean existsByEmail(String email);
84 
85    boolean existsByUsername(String username);
86 
87    @Query("SELECT u FROM User u LEFT JOIN FETCH u.roles WHERE u.email = :email")
88    Optional<User> findByEmailWithRoles(@Param("email") String email);
89 
90    @Query("SELECT u FROM User u WHERE u.active = true AND u.createdAt >= :since")
91    List<User> findActiveUsersSince(@Param("since") LocalDateTime since);
92 
93    @Modifying
94    @Query("UPDATE User u SET u.active = false WHERE u.lastLoginAt < :threshold")
95    int deactivateInactiveUsers(@Param("threshold") LocalDateTime threshold);
96 
97    // Projection for read-only DTOs
98    @Query("SELECT new com.example.dto.UserSummary(u.id, u.username, u.email) " +
99           "FROM User u WHERE u.active = true")
100    List<UserSummary> findAllActiveSummaries();
101}
102```
103 
104## Repository with Specifications
105 
106```java
107public class UserSpecifications {
108 
109    public static Specification<User> hasEmail(String email) {
110        return (root, query, cb) ->
111            email == null ? null : cb.equal(root.get("email"), email);
112    }
113 
114    public static Specification<User> isActive() {
115        return (root, query, cb) -> cb.isTrue(root.get("active"));
116    }
117 
118    public static Specification<User> createdAfter(LocalDateTime date) {
119        return (root, query, cb) ->
120            date == null ? null : cb.greaterThanOrEqualTo(root.get("createdAt"), date);
121    }
122 
123    public static Specification<User> hasRole(String roleName) {
124        return (root, query, cb) -> {
125            Join<User, Role> roles = root.join("roles", JoinType.INNER);
126            return cb.equal(roles.get("name"), roleName);
127        };
128    }
129}
130 
131// Usage in service
132@Service
133@RequiredArgsConstructor
134public class UserService {
135    private final UserRepository userRepository;
136 
137    public Page<User> searchUsers(UserSearchCriteria criteria, Pageable pageable) {
138        Specification<User> spec = Specification
139            .where(UserSpecifications.hasEmail(criteria.email()))
140            .and(UserSpecifications.isActive())
141            .and(UserSpecifications.createdAfter(criteria.createdAfter()));
142 
143        return userRepository.findAll(spec, pageable);
144    }
145}
146```
147 
148## Transaction Management
149 
150```java
151@Service
152@RequiredArgsConstructor
153@Transactional(readOnly = true)
154public class OrderService {
155    private final OrderRepository orderRepository;
156    private final PaymentService paymentService;
157    private final InventoryService inventoryService;
158    private final NotificationService notificationService;
159 
160    @Transactional
161    public Order createOrder(OrderCreateRequest request) {
162        // All operations in single transaction
163        Order order = Order.builder()
164            .customerId(request.customerId())
165            .status(OrderStatus.PENDING)
166            .build();
167 
168        request.items().forEach(item -> {
169            inventoryService.reserveStock(item.productId(), item.quantity());
170            order.addItem(item);
171        });
172 
173        order = orderRepository.save(order);
174 
175        try {
176            paymentService.processPayment(order);
177            order.setStatus(OrderStatus.PAID);
178        } catch (PaymentException e) {
179            order.setStatus(OrderStatus.PAYMENT_FAILED);
180            throw e; // Transaction will rollback
181        }
182 
183        return orderRepository.save(order);
184    }
185 
186    @Transactional(propagation = Propagation.REQUIRES_NEW)
187    public void logOrderEvent(Long orderId, String event) {
188        // Separate transaction - will commit even if parent rolls back
189        OrderEvent orderEvent = new OrderEvent(orderId, event);
190        orderEventRepository.save(orderEvent);
191    }
192 
193    @Transactional(noRollbackFor = NotificationException.class)
194    public void completeOrder(Long orderId) {
195        Order order = orderRepository.findById(orderId)
196            .orElseThrow(() -> new ResourceNotFoundException("Order not found"));
197 
198        order.setStatus(OrderStatus.COMPLETED);
199        orderRepository.save(order);
200 
201        // Won't rollback transaction if notification fails
202        try {
203            notificationService.sendCompletionEmail(order);
204        } catch (NotificationException e) {
205            log.error("Failed to send notification for order {}", orderId, e);
206        }
207    }
208}
209```
210 
211## Auditing Configuration
212 
213```java
214@Configuration
215@EnableJpaAuditing
216public class JpaAuditingConfig {
217 
218    @Bean
219    public AuditorAware<String> auditorProvider() {
220        return () -> {
221            Authentication authentication = SecurityContextHolder
222                .getContext()
223                .getAuthentication();
224 
225            if (authentication == null || !authentication.isAuthenticated()) {
226                return Optional.of("system");
227            }
228 
229            return Optional.of(authentication.getName());
230        };
231    }
232}
233 
234@MappedSuperclass
235@EntityListeners(AuditingEntityListener.class)
236@Getter @Setter
237public abstract class AuditableEntity {
238 
239    @CreatedDate
240    @Column(nullable = false, updatable = false)
241    private LocalDateTime createdAt;
242 
243    @CreatedBy
244    @Column(nullable = false, updatable = false, length = 100)
245    private String createdBy;
246 
247    @LastModifiedDate
248    @Column(nullable = false)
249    private LocalDateTime updatedAt;
250 
251    @LastModifiedBy
252    @Column(nullable = false, length = 100)
253    private String updatedBy;
254}
255```
256 
257## Projections
258 
259```java
260// Interface-based projection
261public interface UserSummary {
262    Long getId();
263    String getUsername();
264    String getEmail();
265 
266    @Value("#{target.firstName + ' ' + target.lastName}")
267    String getFullName();
268}
269 
270// Class-based projection (DTO)
271public record UserSummaryDto(
272    Long id,
273    String username,
274    String email
275) {}
276 
277// Usage
278public interface UserRepository extends JpaRepository<User, Long> {
279    List<UserSummary> findAllBy();
280 
281    <T> List<T> findAllBy(Class<T> type);
282}
283 
284// Service usage
285List<UserSummary> summaries = userRepository.findAllBy();
286List<UserSummaryDto> dtos = userRepository.findAllBy(UserSummaryDto.class);
287```
288 
289## Query Optimization
290 
291```java
292@Service
293@RequiredArgsConstructor
294@Transactional(readOnly = true)
295public class UserQueryService {
296    private final UserRepository userRepository;
297    private final EntityManager entityManager;
298 
299    // N+1 problem solved with JOIN FETCH
300    @Query("SELECT DISTINCT u FROM User u " +
301           "LEFT JOIN FETCH u.addresses " +
302           "LEFT JOIN FETCH u.roles " +
303           "WHERE u.active = true")
304    List<User> findAllActiveWithAssociations();
305 
306    // Batch fetching
307    @BatchSize(size = 25)
308    @OneToMany(mappedBy = "user")
309    private List<Order> orders;
310 
311    // EntityGraph for dynamic fetching
312    @EntityGraph(attributePaths = {"addresses", "roles"})
313    List<User> findAllByActiveTrue();
314 
315    // Pagination to avoid loading all data
316    public Page<User> findAllUsers(Pageable pageable) {
317        return userRepository.findAll(pageable);
318    }
319 
320    // Native query for complex queries
321    @Query(value = """
322        SELECT u.* FROM users u
323        INNER JOIN orders o ON u.id = o.user_id
324        WHERE o.created_at >= :since
325        GROUP BY u.id
326        HAVING COUNT(o.id) >= :minOrders
327        """, nativeQuery = true)
328    List<User> findFrequentBuyers(@Param("since") LocalDateTime since,
329                                  @Param("minOrders") int minOrders);
330}
331```
332 
333## Database Migrations (Flyway)
334 
335```sql
336-- V1__create_users_table.sql
337CREATE TABLE users (
338    id BIGSERIAL PRIMARY KEY,
339    email VARCHAR(100) NOT NULL UNIQUE,
340    password VARCHAR(100) NOT NULL,
341    username VARCHAR(50) NOT NULL UNIQUE,
342    active BOOLEAN NOT NULL DEFAULT true,
343    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
344    updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
345    version BIGINT NOT NULL DEFAULT 0
346);
347 
348CREATE INDEX idx_users_email ON users(email);
349CREATE INDEX idx_users_username ON users(username);
350CREATE INDEX idx_users_active ON users(active);
351 
352-- V2__create_addresses_table.sql
353CREATE TABLE addresses (
354    id BIGSERIAL PRIMARY KEY,
355    user_id BIGINT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
356    street VARCHAR(200) NOT NULL,
357    city VARCHAR(100) NOT NULL,
358    country VARCHAR(2) NOT NULL,
359    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
360);
361 
362CREATE INDEX idx_addresses_user_id ON addresses(user_id);
363```
364 
365## Quick Reference
366 
367| Annotation | Purpose |
368|------------|---------|
369| `@Entity` | Marks class as JPA entity |
370| `@Table` | Specifies table details and indexes |
371| `@Id` | Marks primary key field |
372| `@GeneratedValue` | Auto-generated primary key strategy |
373| `@Column` | Column constraints and mapping |
374| `@OneToMany/@ManyToOne` | One-to-many/many-to-one relationships |
375| `@ManyToMany` | Many-to-many relationships |
376| `@JoinColumn/@JoinTable` | Join column/table configuration |
377| `@Transactional` | Declares transaction boundaries |
378| `@Query` | Custom JPQL/native queries |
379| `@Modifying` | Marks query as UPDATE/DELETE |
380| `@EntityGraph` | Defines fetch graph for associations |
381| `@Version` | Optimistic locking version field |
382