Spring Boot
Complete Reference

<parent>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-parent</artifactId>
  <version>3.2.0</version>
</parent>

<dependencies>
  <!-- Web MVC + embedded Tomcat -->
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
  </dependency>

  <!-- JPA + Hibernate -->
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
  </dependency>

  <!-- Spring Security -->
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
  </dependency>

  <!-- Bean validation -->
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
  </dependency>

  <!-- Actuator -->
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
  </dependency>
</dependencies>

// Override auto-configured beans with your own @Bean definitions
@Configuration
public class AppConfig {

    // Override default ObjectMapper (Jackson JSON serializer)
    @Bean
    public ObjectMapper objectMapper() {
        return new ObjectMapper()
            .configure(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS, false)
            .registerModule(new JavaTimeModule());
    }

    // Declare a shared RestTemplate bean
    @Bean
    public RestTemplate restTemplate(RestTemplateBuilder builder) {
        return builder
            .setConnectTimeout(Duration.ofSeconds(5))
            .setReadTimeout(Duration.ofSeconds(10))
            .build();
    }

    // ConditionalOnMissingBean — only creates this if you haven't defined your own
    @Bean
    @ConditionalOnMissingBean
    public PasswordEncoder passwordEncoder() {
        return new BCryptPasswordEncoder(12);
    }
}

// ResponseEntity gives you fine-grained control over status, headers, body

@RestController
@RequestMapping("/api/products")
public class ProductController {

    @GetMapping("/{id}")
    public ResponseEntity<ProductDto> getProduct(@PathVariable Long id) {
        return userService.findOptional(id)
            .map(ResponseEntity::ok)                           // 200 OK
            .orElse(ResponseEntity.notFound().build());        // 404
    }

    @PostMapping
    public ResponseEntity<ProductDto> createProduct(@RequestBody CreateProductRequest req) {
        ProductDto created = productService.create(req);
        URI location = ServletUriComponentsBuilder.fromCurrentRequest()
            .path("/{id}")
            .buildAndExpand(created.id())
            .toUri();
        return ResponseEntity
            .created(location)            // 201 + Location header
            .body(created);
    }

    @GetMapping("/export")
    public ResponseEntity<byte[]> exportCsv() {
        byte[] csv = reportService.generateCsv();
        return ResponseEntity.ok()
            .header("Content-Disposition", "attachment; filename=products.csv")
            .contentType(MediaType.TEXT_PLAIN)
            .body(csv);
    }
}

// DTOs (Data Transfer Objects) decouple API contracts from domain entities

// Immutable request DTO using Java 17 record
public record CreateUserRequest(
    @NotBlank  @Size(min=2, max=50)  String name,
    @NotBlank  @Email                String email,
    @NotBlank  @Size(min=8)          String password
) {}

// Response DTO — never expose the raw @Entity
public record UserDto(
    Long   id,
    String name,
    String email,
    LocalDateTime createdAt
) {
    // Static factory method from entity
    public static UserDto from(User user) {
        return new UserDto(user.getId(), user.getName(),
                           user.getEmail(), user.getCreatedAt());
    }
}

// Update DTO — all fields optional for PATCH
public record UpdateUserRequest(
    @Size(min=2, max=50) String name,   // null = unchanged
    @Email               String email
) {}

// @Transactional wraps the entire method in a single database transaction.
// If an unchecked exception escapes, the transaction is automatically rolled back.

@Service
public class OrderService {

    @Transactional                         // default: propagation=REQUIRED, rollbackOn=RuntimeException
    public Order placeOrder(PlaceOrderRequest req) {
        // All of these run in ONE transaction:
        inventoryService.reserve(req.items());     // deduct stock
        Order order = orderRepository.save(...);   // persist order
        paymentService.charge(req.payment());      // record payment
        // If ANY step throws RuntimeException → entire transaction rolls back
        return order;
    }

    @Transactional(readOnly = true)        // hint to JPA: skip dirty checking → faster
    public List<Order> getOrdersForUser(Long userId) {
        return orderRepository.findByUserId(userId);
    }

    @Transactional(propagation = Propagation.REQUIRES_NEW)  // always a fresh transaction
    public void auditLog(String action) {
        auditRepository.save(new AuditEntry(action, LocalDateTime.now()));
    }

    @Transactional(rollbackFor = CheckedPaymentException.class)  // also rollback on checked
    public void processPayment(Payment p) throws CheckedPaymentException {
        // ...
    }
}

public interface UserRepository extends JpaRepository<User, Long> {

    // JPQL query (entity-based, database-agnostic)
    @Query("SELECT u FROM User u WHERE u.email = :email AND u.active = true")
    Optional<User> findActiveByEmail(@Param("email") String email);

    // Native SQL query (database-specific)
    @Query(value = "SELECT * FROM users WHERE LOWER(name) LIKE LOWER(:pattern)",
           nativeQuery = true)
    List<User> searchByName(@Param("pattern") String pattern);

    // Projection — return only selected fields
    @Query("SELECT u.id AS id, u.name AS name, u.email AS email FROM User u")
    List<UserSummary> findAllSummaries();

    // Modifying query — must pair with @Transactional
    @Modifying
    @Transactional
    @Query("UPDATE User u SET u.active = false WHERE u.lastLoginAt < :cutoff")
    int deactivateInactiveUsers(@Param("cutoff") LocalDateTime cutoff);
}

// Projection interface
interface UserSummary {
    Long   getId();
    String getName();
    String getEmail();
}

// Specifications enable dynamic queries built at runtime
public interface UserRepository extends JpaRepository<User, Long>,
                                         JpaSpecificationExecutor<User> {}

// Specification builder
public class UserSpecs {
    public static Specification<User> hasEmail(String email) {
        return (root, query, cb) -> cb.equal(root.get("email"), email);
    }
    public static Specification<User> isActive() {
        return (root, query, cb) -> cb.isTrue(root.get("active"));
    }
    public static Specification<User> createdAfter(LocalDateTime date) {
        return (root, query, cb) -> cb.greaterThan(root.get("createdAt"), date);
    }
}

// Usage — compose specs dynamically
@Service
public class UserService {
    public List<User> search(String email, boolean onlyActive) {
        Specification<User> spec = Specification.where(null);
        if (email != null)   spec = spec.and(UserSpecs.hasEmail(email));
        if (onlyActive)      spec = spec.and(UserSpecs.isActive());
        return userRepository.findAll(spec);
    }
}

@Entity @Table(name = "orders")
public class Order {

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

    // Many orders belong to one user
    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "user_id", nullable = false)
    private User user;

    // One order has many line items — cascade: persist/delete propagates
    @OneToMany(mappedBy = "order", cascade = CascadeType.ALL, orphanRemoval = true)
    private List<OrderItem> items = new ArrayList<>();

    @Enumerated(EnumType.STRING)
    private OrderStatus status = OrderStatus.PENDING;

    // Helper method to maintain bidirectional consistency
    public void addItem(OrderItem item) {
        items.add(item);
        item.setOrder(this);
    }
}

@Entity @Table(name = "order_items")
public class OrderItem {
    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "order_id")
    private Order order;

    @Column(nullable = false)
    private String productName;
    private int quantity;
    private BigDecimal unitPrice;
}

// Enable JPA Auditing once in your @Configuration
@SpringBootApplication
@EnableJpaAuditing(auditorAwareRef = "auditorProvider")
public class MyApplication { ... }

@Bean
public AuditorAware<String> auditorProvider() {
    return () -> Optional.ofNullable(SecurityContextHolder.getContext())
        .map(ctx -> ctx.getAuthentication())
        .map(auth -> auth.getName());
}

// Now annotate your entity to auto-capture audit fields
@Entity
@EntityListeners(AuditingEntityListener.class)
public class Product {

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

    @CreatedDate   @Column(updatable = false)
    private LocalDateTime createdAt;

    @LastModifiedDate
    private LocalDateTime updatedAt;

    @CreatedBy   @Column(updatable = false, length = 100)
    private String createdBy;

    @LastModifiedBy  @Column(length = 100)
    private String updatedBy;
}

@RestControllerAdvice
public class GlobalExceptionHandler {

    private static final Logger log = LoggerFactory.getLogger(GlobalExceptionHandler.class);

    @ExceptionHandler(ResourceNotFoundException.class)
    @ResponseStatus(HttpStatus.NOT_FOUND)
    public ErrorResponse handleNotFound(ResourceNotFoundException ex,
                                        HttpServletRequest req) {
        return ErrorResponse.of(404, ex.getMessage(), req.getRequestURI());
    }

    @ExceptionHandler(MethodArgumentNotValidException.class)
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    public ErrorResponse handleValidation(MethodArgumentNotValidException ex,
                                          HttpServletRequest req) {
        String msg = ex.getBindingResult().getFieldErrors().stream()
            .map(e -> e.getField() + ": " + e.getDefaultMessage())
            .collect(Collectors.joining(", "));
        return ErrorResponse.of(400, msg, req.getRequestURI());
    }

    @ExceptionHandler(DataIntegrityViolationException.class)
    @ResponseStatus(HttpStatus.CONFLICT)
    public ErrorResponse handleConflict(DataIntegrityViolationException ex,
                                        HttpServletRequest req) {
        return ErrorResponse.of(409, "Data conflict: " + ex.getRootCause().getMessage(),
                                req.getRequestURI());
    }

    // Always add this last — prevents raw stack traces reaching the client
    @ExceptionHandler(Exception.class)
    @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
    public ErrorResponse handleGeneric(Exception ex, HttpServletRequest req) {
        log.error("Unhandled exception at {}", req.getRequestURI(), ex);
        return ErrorResponse.of(500, "An unexpected error occurred",
                                req.getRequestURI());
    }
}

// Typed exception — carries resource info for clear messages
public class ResourceNotFoundException extends RuntimeException {
    private final String resourceType;
    private final Object resourceId;

    public ResourceNotFoundException(String type, Object id) {
        super(type + " not found with id: " + id);
        this.resourceType = type;
        this.resourceId   = id;
    }
    // getters ...
}

// Throw from service layer — caught by GlobalExceptionHandler
public User findById(Long id) {
    return userRepository.findById(id)
        .orElseThrow(() -> new ResourceNotFoundException("User", id));
}

// 1. Define the annotation
@Target({ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = UniqueEmailValidator.class)
public @interface UniqueEmail {
    String message() default "Email is already registered";
    Class<?>[] groups()  default {};
    Class<? extends Payload>[] payload() default {};
}

// 2. Implement the ConstraintValidator
@Component
public class UniqueEmailValidator implements ConstraintValidator<UniqueEmail, String> {
    private final UserRepository userRepository;

    public UniqueEmailValidator(UserRepository userRepository) {
        this.userRepository = userRepository;
    }

    @Override
    public boolean isValid(String email, ConstraintValidatorContext ctx) {
        return email != null && !userRepository.existsByEmail(email);
    }
}

// 3. Use it on a DTO field
public record RegisterRequest(
    @UniqueEmail
    @Email
    String email,
    // ...
) {}

@Component
public class JwtAuthFilter extends OncePerRequestFilter {

    private final JwtService jwtService;
    private final UserDetailsService userDetailsService;

    @Override
    protected void doFilterInternal(HttpServletRequest request,
                                    HttpServletResponse response,
                                    FilterChain chain)
            throws ServletException, IOException {

        final String header = request.getHeader("Authorization");
        if (header == null || !header.startsWith("Bearer ")) {
            chain.doFilter(request, response);
            return;
        }

        String token   = header.substring(7);
        String subject = jwtService.extractSubject(token);

        if (subject != null && SecurityContextHolder.getContext().getAuthentication() == null) {
            UserDetails user = userDetailsService.loadUserByUsername(subject);
            if (jwtService.isTokenValid(token, user)) {
                UsernamePasswordAuthenticationToken authToken =
                    new UsernamePasswordAuthenticationToken(
                        user, null, user.getAuthorities());
                authToken.setDetails(new WebAuthenticationDetailsSource()
                    .buildDetails(request));
                SecurityContextHolder.getContext().setAuthentication(authToken);
            }
        }
        chain.doFilter(request, response);
    }
}

// Enable method-level security in @Configuration
@EnableMethodSecurity
public class SecurityConfig { ... }

// Now protect individual service methods
@Service
public class DocumentService {

    @PreAuthorize("hasRole('ADMIN') or #userId == authentication.principal.id")
    public Document getDocument(Long userId, Long docId) {
        return documentRepository.findByUserIdAndId(userId, docId)
            .orElseThrow(() -> new ResourceNotFoundException("Document", docId));
    }

    @PreAuthorize("hasRole('ADMIN')")
    public void deleteDocument(Long docId) {
        documentRepository.deleteById(docId);
    }

    @PostAuthorize("returnObject.owner == authentication.name")
    public Document findSecure(Long docId) {
        return documentRepository.findById(docId)
            .orElseThrow();
    }
}

# application.yml — default (shared) config
spring:
  jpa:
    show-sql: false

---
# application-dev.yml — activated with: --spring.profiles.active=dev
spring:
  config:
    activate:
      on-profile: dev
  datasource:
    url: jdbc:h2:mem:testdb    # in-memory DB for local dev
  jpa:
    show-sql: true
    hibernate:
      ddl-auto: create-drop

---
# application-prod.yml
spring:
  config:
    activate:
      on-profile: prod
  datasource:
    url: ${DB_URL}             # real database in production
  jpa:
    hibernate:
      ddl-auto: validate

@SpringBootApplication
@EnableAsync
public class MyApplication { ... }

// Custom thread pool (optional — recommended for production)
@Configuration
public class AsyncConfig {
    @Bean(name = "taskExecutor")
    public Executor taskExecutor() {
        ThreadPoolTaskExecutor exec = new ThreadPoolTaskExecutor();
        exec.setCorePoolSize(4);
        exec.setMaxPoolSize(16);
        exec.setQueueCapacity(100);
        exec.setThreadNamePrefix("async-");
        exec.initialize();
        return exec;
    }
}

@Service
public class NotificationService {

    // Returns immediately; Spring runs this on a separate thread
    @Async("taskExecutor")
    public CompletableFuture<Void> sendEmailAsync(String to, String body) {
        emailClient.send(to, body);           // may take a few seconds
        return CompletableFuture.completedFuture(null);
    }

    @Async
    public void sendPushNotificationAsync(Long userId, String message) {
        pushGateway.send(userId, message);
    }
}

// Controller — fire-and-forget, responds instantly
@PostMapping("/notify/{userId}")
@ResponseStatus(HttpStatus.ACCEPTED)
public void notify(@PathVariable Long userId, @RequestBody String message) {
    notificationService.sendPushNotificationAsync(userId, message);
    // returns 202 immediately while notification sends in background
}

// Custom health indicator — appears under /actuator/health
@Component
public class ExternalApiHealthIndicator implements HealthIndicator {

    private final ExternalApiClient apiClient;

    @Override
    public Health health() {
        try {
            boolean ok = apiClient.ping();
            return ok
                ? Health.up().withDetail("api", "reachable").build()
                : Health.down().withDetail("api", "unreachable").build();
        } catch (Exception ex) {
            return Health.down()
                .withDetail("api", "error")
                .withException(ex)
                .build();
        }
    }
}

// Custom metric counter
@Service
public class OrderService {
    private final Counter orderCounter;

    public OrderService(MeterRegistry registry) {
        this.orderCounter = Counter.builder("orders.created")
            .description("Total orders placed")
            .register(registry);
    }

    @Transactional
    public Order placeOrder(PlaceOrderRequest req) {
        Order order = // ... create order
        orderCounter.increment();
        return order;
    }
}

// @WebMvcTest loads ONLY the web layer (no JPA, no full context)
@WebMvcTest(UserController.class)
class UserControllerTest {

    @Autowired MockMvc mvc;
    @MockBean  UserService userService;   // replaced with Mockito mock

    @Test
    void getUser_returns200() throws Exception {
        UserDto dto = new UserDto(1L, "Alice", "alice@example.com", LocalDateTime.now());
        when(userService.findById(1L)).thenReturn(dto);

        mvc.perform(get("/api/v1/users/1").accept(MediaType.APPLICATION_JSON))
           .andExpect(status().isOk())
           .andExpect(jsonPath("$.name").value("Alice"))
           .andExpect(jsonPath("$.email").value("alice@example.com"));
    }

    @Test
    void createUser_returns400_whenEmailInvalid() throws Exception {
        String body = """{"name":"Bob","email":"not-an-email","password":"Secure1!"}""";
        mvc.perform(post("/api/v1/users")
               .contentType(MediaType.APPLICATION_JSON)
               .content(body))
           .andExpect(status().isBadRequest());
    }
}

// Full Spring context + in-memory H2 database
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
@AutoConfigureTestDatabase(replace = Replace.ANY)   // swap to H2
class UserIntegrationTest {

    @Autowired TestRestTemplate restTemplate;
    @Autowired UserRepository   userRepository;

    @BeforeEach void setup() { userRepository.deleteAll(); }

    @Test
    void createAndFetchUser() {
        CreateUserRequest req = new CreateUserRequest("Alice","alice@test.com","Secret1!");
        ResponseEntity<UserDto> createResp =
            restTemplate.postForEntity("/api/v1/users", req, UserDto.class);

        assertThat(createResp.getStatusCode()).isEqualTo(HttpStatus.CREATED);
        Long id = createResp.getBody().id();

        ResponseEntity<UserDto> getResp =
            restTemplate.getForEntity("/api/v1/users/" + id, UserDto.class);

        assertThat(getResp.getStatusCode()).isEqualTo(HttpStatus.OK);
        assertThat(getResp.getBody().email()).isEqualTo("alice@test.com");
    }
}