Add documentation for Jetty session support (dropwizard#4681)

Add a documentation section on session support and provide an e2e test explaining how to use it.

docs/source/manual/core.rst

@@ -524,7 +524,7 @@ settings in configuration:
 ``https://<hostname>:<port>/health-check?type=<type>&name=<name>``
 
 * replace ``<type>`` with ``ready`` or ``alive``; defaults to ``ready`` if the ``type`` parameter is not provided
-* replace ``<name>`` with the name of the health check to query. Multiple names can be provided, or no no names. If all checks are desired, 
+* replace ``<name>`` with the name of the health check to query. Multiple names can be provided, or no no names. If all checks are desired,
   ``name=all`` can be specified to retrieve all checks
 
 .. _man-core-health-providedchecks:
@@ -566,17 +566,17 @@ In the `Application.run()` method, you can access views of the health state data
 **Accessing data directly**
 
 .. code-block:: java
-    
+
     @Override
     public void run(final AppConfiguration configuration, final Environment environment) {
         ...
         Collection<HealthStateView> views = environment.health().healthStateAggregator().healthStateViews();
     }
 
 **Listening to data changes**
-    
+
 .. code-block:: java
-    
+
     @Override
     public void run(final AppConfiguration configuration, final Environment environment) {
         ...
@@ -1826,6 +1826,34 @@ Adding a ``Cache-Control`` statement to your resource class is simple with Dropw
 
 The ``@CacheControl`` annotation will take all of the parameters of the ``Cache-Control`` header.
 
+Sessions
+--------
+
+Although Dropwizard's main purpose is to build stateless RESTful APIs, a stateful web service can
+be built using HTTP sessions. As most users won't profit from having session support enabled by
+default, session support is implemented as opt-in.
+
+The underlying Jetty server will handle sessions only if a ``SessionHandler`` is provided at
+application startup. Therefore the following code has to be added to the ``run`` method of the
+``Application`` class:
+
+.. code-block:: java
+
+    @Override
+    public void run(final TestConfiguration configuration, final Environment environment) {
+        environment.servlets().setSessionHandler(new org.eclipse.jetty.server.session.SessionHandler());
+    }
+
+This will provide Jetty's default ``SessionHandler`` to the servlet environment and session support is enabled.
+To get an ``HttpSession`` object injected into a Jersey resource method, Dropwizard provides a ``@Session``
+annotation:
+
+.. code-block:: java
+
+    public Response doSomethingWithSessions(@Session HttpSession httpSession) {
+        return Response.ok().build();
+    }
+
 .. _man-core-representations:
 
 Representations

dropwizard-e2e/pom.xml

@@ -48,6 +48,10 @@
             <groupId>io.dropwizard</groupId>
             <artifactId>dropwizard-jersey</artifactId>
         </dependency>
+        <dependency>
+            <groupId>io.dropwizard</groupId>
+            <artifactId>dropwizard-jetty</artifactId>
+        </dependency>
         <dependency>
             <groupId>io.dropwizard</groupId>
             <artifactId>dropwizard-logging</artifactId>
@@ -113,6 +117,16 @@
             <groupId>org.eclipse.jetty</groupId>
             <artifactId>jetty-io</artifactId>
         </dependency>
+        <dependency>
+            <groupId>org.eclipse.jetty</groupId>
+            <artifactId>jetty-server</artifactId>
+            <exclusions>
+                <exclusion>
+                    <groupId>javax.servlet</groupId>
+                    <artifactId>javax.servlet-api</artifactId>
+                </exclusion>
+            </exclusions>
+        </dependency>
         <dependency>
             <groupId>org.glassfish.jersey.core</groupId>
             <artifactId>jersey-common</artifactId>

dropwizard-e2e/src/main/java/com/example/httpsessions/HttpSessionsApp.java

@@ -0,0 +1,14 @@
+package com.example.httpsessions;
+
+import io.dropwizard.Application;
+import io.dropwizard.Configuration;
+import io.dropwizard.setup.Environment;
+import org.eclipse.jetty.server.session.SessionHandler;
+
+public class HttpSessionsApp extends Application<Configuration> {
+    @Override
+    public void run(Configuration configuration, Environment environment) throws Exception {
+        environment.servlets().setSessionHandler(new SessionHandler());
+        environment.jersey().register(new HttpSessionsResource());
+    }
+}

dropwizard-e2e/src/main/java/com/example/httpsessions/HttpSessionsResource.java

@@ -0,0 +1,17 @@
+package com.example.httpsessions;
+
+import io.dropwizard.jersey.sessions.Session;
+
+import javax.servlet.http.HttpSession;
+import javax.ws.rs.GET;
+import javax.ws.rs.Path;
+import javax.ws.rs.core.Response;
+
+@Path("/")
+public class HttpSessionsResource {
+    @GET
+    @Path("session")
+    public Response isSessionInjected(@Session HttpSession httpSession) {
+        return Response.ok(httpSession != null).build();
+    }
+}

dropwizard-e2e/src/test/java/com/example/httpsessions/HttpSessionsTest.java

@@ -0,0 +1,22 @@
+package com.example.httpsessions;
+
+import io.dropwizard.Configuration;
+import io.dropwizard.testing.ResourceHelpers;
+import io.dropwizard.testing.junit5.DropwizardAppExtension;
+import io.dropwizard.testing.junit5.DropwizardExtensionsSupport;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+@ExtendWith(DropwizardExtensionsSupport.class)
+class HttpSessionsTest {
+    public static final DropwizardAppExtension<Configuration> RULE =
+        new DropwizardAppExtension<>(HttpSessionsApp.class, ResourceHelpers.resourceFilePath("httpsessions/config.yml"));
+
+    @Test
+    void testInjectedSessionsIsNotNull() {
+        Boolean sessionNotNull = RULE.client().target(String.format("http://localhost:%d/session", RULE.getLocalPort())).request().get(Boolean.class);
+        assertThat(sessionNotNull).isNotNull().isTrue();
+    }
+}

dropwizard-e2e/src/test/resources/httpsessions/config.yml

@@ -0,0 +1,7 @@
+server:
+  applicationConnectors:
+    - type: http
+      port: 0
+  adminConnectors:
+    - type: http
+      port: 0