Use HttpSecurity Lambda DSL in JavaDoc

Issue gh-13067

Author: jzheaux

config/src/main/java/org/springframework/security/config/annotation/web/builders/HttpSecurity.java

@@ -103,6 +103,8 @@
 import org.springframework.web.filter.CorsFilter;
 import org.springframework.web.servlet.handler.HandlerMappingIntrospector;
 
+import static org.springframework.security.config.Customizer.withDefaults;
+
 /**
  * A {@link HttpSecurity} is similar to Spring Security's XML <http> element in the
  * namespace configuration. It allows configuring web based security for specific http
@@ -219,8 +221,8 @@ private ApplicationContext getContext() {
 	/**
 	 * Adds the Security headers to the response. This is activated by default when using
 	 * {@link EnableWebSecurity}. Accepting the default provided by
-	 * {@link EnableWebSecurity} or only invoking {@link #headers()} without invoking
-	 * additional methods on it, is the equivalent of:
+	 * {@link EnableWebSecurity} or only invoking {@link #headers(withDefaults())} without
+	 * invoking additional methods on it, is the equivalent of:
 	 *
 	 * <pre>
 	 * &#064;Configuration
@@ -266,8 +268,8 @@ private ApplicationContext getContext() {
 	 *
 	 * You can enable only a few of the headers by first invoking
 	 * {@link HeadersConfigurer#defaultsDisabled()} and then invoking the appropriate
-	 * methods on the {@link #headers()} result. For example, the following will enable
-	 * {@link HeadersConfigurer#cacheControl()} and
+	 * methods on the {@link #headers(withDefaults())} result. For example, the following
+	 * will enable {@link HeadersConfigurer#cacheControl()} and
 	 * {@link HeadersConfigurer#frameOptions()} only.
 	 *
 	 * <pre>
@@ -331,7 +333,8 @@ public HeadersConfigurer<HttpSecurity> headers() throws Exception {
 	 * <h2>Example Configurations</h2>
 	 *
 	 * Accepting the default provided by {@link EnableWebSecurity} or only invoking
-	 * {@link #headers()} without invoking additional methods on it, is the equivalent of:
+	 * {@link #headers(Customizer)} without invoking additional methods on it, is the
+	 * equivalent of:
 	 *
 	 * <pre>
 	 * &#064;Configuration
@@ -372,9 +375,9 @@ public HeadersConfigurer<HttpSecurity> headers() throws Exception {
 	 *
 	 * You can enable only a few of the headers by first invoking
 	 * {@link HeadersConfigurer#defaultsDisabled()} and then invoking the appropriate
-	 * methods on the {@link #headers()} result. For example, the following will enable
-	 * {@link HeadersConfigurer#cacheControl()} and
-	 * {@link HeadersConfigurer#frameOptions()} only.
+	 * methods on the {@link #headers(Customizer)} result. For example, the following will
+	 * enable {@link HeadersConfigurer#cacheControl(Customizer)} and
+	 * {@link HeadersConfigurer#frameOptions(Customizer)} only.
 	 *
 	 * <pre>
 	 * &#064;Configuration
@@ -397,7 +400,7 @@ public HeadersConfigurer<HttpSecurity> headers() throws Exception {
 	 *
 	 * You can also choose to keep the defaults but explicitly disable a subset of
 	 * headers. For example, the following will enable all the default headers except
-	 * {@link HeadersConfigurer#frameOptions()}.
+	 * {@link HeadersConfigurer#frameOptions(Customizer)}.
 	 *
 	 * <pre>
 	 * &#064;Configuration
@@ -615,9 +618,10 @@ public HttpSecurity sessionManagement(
 	 * {@link HttpSecurity#getSharedObject(Class)}. Other provided
 	 * {@link SecurityConfigurer} objects use this configured {@link PortMapper} as a
 	 * default {@link PortMapper} when redirecting from HTTP to HTTPS or from HTTPS to
-	 * HTTP (for example when used in combination with {@link #requiresChannel()}. By
-	 * default Spring Security uses a {@link PortMapperImpl} which maps the HTTP port 8080
-	 * to the HTTPS port 8443 and the HTTP port of 80 to the HTTPS port of 443.
+	 * HTTP (for example when used in combination with
+	 * {@link #requiresChannel(Customizer)} )}. By default Spring Security uses a
+	 * {@link PortMapperImpl} which maps the HTTP port 8080 to the HTTPS port 8443 and the
+	 * HTTP port of 80 to the HTTPS port of 443.
 	 *
 	 * <h2>Example Configuration</h2>
 	 *
@@ -657,7 +661,7 @@ public HttpSecurity sessionManagement(
 	 * <a href=
 	 * "https://docs.spring.io/spring-security/reference/migration-7/configuration.html#_use_the_lambda_dsl">documentation</a>
 	 * for more details.
-	 * @see #requiresChannel()
+	 * @see #requiresChannel(withDefaults())
 	 */
 	@Deprecated(since = "6.1", forRemoval = true)
 	public PortMapperConfigurer<HttpSecurity> portMapper() throws Exception {
@@ -669,9 +673,10 @@ public PortMapperConfigurer<HttpSecurity> portMapper() throws Exception {
 	 * {@link HttpSecurity#getSharedObject(Class)}. Other provided
 	 * {@link SecurityConfigurer} objects use this configured {@link PortMapper} as a
 	 * default {@link PortMapper} when redirecting from HTTP to HTTPS or from HTTPS to
-	 * HTTP (for example when used in combination with {@link #requiresChannel()}. By
-	 * default Spring Security uses a {@link PortMapperImpl} which maps the HTTP port 8080
-	 * to the HTTPS port 8443 and the HTTP port of 80 to the HTTPS port of 443.
+	 * HTTP (for example when used in combination with
+	 * {@link #requiresChannel(withDefaults())}. By default Spring Security uses a
+	 * {@link PortMapperImpl} which maps the HTTP port 8080 to the HTTPS port 8443 and the
+	 * HTTP port of 80 to the HTTPS port of 443.
 	 *
 	 * <h2>Example Configuration</h2>
 	 *
@@ -714,7 +719,7 @@ public PortMapperConfigurer<HttpSecurity> portMapper() throws Exception {
 	 * {@link PortMapperConfigurer}
 	 * @return the {@link HttpSecurity} for further customizations
 	 * @throws Exception
-	 * @see #requiresChannel()
+	 * @see #requiresChannel(Customizer)
 	 */
 	public HttpSecurity portMapper(Customizer<PortMapperConfigurer<HttpSecurity>> portMapperCustomizer)
 			throws Exception {
@@ -1776,7 +1781,7 @@ public HttpSecurity csrf(Customizer<CsrfConfigurer<HttpSecurity>> csrfCustomizer
 	 * Provides logout support. This is automatically applied when using
 	 * {@link EnableWebSecurity}. The default is that accessing the URL "/logout" will log
 	 * the user out by invalidating the HTTP Session, cleaning up any
-	 * {@link #rememberMe()} authentication that was configured, clearing the
+	 * {@link #rememberMe(Customizer)} authentication that was configured, clearing the
 	 * {@link SecurityContextHolder}, and then redirect to "/login?success".
 	 *
 	 * <h2>Example Custom Configuration</h2>
@@ -1827,8 +1832,8 @@ public LogoutConfigurer<HttpSecurity> logout() throws Exception {
 	 * Provides logout support. This is automatically applied when using
 	 * {@link EnableWebSecurity}. The default is that accessing the URL "/logout" will log
 	 * the user out by invalidating the HTTP Session, cleaning up any
-	 * {@link #rememberMe()} authentication that was configured, clearing the
-	 * {@link SecurityContextHolder}, and then redirect to "/login?success".
+	 * {@link #rememberMe(withDefaults())} authentication that was configured, clearing
+	 * the {@link SecurityContextHolder}, and then redirect to "/login?success".
 	 *
 	 * <h2>Example Custom Configuration</h2>
 	 *
@@ -2499,7 +2504,7 @@ public HttpSecurity saml2Logout(Customizer<Saml2LogoutConfigurer<HttpSecurity>>
 	 * {@link RelyingPartyRegistration}(s) are composed within a
 	 * {@link RelyingPartyRegistrationRepository}, which is <b>required</b> and must be
 	 * registered with the {@link ApplicationContext} or configured via
-	 * {@link #saml2Login()}.<br>
+	 * {@link #saml2Login(withDefaults())}.<br>
 	 * <br>
 	 *
 	 * The default configuration provides an auto-generated logout endpoint at

config/src/main/java/org/springframework/security/config/annotation/web/configuration/EnableWebSecurity.java

@@ -46,8 +46,9 @@
  *
  * 	@Bean
  * 	public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
- * 		http.authorizeHttpRequests().requestMatchers("/public/**").permitAll().anyRequest()
- * 				.hasRole("USER").and()
+ * 		http.authorizeHttpRequests((authorize) -> authorize
+ * 			.requestMatchers("/public/**").permitAll()
+ * 			.anyRequest().hasRole("USER"))
  * 				// Possibly more configuration ...
  * 				.formLogin() // enable form based log in
  * 				// set permitAll for all URLs associated with Form Login

config/src/main/java/org/springframework/security/config/annotation/web/configurers/AnonymousConfigurer.java

@@ -21,6 +21,7 @@
 
 import org.springframework.security.authentication.AnonymousAuthenticationProvider;
 import org.springframework.security.authentication.AuthenticationProvider;
+import org.springframework.security.config.Customizer;
 import org.springframework.security.config.annotation.SecurityConfigurer;
 import org.springframework.security.config.annotation.web.HttpSecurityBuilder;
 import org.springframework.security.config.annotation.web.builders.HttpSecurity;
@@ -57,7 +58,7 @@ public final class AnonymousConfigurer<H extends HttpSecurityBuilder<H>>
 
 	/**
 	 * Creates a new instance
-	 * @see HttpSecurity#anonymous()
+	 * @see HttpSecurity#anonymous(Customizer)
 	 */
 	public AnonymousConfigurer() {
 	}

config/src/main/java/org/springframework/security/config/annotation/web/configurers/ChannelSecurityConfigurer.java

@@ -43,6 +43,8 @@
 import org.springframework.security.web.access.intercept.DefaultFilterInvocationSecurityMetadataSource;
 import org.springframework.security.web.util.matcher.RequestMatcher;
 
+import static org.springframework.security.config.Customizer.withDefaults;
+
 /**
  * Adds channel security (i.e. requires HTTPS or HTTP) to an application. In order for
  * {@link ChannelSecurityConfigurer} to be useful, at least one {@link RequestMatcher}
@@ -96,7 +98,7 @@ public final class ChannelSecurityConfigurer<H extends HttpSecurityBuilder<H>>
 
 	/**
 	 * Creates a new instance
-	 * @see HttpSecurity#requiresChannel()
+	 * @see HttpSecurity#requiresChannel(Customizer)
 	 */
 	public ChannelSecurityConfigurer(ApplicationContext context) {
 		this.REGISTRY = new ChannelRequestMatcherRegistry(context);

config/src/main/java/org/springframework/security/config/annotation/web/configurers/CorsConfigurer.java

@@ -18,6 +18,7 @@
 
 import org.springframework.beans.factory.NoSuchBeanDefinitionException;
 import org.springframework.context.ApplicationContext;
+import org.springframework.security.config.Customizer;
 import org.springframework.security.config.annotation.web.HttpSecurityBuilder;
 import org.springframework.security.config.annotation.web.builders.HttpSecurity;
 import org.springframework.util.Assert;
@@ -57,7 +58,7 @@ public class CorsConfigurer<H extends HttpSecurityBuilder<H>> extends AbstractHt
 	/**
 	 * Creates a new instance
 	 *
-	 * @see HttpSecurity#cors()
+	 * @see HttpSecurity#cors(Customizer)
 	 */
 	public CorsConfigurer() {
 	}

config/src/main/java/org/springframework/security/config/annotation/web/configurers/CsrfConfigurer.java

@@ -27,6 +27,7 @@
 
 import org.springframework.context.ApplicationContext;
 import org.springframework.security.access.AccessDeniedException;
+import org.springframework.security.config.Customizer;
 import org.springframework.security.config.annotation.web.AbstractRequestMatcherRegistry;
 import org.springframework.security.config.annotation.web.HttpSecurityBuilder;
 import org.springframework.security.config.annotation.web.builders.HttpSecurity;
@@ -56,6 +57,8 @@
 import org.springframework.util.Assert;
 import org.springframework.util.StringUtils;
 
+import static org.springframework.security.config.Customizer.withDefaults;
+
 /**
  * Adds
  * <a href="https://www.owasp.org/index.php/Cross-Site_Request_Forgery_(CSRF)" >CSRF</a>
@@ -103,7 +106,7 @@ public final class CsrfConfigurer<H extends HttpSecurityBuilder<H>>
 
 	/**
 	 * Creates a new instance
-	 * @see HttpSecurity#csrf()
+	 * @see HttpSecurity#csrf(Customizer)
 	 */
 	public CsrfConfigurer(ApplicationContext context) {
 		this.context = context;
@@ -163,9 +166,8 @@ public CsrfConfigurer<H> csrfTokenRequestHandler(CsrfTokenRequestHandler request
 	 *
 	 * <pre>
 	 * http
-	 *     .csrf()
-	 *         .ignoringRequestMatchers((request) -&gt; "XMLHttpRequest".equals(request.getHeader("X-Requested-With")))
-	 *         .and()
+	 *     .csrf((csrf) -&gt; csrf
+	 *         .ignoringRequestMatchers((request) -&gt; "XMLHttpRequest".equals(request.getHeader("X-Requested-With"))))
 	 *     ...
 	 * </pre>
 	 *
@@ -191,9 +193,8 @@ public CsrfConfigurer<H> ignoringRequestMatchers(RequestMatcher... requestMatche
 	 *
 	 * <pre>
 	 * http
-	 *     .csrf()
-	 *         .ignoringRequestMatchers("/sockjs/**")
-	 *         .and()
+	 *     .csrf((csrf) -&gt; csrf
+	 *         .ignoringRequestMatchers("/sockjs/**"))
 	 *     ...
 	 * </pre>
 	 *

config/src/main/java/org/springframework/security/config/annotation/web/configurers/ExceptionHandlingConfigurer.java

@@ -18,6 +18,7 @@
 
 import java.util.LinkedHashMap;
 
+import org.springframework.security.config.Customizer;
 import org.springframework.security.config.annotation.web.HttpSecurityBuilder;
 import org.springframework.security.config.annotation.web.builders.HttpSecurity;
 import org.springframework.security.web.AuthenticationEntryPoint;
@@ -76,7 +77,7 @@ public final class ExceptionHandlingConfigurer<H extends HttpSecurityBuilder<H>>
 
 	/**
 	 * Creates a new instance
-	 * @see HttpSecurity#exceptionHandling()
+	 * @see HttpSecurity#exceptionHandling(Customizer)
 	 */
 	public ExceptionHandlingConfigurer() {
 	}

config/src/main/java/org/springframework/security/config/annotation/web/configurers/ExpressionUrlAuthorizationConfigurer.java

@@ -29,6 +29,7 @@
 import org.springframework.security.access.expression.SecurityExpressionHandler;
 import org.springframework.security.access.hierarchicalroles.RoleHierarchy;
 import org.springframework.security.authentication.AuthenticationTrustResolver;
+import org.springframework.security.config.Customizer;
 import org.springframework.security.config.ObjectPostProcessor;
 import org.springframework.security.config.annotation.web.HttpSecurityBuilder;
 import org.springframework.security.config.annotation.web.builders.HttpSecurity;
@@ -41,6 +42,8 @@
 import org.springframework.util.Assert;
 import org.springframework.util.StringUtils;
 
+import static org.springframework.security.config.Customizer.withDefaults;
+
 /**
  * Adds URL based authorization based upon SpEL expressions to an application. At least
  * one {@link org.springframework.web.bind.annotation.RequestMapping} needs to be mapped
@@ -77,7 +80,7 @@
  * @author Yanming Zhou
  * @author Ngoc Nhan
  * @since 3.2
- * @see org.springframework.security.config.annotation.web.builders.HttpSecurity#authorizeRequests()
+ * @see org.springframework.security.config.annotation.web.builders.HttpSecurity#authorizeRequests(Customizer)
  * @deprecated Use {@link AuthorizeHttpRequestsConfigurer} instead
  */
 @Deprecated
@@ -104,7 +107,7 @@ public final class ExpressionUrlAuthorizationConfigurer<H extends HttpSecurityBu
 
 	/**
 	 * Creates a new instance
-	 * @see HttpSecurity#authorizeRequests()
+	 * @see HttpSecurity#authorizeRequests(Customizer)
 	 */
 	public ExpressionUrlAuthorizationConfigurer(ApplicationContext context) {
 		GrantedAuthorityDefaults grantedAuthorityDefaults = context.getBeanProvider(GrantedAuthorityDefaults.class)

config/src/main/java/org/springframework/security/config/annotation/web/configurers/FormLoginConfigurer.java

@@ -17,6 +17,7 @@
 package org.springframework.security.config.annotation.web.configurers;
 
 import org.springframework.http.HttpMethod;
+import org.springframework.security.config.Customizer;
 import org.springframework.security.config.annotation.web.HttpSecurityBuilder;
 import org.springframework.security.config.annotation.web.RequestMatcherFactory;
 import org.springframework.security.config.annotation.web.builders.HttpSecurity;
@@ -74,7 +75,7 @@ public final class FormLoginConfigurer<H extends HttpSecurityBuilder<H>> extends
 
 	/**
 	 * Creates a new instance
-	 * @see HttpSecurity#formLogin()
+	 * @see HttpSecurity#formLogin(Customizer)
 	 */
 	public FormLoginConfigurer() {
 		super(new UsernamePasswordAuthenticationFilter(), null);

config/src/main/java/org/springframework/security/config/annotation/web/configurers/HeadersConfigurer.java

@@ -48,6 +48,8 @@
 import org.springframework.security.web.util.matcher.RequestMatcher;
 import org.springframework.util.Assert;
 
+import static org.springframework.security.config.Customizer.withDefaults;
+
 /**
  * <p>
  * Adds the Security HTTP headers to the response. Security HTTP headers is activated by
@@ -111,7 +113,7 @@ public class HeadersConfigurer<H extends HttpSecurityBuilder<H>>
 	/**
 	 * Creates a new instance
 	 *
-	 * @see HttpSecurity#headers()
+	 * @see HttpSecurity#headers(Customizer)
 	 */
 	public HeadersConfigurer() {
 	}