Spring Framework User Guide

1. Quick Start

Spring Framework is the foundational Java application framework that provides comprehensive infrastructure support for developing enterprise Java applications. It handles the plumbing so you can focus on business logic through dependency injection, aspect-oriented programming, data access abstractions, web frameworks (both servlet-based and reactive), messaging, testing, and more.

Key features:

• Inversion of Control (IoC) container — manages object creation, wiring, and lifecycle
• Aspect-Oriented Programming (AOP) — cross-cutting concerns without boilerplate
• Spring MVC — annotation-driven servlet-based web framework
• Spring WebFlux — fully reactive, non-blocking web framework built on Project Reactor
• Data access abstractions — JdbcTemplate, R2DBC, ORM integration, transaction management
• Messaging — JMS, WebSocket/STOMP, and generic messaging abstractions
• Spring Expression Language (SpEL) — powerful expression evaluation at runtime
• Comprehensive testing support — MockMvc, WebTestClient, context caching, bean overrides

Prerequisites: JDK 17+ (JDK 21+ recommended for virtual threads support)

Minimal Gradle setup:

dependencies {
    implementation 'org.springframework:spring-context:7.0.0'
}

Minimal example — annotation-based IoC:

import org.springframework.context.annotation.*;

@Configuration
@ComponentScan("com.example")
public class AppConfig {

    @Bean
    public GreetingService greetingService() {
        return new GreetingService();
    }
}

import org.springframework.context.annotation.AnnotationConfigApplicationContext;

public class Application {
    public static void main(String[] args) {
        var ctx = new AnnotationConfigApplicationContext(AppConfig.class);
        GreetingService svc = ctx.getBean(GreetingService.class);
        svc.greet("World");
        ctx.close();
    }
}

Hello, World!

Tip

Most Spring applications use Spring Boot which auto-configures Spring Framework. If you are starting a new project, begin with Spring Initializr — it generates a ready-to-run Spring Boot project with Spring Framework as the underlying engine.

What to try next:

• See "Installation" for all dependency management options
• See "Core Usage — Dependency Injection" for full IoC container usage
• See "Core Usage — Web Applications" for building REST APIs and web apps
• See Admin Guide for architecture deep-dives and module internals

2. Installation

System Requirements

Important

Spring Framework 7.x requires Jakarta EE 10+ APIs (jakarta.* namespace). If migrating from Spring 5.x, you must update all javax.* imports to jakarta.*.

Dependency Management with BOM

Spring Framework publishes a Bill of Materials (BOM) so you can manage all module versions in one place.

Maven

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework</groupId>
            <artifactId>spring-framework-bom</artifactId>
            <version>7.0.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>org.springframework</groupId>
        <artifactId>spring-context</artifactId>
    </dependency>
</dependencies>

Gradle

dependencies {
    implementation platform('org.springframework:spring-framework-bom:7.0.0')
    implementation 'org.springframework:spring-context'
}

Module Dependency Guide

Choose the modules you need based on your use case:

Note

Transitive dependencies are managed automatically. Adding spring-webmvc pulls in spring-web, spring-context, spring-aop, spring-beans, spring-core, and spring-expression.

Maven Repositories

repositories {
    mavenCentral()
    // For milestones and release candidates:
    maven { url = "https://repo.spring.io/milestone" }
    // For snapshots:
    maven { url = "https://repo.spring.io/snapshot" }
}

Post-Install Verification

import org.springframework.core.SpringVersion;

public class VersionCheck {
    public static void main(String[] args) {
        System.out.println("Spring Framework: " + SpringVersion.getVersion());
    }
}

Spring Framework: 7.0.0

Install Troubleshooting

Problem: ClassNotFoundException: jakarta.servlet.ServletException

Your servlet container or dependency set uses the old javax.servlet namespace. Spring Framework 7.x requires Jakarta EE 10+ (jakarta.*). Upgrade your container (Tomcat 11+, Jetty 12+) and dependencies.

Problem: Gradle dependency resolution errors with SNAPSHOT versions

Add the Spring snapshot repository and ensure dynamic version caching is disabled:

configurations.all {
    resolutionStrategy {
        cacheChangingModulesFor 0, "seconds"
        cacheDynamicVersionsFor 0, "seconds"
    }
}

Problem: NoSuchMethodError or NoClassDefFoundError at runtime

Multiple Spring versions on the classpath. Use the BOM (see above) to enforce a single consistent version across all modules.

Problem: Module conflicts with spring-jcl

Spring Framework uses spring-jcl (Jakarta Commons Logging bridge) for logging. If you see conflicts with commons-logging, exclude it:

<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-core</artifactId>
    <exclusions>
        <exclusion>
            <groupId>org.springframework</groupId>
            <artifactId>spring-jcl</artifactId>
        </exclusion>
    </exclusions>
</dependency>

Problem: Kotlin extension functions not resolving

Ensure you have both spring-context and the Kotlin standard library on the classpath. Kotlin extensions are defined in companion source sets (e.g., spring-r2dbc/src/main/kotlin/) and require the Kotlin runtime.

Problem: @ComponentScan not finding beans

Verify the base package matches where your annotated classes live. By default, @ComponentScan without arguments scans the package of the configuration class and all sub-packages.

Problem: Java module system (JPMS) issues

Spring Framework provides Automatic-Module-Name in each JAR manifest. If using the module system, add requires org.springframework.context; (or the relevant module) to your module-info.java.

3. Configuration

Spring Framework supports three configuration styles that can be mixed freely.

Annotation-Based Configuration (Recommended)

@Configuration
@ComponentScan("com.example")
@PropertySource("classpath:application.properties")
public class AppConfig {

    @Value("${app.name}")
    private String appName;

    @Bean
    public DataSource dataSource() {
        var ds = new HikariDataSource();
        ds.setJdbcUrl("jdbc:postgresql://localhost/mydb");
        return ds;
    }
}

Key annotations:

Java-Based Configuration (Programmatic)

var ctx = new AnnotationConfigApplicationContext();
ctx.register(AppConfig.class, SecurityConfig.class);
ctx.getEnvironment().setActiveProfiles("production");
ctx.refresh();

XML Configuration (Legacy)

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:context="http://www.springframework.org/schema/context"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="
           http://www.springframework.org/schema/beans
           https://www.springframework.org/schema/beans/spring-beans.xsd
           http://www.springframework.org/schema/context
           https://www.springframework.org/schema/context/spring-context.xsd">

    <context:component-scan base-package="com.example"/>
    <context:property-placeholder location="classpath:app.properties"/>

    <bean id="dataSource" class="com.zaxxer.hikari.HikariDataSource">
        <property name="jdbcUrl" value="${db.url}"/>
    </bean>
</beans>

Tip

Annotation-based configuration is the standard for new projects. XML configuration remains fully supported for legacy codebases and is required for certain namespace features (<aop:config>, <tx:annotation-driven>, etc.).

XML Namespace Reference (User-Facing)

The following XML namespaces are available for configuration. These are taken from the source code's NamespaceHandler implementations:

See Admin Guide for the complete configuration reference with all attributes.

Profiles

@Configuration
@Profile("development")
public class DevConfig {
    @Bean
    public DataSource dataSource() {
        return new EmbeddedDatabaseBuilder()
            .setType(EmbeddedDatabaseType.H2)
            .addScript("schema.sql")
            .build();
    }
}

Activate profiles via:

ctx.getEnvironment().setActiveProfiles("development");

Or via system property: -Dspring.profiles.active=development

Warning

Beans without a @Profile annotation are always active. If you define a DataSource in both a profiled and un-profiled config, you may get duplicate bean conflicts. Use @Primary or ensure only one is active per profile.

Environment Abstraction

@Component
public class EnvironmentAwareService {

    @Autowired
    private Environment env;

    public String getDbUrl() {
        return env.getProperty("db.url", "jdbc:h2:mem:default");
    }

    public boolean isProduction() {
        return env.acceptsProfiles(Profiles.of("production"));
    }
}

4. Core Usage

4.1 Dependency Injection

Constructor Injection (Preferred)

@Service
public class OrderService {

    private final OrderRepository repository;
    private final NotificationService notifications;

    public OrderService(OrderRepository repository, NotificationService notifications) {
        this.repository = repository;
        this.notifications = notifications;
    }

    public void placeOrder(Order order) {
        repository.save(order);
        notifications.sendConfirmation(order);
    }
}

Tip

When a class has a single constructor, @Autowired is not required — Spring injects dependencies automatically. This is the cleanest pattern for testability and immutability.

Field and Setter Injection

@Component
public class ReportGenerator {

    @Autowired
    private TemplateEngine templateEngine;

    private DataSource dataSource;

    @Autowired
    public void setDataSource(DataSource dataSource) {
        this.dataSource = dataSource;
    }
}

Qualifier and Primary

@Bean
@Primary
public DataSource primaryDataSource() { /* ... */ }

@Bean("analyticsDs")
public DataSource analyticsDataSource() { /* ... */ }

// Inject specific bean:
@Autowired
@Qualifier("analyticsDs")
private DataSource analyticsDataSource;

Collection and Map Injection

@Service
public class PluginManager {

    // Injects all beans of type Plugin, ordered by @Order / @Priority
    private final List<Plugin> plugins;

    // Injects all beans of type Plugin, keyed by bean name
    private final Map<String, Plugin> pluginMap;

    public PluginManager(List<Plugin> plugins, Map<String, Plugin> pluginMap) {
        this.plugins = plugins;
        this.pluginMap = pluginMap;
    }
}

ObjectProvider (Lazy / Optional Dependencies)

@Service
public class FlexibleService {

    private final ObjectProvider<CacheManager> cacheManagerProvider;

    public FlexibleService(ObjectProvider<CacheManager> cacheManagerProvider) {
        this.cacheManagerProvider = cacheManagerProvider;
    }

    public void doWork() {
        CacheManager cm = cacheManagerProvider.getIfAvailable();
        if (cm != null) {
            // Use caching
        }
    }
}

Bean Scopes

Bean Lifecycle Callbacks

@Component
public class ConnectionPool implements InitializingBean, DisposableBean {

    @Override
    public void afterPropertiesSet() {
        // Called after all properties are set — initialize pool
    }

    @Override
    public void destroy() {
        // Called on container shutdown — close connections
    }
}

// Or annotation-based:
@Component
public class ConnectionPool {

    @PostConstruct
    public void init() {
        // Initialize
    }

    @PreDestroy
    public void cleanup() {
        // Cleanup
    }
}

4.2 Aspect-Oriented Programming (AOP)

Enable AOP with @EnableAspectJAutoProxy:

@Configuration
@EnableAspectJAutoProxy
public class AopConfig { }

Define aspects:

@Aspect
@Component
public class LoggingAspect {

    @Before("execution(* com.example.service.*.*(..))")
    public void logMethodEntry(JoinPoint jp) {
        System.out.println("Entering: " + jp.getSignature().getName());
    }

    @Around("@annotation(com.example.Timed)")
    public Object measureTime(ProceedingJoinPoint pjp) throws Throwable {
        long start = System.nanoTime();
        Object result = pjp.proceed();
        long elapsed = System.nanoTime() - start;
        System.out.printf("%s took %d ms%n", pjp.getSignature().getName(), elapsed / 1_000_000);
        return result;
    }

    @AfterReturning(pointcut = "within(com.example..*)", returning = "result")
    public void logReturn(JoinPoint jp, Object result) {
        System.out.println(jp.getSignature().getName() + " returned: " + result);
    }

    @AfterThrowing(pointcut = "within(com.example..*)", throwing = "ex")
    public void logException(JoinPoint jp, Exception ex) {
        System.err.println("Exception in " + jp.getSignature() + ": " + ex.getMessage());
    }
}

Pointcut expression reference:

Note

Spring AOP uses JDK dynamic proxies for interfaces and CGLIB proxies for classes. If you need to advise private or final methods, use full AspectJ weaving via spring-aspects and load-time weaving.

Combining Pointcuts

@Aspect
@Component
public class SecurityAspect {

    @Pointcut("within(com.example.service..*)")
    private void inServiceLayer() {}

    @Pointcut("@annotation(com.example.RequiresAuth)")
    private void requiresAuth() {}

    @Before("inServiceLayer() && requiresAuth()")
    public void checkAuth(JoinPoint jp) {
        // Combined pointcut: service layer methods annotated with @RequiresAuth
    }
}

4.3 Spring Expression Language (SpEL)

SpEL enables dynamic value resolution at runtime:

@Value("#{systemProperties['user.home']}")
private String userHome;

@Value("#{T(java.lang.Math).random() * 100}")
private double randomValue;

@Value("#{orderService.getActiveOrderCount()}")
private int activeOrders;

// Conditional default:
@Value("#{systemProperties['cache.size'] ?: 256}")
private int cacheSize;

// Collection selection:
@Value("#{users.?[role == 'ADMIN']}")
private List<User> admins;

// Collection projection:
@Value("#{orders.![total]}")
private List<BigDecimal> orderTotals;

SpEL in XML:

<bean id="config" class="com.example.AppConfig">
    <property name="maxRetries" value="#{systemProperties['max.retries'] ?: 3}"/>
</bean>

4.4 Events

The ApplicationContext publishes and receives events:

// Define an event
public class OrderPlacedEvent extends ApplicationEvent {
    private final Order order;
    public OrderPlacedEvent(Object source, Order order) {
        super(source);
        this.order = order;
    }
    public Order getOrder() { return order; }
}

// Publish
@Service
public class OrderService {
    @Autowired
    private ApplicationEventPublisher publisher;

    public void placeOrder(Order order) {
        // ... save order
        publisher.publishEvent(new OrderPlacedEvent(this, order));
    }
}

// Listen — annotation-based (recommended)
@Component
public class OrderEventListener {

    @EventListener
    public void handleOrderPlaced(OrderPlacedEvent event) {
        System.out.println("Order placed: " + event.getOrder().getId());
    }

    @EventListener(condition = "#event.order.total > 1000")
    public void handleHighValueOrder(OrderPlacedEvent event) {
        // Special handling for high-value orders
    }

    @Async
    @EventListener
    public void asyncNotification(OrderPlacedEvent event) {
        // Runs asynchronously in a separate thread
    }

    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
    public void afterOrderCommitted(OrderPlacedEvent event) {
        // Only fires after the transaction commits successfully
    }
}

Note

@Async event listeners require @EnableAsync on a configuration class and a configured TaskExecutor. @TransactionalEventListener requires an active transaction context.

4.5 Web Applications — Spring MVC

Basic REST Controller

@RestController
@RequestMapping("/api/orders")
public class OrderController {

    private final OrderService orderService;

    public OrderController(OrderService orderService) {
        this.orderService = orderService;
    }

    @GetMapping
    public List<Order> listOrders(
            @RequestParam(defaultValue = "0") int page,
            @RequestParam(defaultValue = "20") int size) {
        return orderService.findAll(page, size);
    }

    @GetMapping("/{id}")
    public ResponseEntity<Order> getOrder(@PathVariable Long id) {
        return orderService.findById(id)
            .map(ResponseEntity::ok)
            .orElse(ResponseEntity.notFound().build());
    }

    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public Order createOrder(@Valid @RequestBody OrderRequest request) {
        return orderService.create(request);
    }

    @PutMapping("/{id}")
    public Order updateOrder(@PathVariable Long id, @Valid @RequestBody OrderRequest request) {
        return orderService.update(id, request);
    }

    @DeleteMapping("/{id}")
    @ResponseStatus(HttpStatus.NO_CONTENT)
    public void deleteOrder(@PathVariable Long id) {
        orderService.delete(id);
    }
}

MVC Configuration

@Configuration
@EnableWebMvc
public class WebConfig implements WebMvcConfigurer {

    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/api/**")
            .allowedOrigins("https://example.com")
            .allowedMethods("GET", "POST", "PUT", "DELETE");
    }

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(new LoggingInterceptor())
            .addPathPatterns("/api/**")
            .excludePathPatterns("/api/health");
    }

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/static/**")
            .addResourceLocations("classpath:/static/")
            .setCachePeriod(3600);
    }

    @Override
    public void configureContentNegotiation(ContentNegotiationConfigurer configurer) {
        configurer.defaultContentType(MediaType.APPLICATION_JSON);
    }

    @Override
    public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
        converters.add(new MappingJackson2HttpMessageConverter());
        converters.add(new StringHttpMessageConverter());
    }
}

Warning

@EnableWebMvc takes full control of Spring MVC configuration. If using Spring Boot, do NOT use @EnableWebMvc — Boot provides its own auto-configuration that @EnableWebMvc will override.

Exception Handling

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(OrderNotFoundException.class)
    @ResponseStatus(HttpStatus.NOT_FOUND)
    public ErrorResponse handleNotFound(OrderNotFoundException ex) {
        return new ErrorResponse("NOT_FOUND", ex.getMessage());
    }

    @ExceptionHandler(MethodArgumentNotValidException.class)
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    public ErrorResponse handleValidation(MethodArgumentNotValidException ex) {
        var errors = ex.getBindingResult().getFieldErrors().stream()
            .map(e -> e.getField() + ": " + e.getDefaultMessage())
            .toList();
        return new ErrorResponse("VALIDATION_ERROR", String.join("; ", errors));
    }

    @ExceptionHandler(Exception.class)
    @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
    public ErrorResponse handleGeneral(Exception ex) {
        return new ErrorResponse("INTERNAL_ERROR", "An unexpected error occurred");
    }
}

Request Mapping Annotations

Parameter Binding Annotations

API Versioning (Spring Framework 7.0+)

Spring Framework 7.0 introduced built-in API versioning support through ApiVersionConfigurer:

@Configuration
@EnableWebMvc
public class WebConfig implements WebMvcConfigurer {

    @Override
    public void configureApiVersioning(ApiVersionConfigurer configurer) {
        configurer
            .useRequestHeader("X-API-Version")
            .useQueryParam("version")
            .setDefaultVersion("1.0");
    }
}

Version resolvers (confirmed from ApiVersionConfigurer source):

The default version parser is SemanticApiVersionParser which supports semantic versioning.

Content Negotiation and Message Converters

Spring MVC auto-detects the following HttpMessageConverter implementations based on classpath availability (confirmed from AnnotationDrivenBeanDefinitionParser source):

4.6 Web Applications — Spring WebFlux (Reactive)

Annotation-Based Reactive Controller

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

    private final ProductRepository repository;

    public ProductController(ProductRepository repository) {
        this.repository = repository;
    }

    @GetMapping
    public Flux<Product> listProducts() {
        return repository.findAll();
    }

    @GetMapping("/{id}")
    public Mono<ResponseEntity<Product>> getProduct(@PathVariable String id) {
        return repository.findById(id)
            .map(ResponseEntity::ok)
            .defaultIfEmpty(ResponseEntity.notFound().build());
    }

    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public Mono<Product> createProduct(@Valid @RequestBody Product product) {
        return repository.save(product);
    }

    @GetMapping(value = "/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
    public Flux<Product> streamProducts() {
        return repository.findAll().delayElements(Duration.ofSeconds(1));
    }
}

Functional Endpoints

@Configuration
public class RouterConfig {

    @Bean
    public RouterFunction<ServerResponse> routes(ProductHandler handler) {
        return RouterFunctions.route()
            .GET("/api/products", handler::listAll)
            .GET("/api/products/{id}", handler::getById)
            .POST("/api/products", handler::create)
            .filter((request, next) -> {
                // Filter/middleware
                return next.handle(request);
            })
            .build();
    }
}

@Component
public class ProductHandler {

    private final ProductRepository repository;

    public ProductHandler(ProductRepository repository) {
        this.repository = repository;
    }

    public Mono<ServerResponse> listAll(ServerRequest request) {
        return ServerResponse.ok()
            .contentType(MediaType.APPLICATION_JSON)
            .body(repository.findAll(), Product.class);
    }

    public Mono<ServerResponse> getById(ServerRequest request) {
        String id = request.pathVariable("id");
        return repository.findById(id)
            .flatMap(p -> ServerResponse.ok().bodyValue(p))
            .switchIfEmpty(ServerResponse.notFound().build());
    }

    public Mono<ServerResponse> create(ServerRequest request) {
        return request.bodyToMono(Product.class)
            .flatMap(repository::save)
            .flatMap(p -> ServerResponse.created(URI.create("/api/products/" + p.getId())).bodyValue(p));
    }
}

Tip

Choose annotation-based controllers when migrating from Spring MVC (same programming model). Choose functional endpoints when you want a lambda-based routing DSL with explicit request/response handling.

WebFlux Configuration

@Configuration
@EnableWebFlux
public class WebFluxConfig implements WebFluxConfigurer {

    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/api/**")
            .allowedOrigins("*")
            .allowedMethods("GET", "POST");
    }

    @Override
    public void configureApiVersioning(ApiVersionConfigurer configurer) {
        configurer.usePathSegment(0)
            .setDefaultVersion("1.0");
    }

    @Override
    public void configureHttpMessageCodecs(ServerCodecConfigurer configurer) {
        configurer.defaultCodecs().maxInMemorySize(512 * 1024); // 512KB
    }
}

4.7 Data Access — JDBC

JdbcTemplate

@Repository
public class OrderRepository {

    private final JdbcTemplate jdbc;

    public OrderRepository(DataSource dataSource) {
        this.jdbc = new JdbcTemplate(dataSource);
    }

    public List<Order> findAll() {
        return jdbc.query("SELECT id, customer, total FROM orders",
            (rs, rowNum) -> new Order(
                rs.getLong("id"),
                rs.getString("customer"),
                rs.getBigDecimal("total")
            ));
    }

    public Optional<Order> findById(long id) {
        try {
            return Optional.ofNullable(jdbc.queryForObject(
                "SELECT id, customer, total FROM orders WHERE id = ?",
                (rs, rowNum) -> new Order(rs.getLong("id"), rs.getString("customer"), rs.getBigDecimal("total")),
                id));
        } catch (EmptyResultDataAccessException e) {
            return Optional.empty();
        }
    }

    public int save(Order order) {
        return jdbc.update("INSERT INTO orders (customer, total) VALUES (?, ?)",
            order.getCustomer(), order.getTotal());
    }

    public int[] batchSave(List<Order> orders) {
        return jdbc.batchUpdate(
            "INSERT INTO orders (customer, total) VALUES (?, ?)",
            new BatchPreparedStatementSetter() {
                @Override
                public void setValues(PreparedStatement ps, int i) throws SQLException {
                    ps.setString(1, orders.get(i).getCustomer());
                    ps.setBigDecimal(2, orders.get(i).getTotal());
                }
                @Override
                public int getBatchSize() { return orders.size(); }
            });
    }
}

NamedParameterJdbcTemplate

@Repository
public class UserRepository {

    private final NamedParameterJdbcTemplate jdbc;

    public UserRepository(DataSource dataSource) {
        this.jdbc = new NamedParameterJdbcTemplate(dataSource);
    }

    public List<User> findByRole(String role) {
        return jdbc.query(
            "SELECT * FROM users WHERE role = :role",
            Map.of("role", role),
            (rs, rowNum) -> new User(rs.getLong("id"), rs.getString("name"), rs.getString("role"))
        );
    }

    public List<User> findByIds(List<Long> ids) {
        return jdbc.query(
            "SELECT * FROM users WHERE id IN (:ids)",
            Map.of("ids", ids),
            (rs, rowNum) -> new User(rs.getLong("id"), rs.getString("name"), rs.getString("role"))
        );
    }
}

SimpleJdbcInsert

@Repository
public class OrderRepository {

    private final SimpleJdbcInsert insert;

    public OrderRepository(DataSource dataSource) {
        this.insert = new SimpleJdbcInsert(dataSource)
            .withTableName("orders")
            .usingGeneratedKeyColumns("id");
    }

    public long save(Order order) {
        Map<String, Object> params = Map.of(
            "customer", order.getCustomer(),
            "total", order.getTotal()
        );
        return insert.executeAndReturnKey(params).longValue();
    }
}

Embedded Database (Testing)

@Bean
public DataSource testDataSource() {
    return new EmbeddedDatabaseBuilder()
        .setType(EmbeddedDatabaseType.H2)
        .addScript("classpath:schema.sql")
        .addScript("classpath:test-data.sql")
        .build();
}

4.8 Data Access — R2DBC (Reactive)

@Repository
public class ReactiveOrderRepository {

    private final DatabaseClient client;

    public ReactiveOrderRepository(ConnectionFactory connectionFactory) {
        this.client = DatabaseClient.create(connectionFactory);
    }

    public Flux<Order> findAll() {
        return client.sql("SELECT id, customer, total FROM orders")
            .map(row -> new Order(
                row.get("id", Long.class),
                row.get("customer", String.class),
                row.get("total", BigDecimal.class)))
            .all();
    }

    public Mono<Order> findById(Long id) {
        return client.sql("SELECT id, customer, total FROM orders WHERE id = :id")
            .bind("id", id)
            .map(row -> new Order(
                row.get("id", Long.class),
                row.get("customer", String.class),
                row.get("total", BigDecimal.class)))
            .one();
    }

    public Mono<Void> save(Order order) {
        return client.sql("INSERT INTO orders (customer, total) VALUES (:customer, :total)")
            .bind("customer", order.getCustomer())
            .bind("total", order.getTotal())
            .then();
    }
}

Note

R2DBC provides non-blocking database access for reactive applications. It requires an R2DBC driver for your database (e.g., io.r2dbc:r2dbc-postgresql for PostgreSQL, io.r2dbc:r2dbc-h2 for H2). Kotlin coroutine extensions are available in spring-r2dbc/src/main/kotlin/.

4.9 Transaction Management

Declarative Transactions (Recommended)

@Configuration
@EnableTransactionManagement
public class TxConfig {

    @Bean
    public PlatformTransactionManager transactionManager(DataSource ds) {
        return new DataSourceTransactionManager(ds);
    }
}

@Service
@Transactional
public class OrderService {

    @Transactional(readOnly = true)
    public List<Order> findAll() {
        return repository.findAll();
    }

    @Transactional(propagation = Propagation.REQUIRES_NEW, timeout = 30)
    public void placeOrder(Order order) {
        repository.save(order);
        inventoryService.reserve(order.getItems());
    }

    @Transactional(rollbackFor = BusinessException.class, noRollbackFor = WarningException.class)
    public void processPayment(Payment payment) {
        // ...
    }
}

@Transactional attributes:

Transaction propagation behaviors:

Warning

@Transactional only works on public methods called from outside the class. Self-invocation (calling a @Transactional method from within the same class) bypasses the proxy and the transaction is not applied. Use TransactionTemplate for programmatic transactions within the same class.

Programmatic Transactions

@Service
public class BatchService {

    private final TransactionTemplate txTemplate;

    public BatchService(PlatformTransactionManager txManager) {
        this.txTemplate = new TransactionTemplate(txManager);
        this.txTemplate.setIsolationLevel(TransactionDefinition.ISOLATION_SERIALIZABLE);
    }

    public void processBatch(List<Item> items) {
        txTemplate.execute(status -> {
            for (Item item : items) {
                process(item);
            }
            return null; // Commit on successful return
        });
    }
}

Reactive Transactions

@Configuration
@EnableTransactionManagement
public class R2dbcTxConfig {

    @Bean
    public ReactiveTransactionManager transactionManager(ConnectionFactory cf) {
        return new R2dbcTransactionManager(cf);
    }
}

@Service
public class ReactiveOrderService {

    @Transactional
    public Mono<Order> placeOrder(Order order) {
        return repository.save(order)
            .flatMap(saved -> inventoryService.reserve(saved.getItems())
                .thenReturn(saved));
    }
}

4.10 Task Execution and Scheduling

Enable Async and Scheduling

@Configuration
@EnableAsync
@EnableScheduling
public class TaskConfig {

    @Bean
    public ThreadPoolTaskExecutor taskExecutor() {
        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
        executor.setCorePoolSize(5);
        executor.setMaxPoolSize(10);
        executor.setQueueCapacity(25);
        return executor;
    }

    @Bean
    public ThreadPoolTaskScheduler taskScheduler() {
        ThreadPoolTaskScheduler scheduler = new ThreadPoolTaskScheduler();
        scheduler.setPoolSize(5);
        return scheduler;
    }
}

Scheduled Tasks

@Component
public class ScheduledJobs {

    @Scheduled(fixedRate = 60000)
    public void refreshCache() {
        // Runs every 60 seconds
    }

    @Scheduled(cron = "0 0 2 * * ?")
    public void nightlyCleanup() {
        // Runs at 2 AM daily
    }

    @Scheduled(fixedDelay = 30000, initialDelay = 5000)
    public void pollExternalSystem() {
        // Runs 30s after previous completion, 5s initial delay
    }
}

Async Methods

@Service
public class EmailService {

    @Async
    public CompletableFuture<SendResult> sendEmail(String to, String subject, String body) {
        // Long-running email send
        SendResult result = mailSender.send(to, subject, body);
        return CompletableFuture.completedFuture(result);
    }

    @Async("customExecutor")
    public void sendBulkEmails(List<EmailRequest> requests) {
        // Uses a specific named executor
        requests.forEach(r -> mailSender.send(r));
    }
}

Task Decorators (Context Propagation)

@Bean
ThreadPoolTaskExecutor decoratedTaskExecutor() {
    ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
    executor.setTaskDecorator(new ContextPropagatingTaskDecorator());
    return executor;
}

Tip

Use ContextPropagatingTaskDecorator to propagate observability context (trace IDs, MDC) across async task boundaries.

4.11 Caching

@Configuration
@EnableCaching
public class CacheConfig {

    @Bean
    public CacheManager cacheManager() {
        return new ConcurrentMapCacheManager("products", "users");
    }
}

@Service
public class ProductService {

    @Cacheable("products")
    public Product findById(Long id) {
        // Expensive lookup — result cached by id
        return repository.findById(id).orElseThrow();
    }

    @Cacheable(value = "products", key = "#category + '-' + #page")
    public List<Product> findByCategory(String category, int page) {
        return repository.findByCategory(category, page);
    }

    @CachePut(value = "products", key = "#product.id")
    public Product update(Product product) {
        return repository.save(product);
    }

    @CacheEvict(value = "products", allEntries = true)
    public void clearProductCache() {
        // Evicts all entries
    }

    @Caching(
        put = @CachePut(value = "products", key = "#product.id"),
        evict = @CacheEvict(value = "productLists", allEntries = true)
    )
    public Product save(Product product) {
        return repository.save(product);
    }
}

4.12 Validation

public class OrderRequest {

    @NotBlank(message = "Customer name is required")
    private String customer;

    @NotNull @Positive
    private BigDecimal total;

    @Size(min = 1, message = "At least one item is required")
    private List<@Valid OrderItem> items;

    @Email
    private String email;

    // getters/setters
}

@RestController
public class OrderController {

    @PostMapping("/api/orders")
    public Order create(@Valid @RequestBody OrderRequest request) {
        // Validation errors automatically return 400
        return orderService.create(request);
    }
}

Important

Bean Validation requires a JSR-380 implementation on the classpath (e.g., Hibernate Validator: org.hibernate.validator:hibernate-validator). Spring auto-detects it and creates a LocalValidatorFactoryBean.

Programmatic Validation

@Service
public class OrderService {

    @Autowired
    private Validator validator;

    public void processOrder(Order order) {
        Set<ConstraintViolation<Order>> violations = validator.validate(order);
        if (!violations.isEmpty()) {
            throw new ConstraintViolationException(violations);
        }
        // process
    }
}

4.13 WebSocket and STOMP

@Configuration
@EnableWebSocketMessageBroker
public class WebSocketConfig implements WebSocketMessageBrokerConfigurer {

    @Override
    public void configureMessageBroker(MessageBrokerRegistry config) {
        config.enableSimpleBroker("/topic", "/queue");
        config.setApplicationDestinationPrefixes("/app");
    }

    @Override
    public void registerStompEndpoints(StompEndpointRegistry registry) {
        registry.addEndpoint("/ws").withSockJS();
    }
}

@Controller
public class ChatController {

    @MessageMapping("/chat.send")
    @SendTo("/topic/messages")
    public ChatMessage send(ChatMessage message) {
        return message;
    }

    @MessageMapping("/chat.private")
    @SendToUser("/queue/reply")
    public ChatMessage privateReply(ChatMessage message, Principal principal) {
        return new ChatMessage("Reply to " + principal.getName());
    }
}

Note

For production WebSocket deployments, consider using a full-featured STOMP broker relay (e.g., RabbitMQ with STOMP plugin) instead of the simple in-memory broker. Configure with config.enableStompBrokerRelay("/topic", "/queue").

4.14 JMS Messaging

@Configuration
@EnableJms
public class JmsConfig {

    @Bean
    public DefaultJmsListenerContainerFactory jmsListenerContainerFactory(
            ConnectionFactory connectionFactory) {
        var factory = new DefaultJmsListenerContainerFactory();
        factory.setConnectionFactory(connectionFactory);
        factory.setConcurrency("3-10");
        factory.setSessionTransacted(true);
        return factory;
    }
}

// Sending
@Service
public class NotificationSender {

    private final JmsTemplate jmsTemplate;

    public NotificationSender(JmsTemplate jmsTemplate) {
        this.jmsTemplate = jmsTemplate;
    }

    public void send(Notification notification) {
        jmsTemplate.convertAndSend("notifications", notification);
    }

    public void sendWithHeaders(Notification notification) {
        jmsTemplate.convertAndSend("notifications", notification, message -> {
            message.setStringProperty("priority", "HIGH");
            return message;
        });
    }
}

// Receiving
@Component
public class NotificationListener {

    @JmsListener(destination = "notifications", concurrency = "3-5")
    public void onMessage(Notification notification) {
        System.out.println("Received: " + notification);
    }

    @JmsListener(destination = "orders", selector = "priority = 'HIGH'")
    public void onHighPriorityOrder(Order order) {
        // Only receives messages where JMS property priority='HIGH'
    }
}

4.15 REST Client (WebClient and RestClient)

RestClient (Blocking — Spring Framework 7.x)

RestClient client = RestClient.builder()
    .baseUrl("https://api.example.com")
    .defaultHeader(HttpHeaders.AUTHORIZATION, "Bearer " + token)
    .build();

// GET
User user = client.get()
    .uri("/users/{id}", userId)
    .retrieve()
    .body(User.class);

// POST
Order created = client.post()
    .uri("/orders")
    .body(orderRequest)
    .retrieve()
    .body(Order.class);

WebClient (Reactive)

WebClient client = WebClient.builder()
    .baseUrl("https://api.example.com")
    .defaultHeader(HttpHeaders.AUTHORIZATION, "Bearer " + token)
    .build();

// GET
Mono<User> user = client.get()
    .uri("/users/{id}", userId)
    .retrieve()
    .bodyToMono(User.class);

// POST
Mono<Order> created = client.post()
    .uri("/orders")
    .bodyValue(orderRequest)
    .retrieve()
    .bodyToMono(Order.class);

// Error handling
Mono<User> userWithErrors = client.get()
    .uri("/users/{id}", userId)
    .retrieve()
    .onStatus(HttpStatusCode::is4xxClientError,
        resp -> Mono.error(new UserNotFoundException(userId)))
    .bodyToMono(User.class);

// Streaming
Flux<ServerSentEvent<String>> events = client.get()
    .uri("/events/stream")
    .retrieve()
    .bodyToFlux(new ParameterizedTypeReference<ServerSentEvent<String>>() {});

4.16 HTTP Interface Clients (Declarative)

public interface UserClient {

    @GetExchange("/users/{id}")
    User getUser(@PathVariable Long id);

    @PostExchange("/users")
    User createUser(@RequestBody UserRequest request);

    @GetExchange("/users")
    List<User> listUsers(@RequestParam("role") String role);

    @DeleteExchange("/users/{id}")
    void deleteUser(@PathVariable Long id);
}

@Configuration
public class ClientConfig {

    @Bean
    public UserClient userClient(RestClient.Builder builder) {
        RestClient restClient = builder.baseUrl("https://api.example.com").build();
        return HttpServiceProxyFactory
            .builderFor(RestClientAdapter.create(restClient))
            .build()
            .createClient(UserClient.class);
    }
}

4.17 Testing

Unit Testing with MockMvc

@WebMvcTest(OrderController.class)
class OrderControllerTest {

    @Autowired
    private MockMvc mockMvc;

    @MockitoBean
    private OrderService orderService;

    @Test
    void shouldReturnOrder() throws Exception {
        when(orderService.findById(1L)).thenReturn(Optional.of(new Order(1L, "Alice", BigDecimal.TEN)));

        mockMvc.perform(get("/api/orders/1"))
            .andExpect(status().isOk())
            .andExpect(jsonPath("$.customer").value("Alice"))
            .andExpect(jsonPath("$.total").value(10));
    }

    @Test
    void shouldReturn404WhenNotFound() throws Exception {
        when(orderService.findById(999L)).thenReturn(Optional.empty());

        mockMvc.perform(get("/api/orders/999"))
            .andExpect(status().isNotFound());
    }

    @Test
    void shouldValidateInput() throws Exception {
        mockMvc.perform(post("/api/orders")
                .contentType(MediaType.APPLICATION_JSON)
                .content("{\"customer\":\"\",\"total\":-1}"))
            .andExpect(status().isBadRequest());
    }
}

Integration Testing

@SpringJUnitConfig(AppConfig.class)
@Transactional
class OrderServiceIntegrationTest {

    @Autowired
    private OrderService orderService;

    @Test
    void shouldCreateAndRetrieveOrder() {
        Order order = orderService.create(new OrderRequest("Bob", BigDecimal.valueOf(99.99)));
        assertThat(order.getId()).isNotNull();

        Order found = orderService.findById(order.getId()).orElseThrow();
        assertThat(found.getCustomer()).isEqualTo("Bob");
    }
}

WebTestClient (Reactive)

@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
class ProductControllerTest {

    @Autowired
    private WebTestClient webTestClient;

    @Test
    void shouldListProducts() {
        webTestClient.get().uri("/api/products")
            .exchange()
            .expectStatus().isOk()
            .expectBodyList(Product.class)
            .hasSize(3);
    }

    @Test
    void shouldStreamProducts() {
        webTestClient.get().uri("/api/products/stream")
            .accept(MediaType.TEXT_EVENT_STREAM)
            .exchange()
            .expectStatus().isOk()
            .expectBodyList(Product.class)
            .hasSize(10);
    }
}

Bean Override in Tests

@SpringJUnitConfig(AppConfig.class)
class ServiceTest {

    @MockitoBean
    private ExternalApiClient apiClient;

    @Autowired
    private MyService myService;

    @Test
    void shouldHandleApiFailure() {
        when(apiClient.fetchData()).thenThrow(new RuntimeException("API down"));
        assertThatThrownBy(() -> myService.process())
            .isInstanceOf(ProcessingException.class);
    }
}

Tip

@MockitoBean (Spring Framework 7.x) replaces the older @MockBean from Spring Boot. It creates a Mockito mock and registers it as a bean override in the test application context.

SQL Test Scripts

@SpringJUnitConfig(TestConfig.class)
@Sql(scripts = "classpath:test-data.sql", executionPhase = Sql.ExecutionPhase.BEFORE_TEST_METHOD)
@Transactional
class UserServiceTest {

    @Autowired
    private UserService userService;

    @Test
    void shouldFindUsers() {
        List<User> admins = userService.findByRole("ADMIN");
        assertThat(admins).hasSize(2);
    }
}

Test Context Configuration Annotations

4.18 Kotlin Support

Spring Framework provides first-class Kotlin support with extensions and DSLs:

Routing DSL (WebFlux):

@Configuration
class AppConfig {

    @Bean
    fun router(handler: UserHandler) = coRouter {
        GET("/api/users", handler::listAll)
        GET("/api/users/{id}", handler::getById)
        POST("/api/users", handler::create)
    }
}

Bean definition DSL:

val beans = beans {
    bean<UserRepository>()
    bean<UserService>()
    bean {
        UserHandler(ref())
    }
}

JdbcTemplate extensions:

val count = jdbcTemplate.queryForObject<Int>("SELECT COUNT(*) FROM users")

R2DBC Coroutine extensions:

@Repository
class UserRepository(private val client: DatabaseClient) {

    suspend fun findById(id: Long): User? =
        client.sql("SELECT * FROM users WHERE id = :id")
            .bind("id", id)
            .map { row -> User(row.get("id", Long::class.java)!!, row.get("name", String::class.java)!!) }
            .awaitOneOrNull()

    fun findAll(): Flow<User> =
        client.sql("SELECT * FROM users")
            .map { row -> User(row.get("id", Long::class.java)!!, row.get("name", String::class.java)!!) }
            .flow()
}

4.19 Internationalization (i18n)

@Configuration
public class I18nConfig {

    @Bean
    public MessageSource messageSource() {
        var source = new ReloadableResourceBundleMessageSource();
        source.setBasename("classpath:messages");
        source.setDefaultEncoding("UTF-8");
        return source;
    }

    @Bean
    public LocaleResolver localeResolver() {
        var resolver = new SessionLocaleResolver();
        resolver.setDefaultLocale(Locale.ENGLISH);
        return resolver;
    }
}