Document how to downgrade dependencies to use embedded Jetty 11

In addition to downgrading the Servlet API to 5.0, we also need to cover the impact that this will have on testing. Framework’s Servlet-related mocks require Servlet 6.0 and will fail due to the absence of ServletConnection when run against the Servlet 5.0 API. Similarly, Jetty requires Servlet 5.0 and will fail due to the absence of HttpSessionContext when run against the Servlet 6.0 API. This leaves us with two arrangements that will work:

1. Tests use the Servlet 6.0 API and avoid starting Jetty by only using a mock web environment
2. Tests use the Servlet 5.0 API and avoid using Framework’s Servlet mocks by only using a full-blown web environment

If a mixture of web environments is required by an application’s tests, it can be done but it may require some structural changes to separate the two web environments. With Gradle this could be done with different source sets or separate modules. With Maven, I believe separate modules will always be required.

[wilkinsona]

Yes, I believe that will work as your dependency management for jakarta.servlet-api is nearer to the root so it will take precedence over what’s in the imported spring-boot-dependencies.

[david-romero]

Hi @wilkinsona,

I’m facing this issue in a real application, not only in tests. Do you know how to fix it?

Starters added:

• spring-boot-starter-web
  • exclude
    • spring-boot-starter-tomcat
• spring-boot-starter-jetty
• spring-boot-starter-amqp
• spring-boot-starter-data-redis
• spring-boot-starter-actuator
• spring-boot-starter-validation
• spring-boot-starter-json
• spring-boot-starter-webflux
• spring-boot-starter-data-jpa

Version: 3.0.0-RC2

Error trace:

java.lang.ClassNotFoundException: jakarta.servlet.http.HttpSessionContext
	at java.base/jdk.internal.loader.BuiltinClassLoader.loadClass(BuiltinClassLoader.java:641)
	at java.base/jdk.internal.loader.ClassLoaders$AppClassLoader.loadClass(ClassLoaders.java:188)
	at java.base/java.lang.ClassLoader.loadClass(ClassLoader.java:520)
	... 41 common frames omitted
Wrapped by: java.lang.NoClassDefFoundError: jakarta/servlet/http/HttpSessionContext
	at java.base/java.lang.ClassLoader.defineClass1(Native Method)
	at java.base/java.lang.ClassLoader.defineClass(ClassLoader.java:1012)
	at java.base/java.security.SecureClassLoader.defineClass(SecureClassLoader.java:150)
	at java.base/jdk.internal.loader.BuiltinClassLoader.defineClass(BuiltinClassLoader.java:862)
	at java.base/jdk.internal.loader.BuiltinClassLoader.findClassOnClassPathOrNull(BuiltinClassLoader.java:760)
	at java.base/jdk.internal.loader.BuiltinClassLoader.loadClassOrNull(BuiltinClassLoader.java:681)
	at java.base/jdk.internal.loader.BuiltinClassLoader.loadClass(BuiltinClassLoader.java:639)
	at java.base/jdk.internal.loader.ClassLoaders$AppClassLoader.loadClass(ClassLoaders.java:188)
	at java.base/java.lang.ClassLoader.loadClass(ClassLoader.java:520)
	at org.eclipse.jetty.server.session.SessionHandler.<clinit>(SessionHandler.java:136)
	at org.eclipse.jetty.servlet.ServletContextHandler.newSessionHandler(ServletContextHandler.java:339)
	at org.eclipse.jetty.servlet.ServletContextHandler.getSessionHandler(ServletContextHandler.java:432)
	at org.eclipse.jetty.servlet.ServletContextHandler.relinkHandlers(ServletContextHandler.java:257)
	at org.eclipse.jetty.servlet.ServletContextHandler.<init>(ServletContextHandler.java:180)
	at org.eclipse.jetty.webapp.WebAppContext.<init>(WebAppContext.java:301)
	at org.eclipse.jetty.webapp.WebAppContext.<init>(WebAppContext.java:228)
	at org.springframework.boot.web.embedded.jetty.JettyEmbeddedWebAppContext.<init>(JettyEmbeddedWebAppContext.java:28)
	at org.springframework.boot.web.embedded.jetty.JettyServletWebServerFactory.getWebServer(JettyServletWebServerFactory.java:158)
	at org.springframework.boot.web.servlet.context.ServletWebServerApplicationContext.createWebServer(ServletWebServerApplicationContext.java:183)
	at org.springframework.boot.web.servlet.context.ServletWebServerApplicationContext.onRefresh(ServletWebServerApplicationContext.java:161)
	... 21 common frames omitted
Wrapped by: org.springframework.context.ApplicationContextException: Unable to start web server
	at org.springframework.boot.web.servlet.context.ServletWebServerApplicationContext.onRefresh(ServletWebServerApplicationContext.java:164)
	at org.springframework.context.support.AbstractApplicationContext.refresh(AbstractApplicationContext.java:578)
	at org.springframework.boot.web.servlet.context.ServletWebServerApplicationContext.refresh(ServletWebServerApplicationContext.java:146)
	at org.springframework.boot.SpringApplication.refresh(SpringApplication.java:730)
	at org.springframework.boot.SpringApplication.refreshContext(SpringApplication.java:432)
	at org.springframework.boot.SpringApplication.run(SpringApplication.java:308)
	at org.springframework.boot.SpringApplication.run(SpringApplication.java:1302)
	at org.springframework.boot.SpringApplication.run(SpringApplication.java:1291)