Spring Boot
Fundamentals

// @SpringBootApplication is equivalent to:
@SpringBootConfiguration    // = @Configuration, marks this as a config class
@EnableAutoConfiguration    // enables the auto-config mechanism
@ComponentScan              // scans this package and all sub-packages for @Component, @Service, etc.
public class MyApp { }

// Practical implication: your main class package is the root scan boundary.
// ALL Spring-managed classes must be in this package or a sub-package.
// This is why you NEVER put @SpringBootApplication in the default package.

// CLASS CONDITIONS — does a class exist on the classpath?
@ConditionalOnClass(DataSource.class)           // activate if DataSource.class exists
@ConditionalOnMissingClass("com.example.Foo")   // activate if this class does NOT exist

// BEAN CONDITIONS — does a bean exist in the context?
@ConditionalOnBean(DataSource.class)            // activate if a DataSource bean exists
@ConditionalOnMissingBean(DataSource.class)     // activate if NO DataSource bean exists (most common)
@ConditionalOnSingleCandidate(DataSource.class) // activate if exactly ONE DataSource bean exists

// PROPERTY CONDITIONS — is a property set?
@ConditionalOnProperty(
    name = "myapp.feature.enabled",
    havingValue = "true",
    matchIfMissing = false   // if property absent, condition = false
)

// RESOURCE CONDITIONS — does a file exist?
@ConditionalOnResource(resources = "classpath:hibernate.cfg.xml")

// WEB CONDITIONS
@ConditionalOnWebApplication                    // activate in servlet-based web app
@ConditionalOnNotWebApplication                 // activate in non-web app (batch jobs, CLIs)

// EXPRESSION CONDITIONS — SpEL expression
@ConditionalOnExpression("${myapp.enabled:true} && ${myapp.version:1} > 2")

// 1. Write the auto-configuration class
@AutoConfiguration                              // marks as auto-config (Spring Boot 2.7+)
@ConditionalOnClass(AuditService.class)         // only if our library is present
@ConditionalOnProperty(
    prefix = "mycompany.audit",
    name = "enabled",
    matchIfMissing = true                       // enabled by default
)
@EnableConfigurationProperties(AuditProperties.class)
public class AuditAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean                   // user can override by defining their own
    public AuditService auditService(AuditProperties props) {
        return new DefaultAuditService(props.getLevel(), props.getDestination());
    }

    @Bean
    @ConditionalOnMissingBean
    @ConditionalOnBean(AuditService.class)
    public AuditInterceptor auditInterceptor(AuditService service) {
        return new AuditInterceptor(service);
    }
}

// 2. Register it in your library JAR:
// src/main/resources/META-INF/spring/
//   org.springframework.boot.autoconfigure.AutoConfiguration.imports
//
// Contents of that file:
// com.mycompany.audit.AuditAutoConfiguration

// 3. Any app that adds your library as a dependency gets audit features automatically.

// In Maven pom.xml — these are the starters you'll use constantly:

// WEB — Tomcat + Spring MVC + Jackson
// spring-boot-starter-web

// DATA — Spring Data JPA + Hibernate + HikariCP
// spring-boot-starter-data-jpa

// SECURITY — Spring Security
// spring-boot-starter-security

// TESTING — JUnit 5 + Mockito + MockMvc + AssertJ
// spring-boot-starter-test

// VALIDATION — Hibernate Validator (JSR-380)
// spring-boot-starter-validation

// ACTUATOR — production monitoring endpoints
// spring-boot-starter-actuator

// CACHE — Spring Cache abstraction
// spring-boot-starter-cache

// REDIS — Spring Data Redis + Lettuce client
// spring-boot-starter-data-redis

// KAFKA — Spring for Apache Kafka
// spring-kafka

// MAIL — JavaMail + Spring Mail
// spring-boot-starter-mail

// ASYNC — WebFlux reactive stack
// spring-boot-starter-webflux

spring-boot-starter-web
├── spring-boot-starter (core Spring Boot)
│   ├── spring-boot
│   ├── spring-boot-autoconfigure
│   └── spring-boot-starter-logging (Logback + SLF4J)
├── spring-boot-starter-json
│   └── jackson-databind (JSON serialization)
├── spring-boot-starter-tomcat
│   └── tomcat-embed-core (embedded web server)
└── spring-web + spring-webmvc (Spring MVC)

// In pom.xml:
// <dependency>
//   <groupId>org.springframework.boot</groupId>
//   <artifactId>spring-boot-starter-web</artifactId>
//   <exclusions>
//     <exclusion>
//       <groupId>org.springframework.boot</groupId>
//       <artifactId>spring-boot-starter-tomcat</artifactId>
//     </exclusion>
//   </exclusions>
// </dependency>
// <dependency>
//   <groupId>org.springframework.boot</groupId>
//   <artifactId>spring-boot-starter-undertow</artifactId>
// </dependency>

// Why Undertow? Non-blocking I/O, lower memory, better performance
// at high concurrency — common choice for microservices.

@Component
public class TomcatCustomizer
    implements WebServerFactoryCustomizer<TomcatServletWebServerFactory> {

    @Override
    public void customize(TomcatServletWebServerFactory factory) {
        factory.setPort(8443);

        // Configure SSL/TLS programmatically
        Ssl ssl = new Ssl();
        ssl.setKeyStore("classpath:keystore.p12");
        ssl.setKeyStorePassword(System.getenv("KEYSTORE_PASSWORD"));
        ssl.setKeyStoreType("PKCS12");
        factory.setSsl(ssl);

        // Add Tomcat Valve (for request logging, access control)
        factory.addEngineValves(new AccessLogValve());

        // Increase connection timeout for heavy file uploads
        factory.addConnectorCustomizers(connector ->
            connector.setProperty("connectionTimeout", "60000")
        );
    }
}

// ── Method 1: @Value (simple, one-off values) ──────────────────────────
@Service
public class EmailService {

    @Value("${myapp.email.from}")
    private String fromAddress;

    @Value("${myapp.email.max-retries:3}")  // :3 is the default value
    private int maxRetries;

    @Value("${myapp.email.recipients}")     // comma-separated → List
    private List<String> recipients;
}

// ── Method 2: Environment (programmatic access) ────────────────────────
@Service
public class FeatureService {

    @Autowired
    private Environment env;

    public boolean isFeatureEnabled(String featureName) {
        return env.getProperty("myapp.features." + featureName, Boolean.class, false);
    }
}

// ── Method 3: @ConfigurationProperties (preferred for groups) ─────────
// Covered in depth in the next topic — this is the production standard.

# Default config (all environments)
server:
  port: 8080
spring:
  application:
    name: order-service

---
# Dev profile override
spring:
  config:
    activate:
      on-profile: dev
  datasource:
    url: jdbc:h2:mem:testdb
    
---
# Production profile override  
spring:
  config:
    activate:
      on-profile: prod
  datasource:
    url: ${DATABASE_URL}    # from environment variable

// 1. Define the properties class
@ConfigurationProperties(prefix = "myapp.mail")
@Validated   // enables JSR-380 validation on startup
public class MailProperties {

    @NotBlank
    private String host;

    @Min(1) @Max(65535)
    private int port = 587;   // default value

    @NotBlank
    private String username;

    @NotBlank
    private String password;

    private boolean startTlsEnabled = true;

    @DurationUnit(ChronoUnit.SECONDS)
    private Duration connectionTimeout = Duration.ofSeconds(30);

    private List<String> adminRecipients = new ArrayList<>();

    // Nested configuration class
    private Retry retry = new Retry();

    public static class Retry {
        private int maxAttempts = 3;
        private Duration delay = Duration.ofSeconds(5);
        // getters/setters...
    }

    // Standard getters and setters (or use Lombok @Data)
}

// 2. Register it
@Configuration
@EnableConfigurationProperties(MailProperties.class)  // explicit registration
public class AppConfig { }
// OR just add @ConfigurationPropertiesScan to your main class

// 3. Use it
@Service
public class EmailService {

    private final MailProperties mailProps;

    public EmailService(MailProperties mailProps) {
        this.mailProps = mailProps;
    }

    public void send(String to, String subject, String body) {
        // Use mailProps.getHost(), mailProps.getPort(), etc.
    }
}

// 4. application.yml binds automatically:
// myapp:
//   mail:
//     host: smtp.mycompany.com
//     port: 587
//     username: noreply@mycompany.com
//     password: ${MAIL_PASSWORD}
//     start-tls-enabled: true
//     connection-timeout: 30s
//     admin-recipients:
//       - ops@mycompany.com
//       - alerts@mycompany.com
//     retry:
//       max-attempts: 3
//       delay: 5s

myapp.mail.startTlsEnabled=true        # camelCase
myapp.mail.start-tls-enabled=true      # kebab-case (recommended for .yml)
myapp.mail.start_tls_enabled=true      # underscore
MYAPP_MAIL_STARTTLSENABLED=true        # env var (uppercase, underscores)

// In pom.xml dependencies:
// <dependency>
//   <groupId>org.springframework.boot</groupId>
//   <artifactId>spring-boot-configuration-processor</artifactId>
//   <optional>true</optional>
// </dependency>

// This generates META-INF/spring-configuration-metadata.json
// IntelliJ and VS Code read this file to provide:
// - Property name completion
// - Type information
// - Default value hints
// - Javadoc tooltips

# Via command-line (deployment standard)
java -jar myapp.jar --spring.profiles.active=prod

# Via environment variable (Docker/K8s standard)
export SPRING_PROFILES_ACTIVE=prod

# Via application.properties (dev default — set this in your repo)
# spring.profiles.active=dev

# Multiple profiles (comma-separated, all activate simultaneously)
java -jar myapp.jar --spring.profiles.active=prod,metrics,feature-flags

src/main/resources/
  application.yml              # base config (all environments)
  application-dev.yml          # dev overrides
  application-test.yml         # test overrides
  application-staging.yml      # staging overrides
  application-prod.yml         # production overrides

spring:
  datasource:
    url: jdbc:h2:mem:devdb;MODE=PostgreSQL
    username: sa
    password: ""
  jpa:
    show-sql: true
    hibernate:
      ddl-auto: create-drop    # recreate schema on startup

logging:
  level:
    com.mycompany: DEBUG
    org.hibernate.SQL: DEBUG
    org.hibernate.type.descriptor.sql: TRACE  # shows bind parameters

myapp:
  feature:
    email-sending: false        # don't actually send emails in dev

spring:
  datasource:
    url: ${DATABASE_URL}
    username: ${DATABASE_USER}
    password: ${DATABASE_PASSWORD}
    hikari:
      maximum-pool-size: 50
  jpa:
    show-sql: false
    hibernate:
      ddl-auto: validate         # NEVER create-drop in prod

logging:
  level:
    root: WARN
    com.mycompany: INFO

server:
  tomcat:
    max-threads: 400

// Use a fake payment provider in dev/test, real one in prod
public interface PaymentGateway {
    PaymentResult charge(PaymentRequest request);
}

@Service
@Profile("!prod")  // active for all profiles EXCEPT prod
public class MockPaymentGateway implements PaymentGateway {
    @Override
    public PaymentResult charge(PaymentRequest request) {
        log.info("MOCK: Charging {} for ${}", request.getCustomerId(), request.getAmount());
        return PaymentResult.success("mock-txn-" + UUID.randomUUID());
    }
}

@Service
@Profile("prod")
public class StripePaymentGateway implements PaymentGateway {
    @Override
    public PaymentResult charge(PaymentRequest request) {
        // actual Stripe API call
        return stripeClient.charge(request);
    }
}

// OrderService gets whichever bean is active — no conditional logic needed
@Service
public class OrderService {
    private final PaymentGateway paymentGateway;  // injected correctly by profile

    public OrderService(PaymentGateway paymentGateway) {
        this.paymentGateway = paymentGateway;
    }
}

spring:
  profiles:
    group:
      prod: prod-db, prod-cache, prod-monitoring, prod-security
      dev: dev-db, dev-stubs, dev-debug

# Activating "prod" now activates all four sub-profiles:
# java -jar app.jar --spring.profiles.active=prod

@Service
public class MyService implements InitializingBean, DisposableBean {

    // Option 1: @PostConstruct (JSR-250 — recommended)
    // Runs after DI is complete, before bean is put into use
    @PostConstruct
    public void init() {
        log.info("Bean initialized — dependencies are injected and ready");
        // Load lookup tables, validate connections, warm up caches
    }

    // Option 2: InitializingBean.afterPropertiesSet()
    // Called at the same time as @PostConstruct (just before)
    @Override
    public void afterPropertiesSet() {
        // Framework-level init logic — prefer @PostConstruct in your code
    }

    // Option 3: @Bean(initMethod = "start")
    // For third-party beans you can't annotate

    // SHUTDOWN ─────────────────────────────────────────────────
    @PreDestroy
    public void cleanup() {
        // Runs when the Spring context closes (app shutdown)
        // Close connections, flush buffers, release resources
    }

    @Override
    public void destroy() {
        // DisposableBean equivalent — called at same time as @PreDestroy
    }
}

// ── Application lifecycle (broader scope) ──────────────────────
@Component
@Order(1)
public class AppStartupRunner implements ApplicationRunner {
    @Override
    public void run(ApplicationArguments args) {
        // Runs after ALL beans are ready (step 7 in startup sequence)
        // Better for: cross-bean coordination, data loading, health checks
    }
}

// Always use a static final logger — one per class
@Service
public class OrderService {

    // SLF4J logger — Lombok @Slf4j annotation generates this
    private static final Logger log = LoggerFactory.getLogger(OrderService.class);
    // Or with Lombok: just add @Slf4j to the class

    public Order createOrder(CreateOrderRequest request) {
        // ── GOOD: parameterized messages (no string concatenation) ──
        log.info("Creating order for customer={} items={}", 
                 request.getCustomerId(), request.getItemCount());

        // ── NEVER do this — string concat happens even if DEBUG is off ──
        // log.debug("Order: " + request.toString());  // BAD

        // ── DEBUG for detailed diagnostic information ──
        log.debug("Order request details: {}", request);  // toString() only called if DEBUG is on

        try {
            Order order = processOrder(request);
            log.info("Order created successfully orderId={} total={}", 
                     order.getId(), order.getTotal());
            return order;
        } catch (InsufficientStockException e) {
            // Warn-level for expected, recoverable business issues
            log.warn("Insufficient stock for order customerId={} productId={}", 
                     request.getCustomerId(), e.getProductId());
            throw e;
        } catch (Exception e) {
            // Error-level with full stack trace for unexpected failures
            log.error("Failed to create order for customerId={}", 
                      request.getCustomerId(), e);  // pass exception as last arg for stack trace
            throw new OrderProcessingException("Order creation failed", e);
        }
    }
}

logging:
  level:
    root: WARN                              # global minimum level
    com.mycompany: INFO                     # your app at INFO
    com.mycompany.service: DEBUG            # specific package more verbose
    org.hibernate.SQL: DEBUG                # see generated SQL
    org.hibernate.type.descriptor.sql: TRACE  # see SQL bind parameters
    org.springframework.web: DEBUG          # see request mapping
    
  # Log file output (optional)
  file:
    name: /var/log/myapp/application.log
    
  pattern:
    # Console pattern with color
    console: "%clr(%d{HH:mm:ss.SSS}){faint} %clr(${LOG_LEVEL_PATTERN:-%5p}) %clr(---){faint} %clr([%15.15t]){faint} %clr(%-40.40logger{39}){cyan} %clr(:){faint} %m%n"
    # File pattern without color codes
    file: "%d{yyyy-MM-dd HH:mm:ss.SSS} %5p --- [%t] %-40.40logger{39} : %m%n"

// pom.xml dependency:
// <dependency>
//   <groupId>net.logstash.logback</groupId>
//   <artifactId>logstash-logback-encoder</artifactId>
//   <version>7.4</version>
// </dependency>

// logback-spring.xml (place in src/main/resources/)
// <configuration>
//   <springProfile name="prod">
//     <appender name="JSON" class="ch.qos.logback.core.ConsoleAppender">
//       <encoder class="net.logstash.logback.encoder.LogstashEncoder"/>
//     </appender>
//     <root level="INFO">
//       <appender-ref ref="JSON" />
//     </root>
//   </springProfile>
// </configuration>

// Each log line becomes JSON like:
// {
//   "@timestamp": "2024-01-15T10:30:00.000Z",
//   "level": "INFO",
//   "logger_name": "com.mycompany.OrderService",
//   "message": "Creating order for customer=123 items=3",
//   "thread_name": "http-nio-8080-exec-1",
//   "traceId": "abc123"   ← from Spring Cloud Sleuth / Micrometer Tracing
// }

@Component
public class RequestLoggingFilter implements Filter {

    @Override
    public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain)
            throws IOException, ServletException {

        HttpServletRequest request = (HttpServletRequest) req;

        // Extract or generate correlation ID
        String correlationId = Optional
            .ofNullable(request.getHeader("X-Correlation-Id"))
            .orElse(UUID.randomUUID().toString());

        try {
            // Put into MDC — now appears in EVERY log line for this request
            MDC.put("correlationId", correlationId);
            MDC.put("userId", extractUserId(request));
            MDC.put("requestPath", request.getRequestURI());

            ((HttpServletResponse) res).setHeader("X-Correlation-Id", correlationId);
            chain.doFilter(req, res);
        } finally {
            MDC.clear();  // CRITICAL: clear MDC after each request (thread pool reuse)
        }
    }
}