The annotation @SessionAttribute (since Spring 4.3) can be used to bind a pre-existing session attribute to a handler method parameter.
Rather than using HttpSession object directly, using this annotation can benefit auto type conversion and optional/required check. This annotation has an element 'required' which is true by default. That means if the attribute value is not present in the session, an exception will be thrown. If we set it to false then we can avoid the exception but the value received can be null.
Definition of SessionAttributeVersion: 7.0.6 package org.springframework.web.bind.annotation;
@Target(ElementType.PARAMETER)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface SessionAttribute {
@AliasFor("name")
String value() default ""; 1
@AliasFor("value")
String name() default ""; 2
boolean required() default true; 3
}
Difference between @SessionAttributes and @SessionAttribute
We saw in @SessionAttributes tutorial, that it can be used in conjunction with @ModelAttribute. That way of accessing session object is limited to a local controller only and suitable for use cases where workflow is limited to a single controller class e.g. form validation and submission. On the other hand, @SessionAttribute is used for pre-existing session attributes that are managed globally, outside the controller, e.g. in filter, interceptor etc. They are suitable for use cases like storing/accessing user authentication information etc.
Example
Following example shows, how to use @SessionAttribute to access user first visit time. A custom HandlerInterceptor populates this information in the HttpSession when user first access to the web application.
The interceptor
package com.logicbig.example;
import org.springframework.web.servlet.AsyncHandlerInterceptor;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import jakarta.servlet.http.HttpSession;
import java.time.LocalDateTime;
public class MyWebInterceptor implements AsyncHandlerInterceptor {
@Override
public boolean preHandle (HttpServletRequest request,
HttpServletResponse response,
Object handler) throws Exception {
HttpSession session = request.getSession(true);
if (session.getAttribute("sessionStartTime") == null) {
session.setAttribute("sessionStartTime", LocalDateTime.now());
}
return true;
}
}
The controller
package com.logicbig.example;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.ResponseBody;
import org.springframework.web.bind.annotation.SessionAttribute;
import java.time.Duration;
import java.time.LocalDateTime;
import java.time.temporal.ChronoUnit;
@Controller
public class ExampleController {
@RequestMapping("/")
@ResponseBody
public String handle(@SessionAttribute(name = "sessionStartTime")
LocalDateTime startDateTime) {
Duration d = Duration.between(startDateTime, LocalDateTime.now());
return String.format("First Visit time: %s<br/> Visiting site for:" +
" %s nanosecond", startDateTime,
d.getNano());
}
}
Java Config class
package com.logicbig.example;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import org.springframework.web.servlet.config.annotation.ViewResolverRegistry;
@EnableWebMvc
@ComponentScan("com.logicbig.example")
public class AppConfig implements WebMvcConfigurer {
@Override
public void addInterceptors (InterceptorRegistry registry) {
registry.addInterceptor(new MyWebInterceptor());
}
}
Running Example
To try examples, run embedded Jetty (configured in pom.xml of example project below):
mvn jetty:run 
$ curl -s http://localhost:8080/example/
First Visit time: 2026-04-01T20:46:19.773<br/> Visiting site for: 0 nanosecond
Integration Test
package com.logicbig.example;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.mock.web.MockHttpSession;
import org.springframework.test.context.ContextConfiguration;
import org.springframework.test.context.junit.jupiter.SpringExtension;
import org.springframework.test.context.junit.jupiter.web.SpringJUnitWebConfig;
import org.springframework.test.context.web.WebAppConfiguration;
import org.springframework.test.web.servlet.assertj.MockMvcTester; // New AssertJ support
import org.springframework.test.web.servlet.setup.MockMvcBuilders;
import org.springframework.web.context.WebApplicationContext;
import java.io.UnsupportedEncodingException;
import java.time.LocalDateTime;
import static org.assertj.core.api.Assertions.assertThat;
@SpringJUnitWebConfig(AppConfig.class)
public class ControllerTest {
@Autowired
private WebApplicationContext wac;
private MockMvcTester mockMvcTester;
@BeforeEach
public void setup() {
this.mockMvcTester = MockMvcTester.from(wac);
}
@Test
public void myTest() throws Exception {
MockHttpSession session = new MockHttpSession();
// Perform first request - MockMvcTester uses a fluent exchange-style API
mockMvcTester.get().uri("/")
.session(session)
.exchange()
.assertThat()
.hasStatusOk();
// Extract session attribute
LocalDateTime startTimeAfterFirstVisit =
(LocalDateTime) session.getAttribute("sessionStartTime");
// Perform second request and capture the response
var result = mockMvcTester.get().uri("/")
.session(session)
.exchange();
// Assertions using AssertJ style
result.assertThat().hasStatusOk();
String responseBody = result.getResponse().getContentAsString();
// Dynamic regex pattern matching with AssertJ
String pattern = String.format(
"First Visit time: %s.*Visiting site for: \\d+ nanosecond",
startTimeAfterFirstVisit.toString());
assertThat(responseBody).matches(pattern);
}
}
mvn clean test -Dtest="ControllerTest" Output$ mvn clean test -Dtest="ControllerTest"
[INFO] Scanning for projects...
[WARNING]
[WARNING] Some problems were encountered while building the effective model for com.logicbig.example:session-attribute-annotation-example:war:1.0-SNAPSHOT
[WARNING] 'build.plugins.plugin.version' for org.apache.maven.plugins:maven-war-plugin is missing. @ line 45, column 21
[WARNING]
[WARNING] It is highly recommended to fix these problems because they threaten the stability of your build.
[WARNING]
[WARNING] For this reason, future Maven versions might no longer support building such malformed projects.
[WARNING]
[INFO]
[INFO] -----< com.logicbig.example:session-attribute-annotation-example >------
[INFO] Building session-attribute-annotation-example 1.0-SNAPSHOT
[INFO] from pom.xml
[INFO] --------------------------------[ war ]---------------------------------
[INFO]
[INFO] --- clean:3.2.0:clean (default-clean) @ session-attribute-annotation-example ---
[INFO] Deleting D:\example-projects\spring-mvc\session-attribute-annotation-example\target
[INFO]
[INFO] --- resources:3.3.1:resources (default-resources) @ session-attribute-annotation-example ---
[WARNING] Using platform encoding (UTF-8 actually) to copy filtered resources, i.e. build is platform dependent!
[INFO] skip non existing resourceDirectory D:\example-projects\spring-mvc\session-attribute-annotation-example\src\main\resources
[INFO]
[INFO] --- compiler:3.3:compile (default-compile) @ session-attribute-annotation-example ---
[INFO] Changes detected - recompiling the module!
[INFO] Compiling 4 source files to D:\example-projects\spring-mvc\session-attribute-annotation-example\target\classes
[INFO]
[INFO] --- resources:3.3.1:testResources (default-testResources) @ session-attribute-annotation-example ---
[WARNING] Using platform encoding (UTF-8 actually) to copy filtered resources, i.e. build is platform dependent!
[INFO] skip non existing resourceDirectory D:\example-projects\spring-mvc\session-attribute-annotation-example\src\test\resources
[INFO]
[INFO] --- compiler:3.3:testCompile (default-testCompile) @ session-attribute-annotation-example ---
[INFO] Changes detected - recompiling the module!
[INFO] Compiling 1 source file to D:\example-projects\spring-mvc\session-attribute-annotation-example\target\test-classes
[INFO]
[INFO] --- surefire:3.2.5:test (default-test) @ session-attribute-annotation-example ---
[INFO] Using auto detected provider org.apache.maven.surefire.junit4.JUnit4Provider
[WARNING] file.encoding cannot be set as system property, use <argLine>-Dfile.encoding=...</argLine> instead
[INFO]
[INFO] -------------------------------------------------------
[INFO] T E S T S
[INFO] -------------------------------------------------------
[INFO] Running com.logicbig.example.ControllerTest
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 2.215 s -- in com.logicbig.example.ControllerTest
[INFO]
[INFO] Results:
[INFO]
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 7.524 s
[INFO] Finished at: 2026-04-01T20:49:10+08:00
[INFO] ------------------------------------------------------------------------
Example ProjectDependencies and Technologies Used: - spring-webmvc 7.0.6 (Spring Web MVC)
Version Compatibility: 4.3.0.RELEASE - 7.0.6 Version compatibilities of spring-webmvc with this example: Versions in green have been tested.
- spring-test 7.0.6 (Spring TestContext Framework)
- junit-jupiter-engine 6.0.3 (Module "junit-jupiter-engine" of JUnit)
- hamcrest 3.0 (Core API and libraries of hamcrest matcher framework)
- assertj-core 3.26.3 (Rich and fluent assertions for testing in Java)
- jakarta.servlet-api 6.1.0 (Jakarta Servlet API documentation)
- JDK 25
- Maven 3.9.11
|
