From 6eee256e12663a5465be6fceffe0b75178f23c37 Mon Sep 17 00:00:00 2001
From: Rob Winch <362503+rwinch@users.noreply.github.com>
Date: Thu, 22 May 2025 14:57:13 -0500
Subject: [PATCH] Demonstrate include-code usage

Closes gh-17161
---
 .../ROOT/pages/servlet/architecture.adoc      | 25 +----------
 .../FilterChainUsage.java                     | 42 +++++++++++++++++++
 .../servletfiltersreview/FilterChainUsage.kt  | 37 ++++++++++++++++
 3 files changed, 80 insertions(+), 24 deletions(-)
 create mode 100644 docs/src/test/java/org/springframework/security/docs/servlet/servletfiltersreview/FilterChainUsage.java
 create mode 100644 docs/src/test/kotlin/org/springframework/security/kt/docs/servlet/servletfiltersreview/FilterChainUsage.kt

diff --git a/docs/modules/ROOT/pages/servlet/architecture.adoc b/docs/modules/ROOT/pages/servlet/architecture.adoc
index 8b1183064b..7bba33945d 100644
--- a/docs/modules/ROOT/pages/servlet/architecture.adoc
+++ b/docs/modules/ROOT/pages/servlet/architecture.adoc
@@ -29,30 +29,7 @@ In this case, the `Filter` typically writes the `HttpServletResponse`.
 The power of the `Filter` comes from the `FilterChain` that is passed into it.
 
 .`FilterChain` Usage Example
-[tabs]
-======
-Java::
-+
-[source,java,role="primary"]
-----
-public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) {
-	// do something before the rest of the application
-    chain.doFilter(request, response); // invoke the rest of the application
-    // do something after the rest of the application
-}
-----
-
-Kotlin::
-+
-[source,kotlin,role="secondary"]
-----
-fun doFilter(request: ServletRequest, response: ServletResponse, chain: FilterChain) {
-    // do something before the rest of the application
-    chain.doFilter(request, response) // invoke the rest of the application
-    // do something after the rest of the application
-}
-----
-======
+include-code::./FilterChainUsage[tag=dofilter,indent=0]
 
 Since a `Filter` impacts only downstream `Filter` instances and the `Servlet`, the order in which each `Filter` is invoked is extremely important.
 
diff --git a/docs/src/test/java/org/springframework/security/docs/servlet/servletfiltersreview/FilterChainUsage.java b/docs/src/test/java/org/springframework/security/docs/servlet/servletfiltersreview/FilterChainUsage.java
new file mode 100644
index 0000000000..702e73c08a
--- /dev/null
+++ b/docs/src/test/java/org/springframework/security/docs/servlet/servletfiltersreview/FilterChainUsage.java
@@ -0,0 +1,42 @@
+/*
+ * Copyright 2002-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.security.docs.servlet.servletfiltersreview;
+
+import java.io.IOException;
+
+import jakarta.servlet.Filter;
+import jakarta.servlet.FilterChain;
+import jakarta.servlet.ServletException;
+import jakarta.servlet.ServletRequest;
+import jakarta.servlet.ServletResponse;
+
+/**
+ * Demos FilterChain Usage.
+ * @author Rob Winch
+ */
+public class FilterChainUsage implements Filter {
+
+	// tag::dofilter[]
+	@Override
+	public void doFilter(ServletRequest request, ServletResponse response,
+			FilterChain chain) throws IOException, ServletException {
+		// do something before the rest of the application
+		chain.doFilter(request, response); // invoke the rest of the application
+		// do something after the rest of the application
+	}
+	// end::dofilter[]
+}
diff --git a/docs/src/test/kotlin/org/springframework/security/kt/docs/servlet/servletfiltersreview/FilterChainUsage.kt b/docs/src/test/kotlin/org/springframework/security/kt/docs/servlet/servletfiltersreview/FilterChainUsage.kt
new file mode 100644
index 0000000000..b35a0b29c1
--- /dev/null
+++ b/docs/src/test/kotlin/org/springframework/security/kt/docs/servlet/servletfiltersreview/FilterChainUsage.kt
@@ -0,0 +1,37 @@
+/*
+ * Copyright 2002-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.security.kt.docs.servlet.servletfiltersreview
+
+import jakarta.servlet.*
+import java.io.IOException
+
+/**
+ * Demos FilterChain Usage.
+ * @author Rob Winch
+ */
+class FilterChainUsage : Filter {
+
+    // tag::dofilter[]
+    @Throws(IOException::class, ServletException::class)
+    override fun doFilter(request: ServletRequest?, response: ServletResponse?, chain: FilterChain) {
+        // do something before the rest of the application
+        chain.doFilter(request, response) // invoke the rest of the application
+        // do something after the rest of the application
+    }
+    // end::dofilter[]
+
+}