Fix Javadoc Errors

Closes gh-9530
2025-03-01 10:59:16 +00:00 · 2021-03-30 11:37:42 -06:00 · 2021-03-30 11:37:42 -06:00 · 404e9e153a
commit 404e9e153a
parent d948528b7b
9 changed files with 41 additions and 40 deletions
--- a/saml2/saml2-service-provider/core/src/main/java/org/springframework/security/saml2/core/OpenSamlInitializationService.java
+++ b/saml2/saml2-service-provider/core/src/main/java/org/springframework/security/saml2/core/OpenSamlInitializationService.java
@ -52,7 +52,7 @@ import org.springframework.security.saml2.Saml2Exception;
 *
 * <pre>
 * 	static {
- *  	OpenSamlInitializationService.requireInitialize((registry) -> {
+ *  	OpenSamlInitializationService.requireInitialize((registry) -&gt; {
 *  	 	registry.setParserPool(...);
 *  		registry.getBuilderFactory().registerBuilder(...);
 *  	});
--- a/saml2/saml2-service-provider/core/src/main/java/org/springframework/security/saml2/core/Saml2X509Credential.java
+++ b/saml2/saml2-service-provider/core/src/main/java/org/springframework/security/saml2/core/Saml2X509Credential.java
@ -85,6 +85,7 @@ public final class Saml2X509Credential {
 	/**
 	 * Create a {@link Saml2X509Credential} that can be used for encryption.
 	 * @param certificate the certificate to use for encryption
+	 * @return an encrypting {@link Saml2X509Credential}
 	 */
 	public static Saml2X509Credential encryption(X509Certificate certificate) {
 		return new Saml2X509Credential(certificate, Saml2X509Credential.Saml2X509CredentialType.ENCRYPTION);
@ -93,6 +94,7 @@ public final class Saml2X509Credential {
 	/**
 	 * Create a {@link Saml2X509Credential} that can be used for verification.
 	 * @param certificate the certificate to use for verification
+	 * @return a verifying {@link Saml2X509Credential}
 	 */
 	public static Saml2X509Credential verification(X509Certificate certificate) {
 		return new Saml2X509Credential(certificate, Saml2X509Credential.Saml2X509CredentialType.VERIFICATION);
@ -102,6 +104,7 @@ public final class Saml2X509Credential {
 	 * Create a {@link Saml2X509Credential} that can be used for decryption.
 	 * @param privateKey the private key to use for decryption
 	 * @param certificate the certificate to use for decryption
+	 * @return an decrypting {@link Saml2X509Credential}
 	 */
 	public static Saml2X509Credential decryption(PrivateKey privateKey, X509Certificate certificate) {
 		return new Saml2X509Credential(privateKey, certificate, Saml2X509Credential.Saml2X509CredentialType.DECRYPTION);
@ -111,6 +114,7 @@ public final class Saml2X509Credential {
 	 * Create a {@link Saml2X509Credential} that can be used for signing.
 	 * @param privateKey the private key to use for signing
 	 * @param certificate the certificate to use for signing
+	 * @return a signing {@link Saml2X509Credential}
 	 */
 	public static Saml2X509Credential signing(PrivateKey privateKey, X509Certificate certificate) {
 		return new Saml2X509Credential(privateKey, certificate, Saml2X509Credential.Saml2X509CredentialType.SIGNING);
--- a/saml2/saml2-service-provider/core/src/main/java/org/springframework/security/saml2/provider/service/authentication/Saml2AuthenticationRequest.java
+++ b/saml2/saml2-service-provider/core/src/main/java/org/springframework/security/saml2/provider/service/authentication/Saml2AuthenticationRequest.java
@ -100,7 +100,8 @@ public final class Saml2AuthenticationRequest {
 	}

 	/**
-	 * A builder for {@link Saml2AuthenticationRequest}. returns a builder object
+	 * A builder for {@link Saml2AuthenticationRequest}.
+	 * @return a {@link Builder} for constructing a {@link Saml2AuthenticationRequest}
 	 */
 	public static Builder builder() {
 		return new Builder();
@ -109,6 +110,7 @@ public final class Saml2AuthenticationRequest {
 	/**
 	 * A builder for {@link Saml2AuthenticationRequest}.
 	 * @param context a context object to copy values from. returns a builder object
+	 * @return a {@link Builder} for constructing a {@link Saml2AuthenticationRequest}
 	 */
 	public static Builder withAuthenticationRequestContext(Saml2AuthenticationRequestContext context) {
 		return new Builder().assertionConsumerServiceUrl(context.getAssertionConsumerServiceUrl())
@ -148,7 +150,7 @@ public final class Saml2AuthenticationRequest {
 		 * request. For example: <code>
 		 *     Saml2X509Credential credential = ...;
 		 *     return Saml2AuthenticationRequest.withLocalSpEntityId("id")
-		 *             .credentials((c) -> c.add(credential))
+		 *             .credentials((c) -&gt; c.add(credential))
 		 *             ...
 		 *             .build();
 		 * </code>
--- a/saml2/saml2-service-provider/core/src/main/java/org/springframework/security/saml2/provider/service/registration/RelyingPartyRegistration.java
+++ b/saml2/saml2-service-provider/core/src/main/java/org/springframework/security/saml2/provider/service/registration/RelyingPartyRegistration.java
@ -59,11 +59,11 @@ import org.springframework.util.Assert;
 *	RelyingPartyRegistration rp = RelyingPartyRegistration.withRegistrationId(registrationId)
 * 			.entityId(relyingPartyEntityId)
 * 			.assertionConsumerServiceLocation(assertingConsumerServiceLocation)
- * 		 	.signingX509Credentials((c) -> c.add(relyingPartySigningCredential))
- * 			.assertingPartyDetails((details) -> details
+ * 		 	.signingX509Credentials((c) -&gt; c.add(relyingPartySigningCredential))
+ * 			.assertingPartyDetails((details) -&gt; details
 * 				.entityId(assertingPartyEntityId));
 * 				.singleSignOnServiceLocation(singleSignOnServiceLocation))
- * 				.verifyingX509Credentials((c) -> c.add(assertingPartyVerificationCredential))
+ * 				.verifyingX509Credentials((c) -&gt; c.add(assertingPartyVerificationCredential))
 * 			.build();
 * </pre>
 *
@ -857,6 +857,7 @@ public final class RelyingPartyRegistration {
 		 * This value may contain a number of placeholders. They are {@code baseUrl},
 		 * {@code registrationId}, {@code baseScheme}, {@code baseHost}, and
 		 * {@code basePort}.
+		 * @param entityId the relying party's EntityID
 		 * @return the {@link Builder} for further configuration
 		 * @since 5.4
 		 */
@ -906,7 +907,7 @@ public final class RelyingPartyRegistration {
 		 * This value may contain a number of placeholders. They are {@code baseUrl},
 		 * {@code registrationId}, {@code baseScheme}, {@code baseHost}, and
 		 * {@code basePort}.
-		 * @param assertionConsumerServiceLocation
+		 * @param assertionConsumerServiceLocation the AssertionConsumerService location
 		 * @return the {@link Builder} for further configuration
 		 * @since 5.4
 		 */
@ -923,7 +924,7 @@ public final class RelyingPartyRegistration {
 		 * <p>
 		 * Equivalent to the value found in &lt;AssertionConsumerService
 		 * Binding="..."/&gt; in the relying party's &lt;SPSSODescriptor&gt;
-		 * @param assertionConsumerServiceBinding
+		 * @param assertionConsumerServiceBinding the AssertionConsumerService binding
 		 * @return the {@link Builder} for further configuration
 		 * @since 5.4
 		 */
@ -948,7 +949,7 @@ public final class RelyingPartyRegistration {
 		 * communication between IDP and SP For example: <code>
 		 *     Saml2X509Credential credential = ...;
 		 *     return RelyingPartyRegistration.withRegistrationId("id")
-		 *             .credentials((c) -> c.add(credential))
+		 *             .credentials((c) -&gt; c.add(credential))
 		 *             ...
 		 *             .build();
 		 * </code>
@ -1018,6 +1019,7 @@ public final class RelyingPartyRegistration {
 		 * {@code registrationId}, {@code baseScheme}, {@code baseHost}, and
 		 * {@code basePort}, for example
 		 * {@code {baseUrl}/saml2/service-provider-metadata/{registrationId}}
+		 * @param template the entity id
 		 * @return a string containing the entity ID or entity ID template
 		 * @deprecated Use {@link #entityId} instead
 		 */
--- a/saml2/saml2-service-provider/core/src/main/java/org/springframework/security/saml2/provider/service/servlet/filter/Saml2WebSsoAuthenticationRequestFilter.java
+++ b/saml2/saml2-service-provider/core/src/main/java/org/springframework/security/saml2/provider/service/servlet/filter/Saml2WebSsoAuthenticationRequestFilter.java
@ -113,6 +113,8 @@ public class Saml2WebSsoAuthenticationRequestFilter extends OncePerRequestFilter
 	 * parameters
 	 * @param authenticationRequestContextResolver a strategy for formulating a
 	 * {@link Saml2AuthenticationRequestContext}
+	 * @param authenticationRequestFactory strategy for formulating a
+	 * &lt;saml2:AuthnRequest&gt;
 	 * @since 5.4
 	 */
 	public Saml2WebSsoAuthenticationRequestFilter(
--- a/saml2/saml2-service-provider/core/src/main/java/org/springframework/security/saml2/provider/service/web/Saml2MetadataFilter.java
+++ b/saml2/saml2-service-provider/core/src/main/java/org/springframework/security/saml2/provider/service/web/Saml2MetadataFilter.java
@ -95,7 +95,7 @@ public final class Saml2MetadataFilter extends OncePerRequestFilter {
 	/**
 	 * Set the {@link RequestMatcher} that determines whether this filter should handle
 	 * the incoming {@link HttpServletRequest}
-	 * @param requestMatcher
+	 * @param requestMatcher the {@link RequestMatcher} to identify requests for metadata
 	 */
 	public void setRequestMatcher(RequestMatcher requestMatcher) {
 		Assert.notNull(requestMatcher, "requestMatcher cannot be null");
@ -106,7 +106,7 @@ public final class Saml2MetadataFilter extends OncePerRequestFilter {
 	 * Sets the metadata filename template containing the {@code {registrationId}}
 	 * template variable.
 	 *
-	 * <br />
+	 * <p>
 	 * The default value is {@code saml-{registrationId}-metadata.xml}
 	 * @param metadataFilename metadata filename, must contain a {registrationId}
 	 * @since 5.5
--- a/saml2/saml2-service-provider/opensaml3/src/main/java/org/springframework/security/saml2/provider/service/authentication/OpenSamlAuthenticationProvider.java
+++ b/saml2/saml2-service-provider/opensaml3/src/main/java/org/springframework/security/saml2/provider/service/authentication/OpenSamlAuthenticationProvider.java
@ -103,18 +103,15 @@ import org.springframework.util.StringUtils;
 * {@link Saml2AuthenticationToken#getSaml2Response()} along with the information about
 * the asserting party, the identity provider (IDP), as well as the relying party, the
 * service provider (SP, this application).
- * </p>
 * <p>
 * The {@link Saml2AuthenticationToken} will be processed into a SAML Response object. The
 * SAML response object can be signed. If the Response is signed, a signature will not be
 * required on the assertion.
- * </p>
 * <p>
 * While a response object can contain a list of assertion, this provider will only
 * leverage the first valid assertion for the purpose of authentication. Assertions that
 * do not pass validation will be ignored. If no valid assertions are found a
 * {@link Saml2AuthenticationException} is thrown.
- * </p>
 * <p>
 * This provider supports two types of encrypted SAML elements
 * <ul>
@ -125,11 +122,9 @@ import org.springframework.util.StringUtils;
 * </ul>
 * If the assertion is encrypted, then signature validation on the assertion is no longer
 * required.
- * </p>
 * <p>
 * This provider does not perform an X509 certificate validation on the configured
 * asserting party, IDP, verification certificates.
- * </p>
 *
 * @author Ryan Cassar
 * @since 5.2
@ -138,7 +133,7 @@ import org.springframework.util.StringUtils;
 * StatusResponse</a>
 * @see <a href="https://wiki.shibboleth.net/confluence/display/OS30/Home">OpenSAML 3</a>
 * @deprecated Because OpenSAML 3 has reached End-of-Life, please update to
- * {@link OpenSaml4AuthenticationProvider}
+ * {@code OpenSaml4AuthenticationProvider}
 */
 public final class OpenSamlAuthenticationProvider implements AuthenticationProvider {

@ -195,7 +190,7 @@ public final class OpenSamlAuthenticationProvider implements AuthenticationProvi
 	 *
 	 * <pre>
 	 *	OpenSamlAuthenticationProvider provider = new OpenSamlAuthenticationProvider();
-	 *	provider.setResponseElementsDecrypter((responseToken) -> {
+	 *	provider.setResponseElementsDecrypter((responseToken) -&gt; {
 	 *	    DecrypterParameters parameters = new DecrypterParameters();
 	 *	    // ... set parameters as needed
 	 *	    Decrypter decrypter = new Decrypter(parameters);
@ -216,7 +211,7 @@ public final class OpenSamlAuthenticationProvider implements AuthenticationProvi
 	 * <pre>
 	 *	OpenSamlAuthenticationProvider provider = new OpenSamlAuthenticationProvider();
 	 *	Converter&lt;EncryptedAssertion, Assertion&gt; myService = ...
-	 *	provider.setResponseDecrypter((responseToken) -> {
+	 *	provider.setResponseDecrypter((responseToken) -&gt; {
 	 *	   Response response = responseToken.getResponse();
 	 *	   response.getEncryptedAssertions().stream()
 	 *	   		.map(service::decrypt).forEach(response.getAssertions()::add);
@ -242,7 +237,7 @@ public final class OpenSamlAuthenticationProvider implements AuthenticationProvi
 	 *
 	 * <pre>
 	 *	OpenSamlAuthenticationProvider provider = new OpenSamlAuthenticationProvider();
-	 *  provider.setAssertionValidator(assertionToken -> {
+	 *  provider.setAssertionValidator(assertionToken -&gt; {
 	 *		Saml2ResponseValidatorResult result = createDefaultAssertionValidator()
 	 *			.convert(assertionToken)
 	 *		return result.concat(myCustomValidator.convert(assertionToken));
@ -255,7 +250,7 @@ public final class OpenSamlAuthenticationProvider implements AuthenticationProvi
 	 * <pre>
 	 *	OpenSamlAuthenticationProvider provider = new OpenSamlAuthenticationProvider();
 	 *	provider.setAssertionValidator(
-	 *		createDefaultAssertionValidator(assertionToken -> {
+	 *		createDefaultAssertionValidator(assertionToken -&gt; {
 	 *			Map&lt;String, Object&gt; params = new HashMap&lt;&gt;();
 	 *			params.put(CLOCK_SKEW, 2 * 60 * 1000);
 	 *			// other parameters
@ -271,7 +266,7 @@ public final class OpenSamlAuthenticationProvider implements AuthenticationProvi
 	 * step from this validator.
 	 *
 	 * This method takes precedence over {@link #setResponseTimeValidationSkew}.
-	 * @param assertionValidator
+	 * @param assertionValidator the strategy for validating a given assertion
 	 * @since 5.4
 	 */
 	public void setAssertionValidator(Converter<AssertionToken, Saml2ResponseValidatorResult> assertionValidator) {
@ -287,7 +282,7 @@ public final class OpenSamlAuthenticationProvider implements AuthenticationProvi
 	 *
 	 * <pre>
 	 *	OpenSamlAuthenticationProvider provider = new OpenSamlAuthenticationProvider();
-	 *	provider.setResponseDecrypter((assertionToken) -> {
+	 *	provider.setResponseDecrypter((assertionToken) -&gt; {
 	 *	    DecrypterParameters parameters = new DecrypterParameters();
 	 *	    // ... set parameters as needed
 	 *	    Decrypter decrypter = new Decrypter(parameters);
@ -307,7 +302,7 @@ public final class OpenSamlAuthenticationProvider implements AuthenticationProvi
 	 * <pre>
 	 *	OpenSamlAuthenticationProvider provider = new OpenSamlAuthenticationProvider();
 	 *	MyDecryptionService myService = ...
-	 *	provider.setResponseDecrypter((responseToken) -> {
+	 *	provider.setResponseDecrypter((responseToken) -&gt; {
 	 *	   	Assertion assertion = assertionToken.getAssertion();
 	 *	   	EncryptedID encrypted = assertion.getSubject().getEncryptedID();
 	 *		NameID name = myService.decrypt(encrypted);
@ -333,7 +328,7 @@ public final class OpenSamlAuthenticationProvider implements AuthenticationProvi
 	 *	OpenSamlAuthenticationProvider provider = new OpenSamlAuthenticationProvider();
 	 * 	Converter&lt;ResponseToken, Saml2Authentication&gt; authenticationConverter =
 	 * 			createDefaultResponseAuthenticationConverter();
-	 *	provider.setResponseAuthenticationConverter(responseToken -> {
+	 *	provider.setResponseAuthenticationConverter(responseToken -&gt; {
 	 *		Saml2Authentication authentication = authenticationConverter.convert(responseToken);
 	 *		User user = myUserRepository.findByUsername(authentication.getName());
 	 *		return new MyAuthentication(authentication, user);
--- a/saml2/saml2-service-provider/opensaml3/src/main/java/org/springframework/security/saml2/provider/service/authentication/OpenSamlAuthenticationRequestFactory.java
+++ b/saml2/saml2-service-provider/opensaml3/src/main/java/org/springframework/security/saml2/provider/service/authentication/OpenSamlAuthenticationRequestFactory.java
@ -47,7 +47,7 @@ import org.springframework.util.StringUtils;
 * @author Josh Cummings
 * @since 5.2
 * @deprecated Because OpenSAML 3 has reached End-of-Life, please update to
- * {@link OpenSaml4AuthenticationRequestFactory}
+ * {@code OpenSaml4AuthenticationRequestFactory}
 */
 public class OpenSamlAuthenticationRequestFactory implements Saml2AuthenticationRequestFactory {

@ -162,7 +162,8 @@ public class OpenSamlAuthenticationRequestFactory implements Saml2Authentication

 	/**
 	 * Set the {@link AuthnRequest} post-processor resolver
-	 * @param authenticationRequestContextConverter
+	 * @param authenticationRequestContextConverter a strategy for creating an
+	 * {@link AuthnRequest}
 	 * @since 5.4
 	 */
 	public void setAuthenticationRequestContextConverter(
@ -173,7 +174,7 @@ public class OpenSamlAuthenticationRequestFactory implements Saml2Authentication

 	/**
 	 * ' Use this {@link Clock} with {@link Instant#now()} for generating timestamps
-	 * @param clock
+	 * @param clock the {@link Clock} to use
 	 */
 	public void setClock(Clock clock) {
 		Assert.notNull(clock, "clock cannot be null");
--- a/saml2/saml2-service-provider/opensaml4/src/main/java/org/springframework/security/saml2/provider/service/authentication/OpenSaml4AuthenticationProvider.java
+++ b/saml2/saml2-service-provider/opensaml4/src/main/java/org/springframework/security/saml2/provider/service/authentication/OpenSaml4AuthenticationProvider.java
@ -98,18 +98,15 @@ import org.springframework.util.StringUtils;
 * {@link Saml2AuthenticationToken#getSaml2Response()} along with the information about
 * the asserting party, the identity provider (IDP), as well as the relying party, the
 * service provider (SP, this application).
- * </p>
 * <p>
 * The {@link Saml2AuthenticationToken} will be processed into a SAML Response object. The
 * SAML response object can be signed. If the Response is signed, a signature will not be
 * required on the assertion.
- * </p>
 * <p>
 * While a response object can contain a list of assertion, this provider will only
 * leverage the first valid assertion for the purpose of authentication. Assertions that
 * do not pass validation will be ignored. If no valid assertions are found a
 * {@link Saml2AuthenticationException} is thrown.
- * </p>
 * <p>
 * This provider supports two types of encrypted SAML elements
 * <ul>
@ -120,11 +117,9 @@ import org.springframework.util.StringUtils;
 * </ul>
 * If the assertion is encrypted, then signature validation on the assertion is no longer
 * required.
- * </p>
 * <p>
 * This provider does not perform an X509 certificate validation on the configured
 * asserting party, IDP, verification certificates.
- * </p>
 *
 * @author Josh Cummings
 * @since 5.5
@ -179,7 +174,7 @@ public final class OpenSaml4AuthenticationProvider implements AuthenticationProv
 	 *
 	 * <pre>
 	 *	OpenSamlAuthenticationProvider provider = new OpenSamlAuthenticationProvider();
-	 *	provider.setResponseElementsDecrypter((responseToken) -> {
+	 *	provider.setResponseElementsDecrypter((responseToken) -&gt; {
 	 *	    DecrypterParameters parameters = new DecrypterParameters();
 	 *	    // ... set parameters as needed
 	 *	    Decrypter decrypter = new Decrypter(parameters);
@ -200,7 +195,7 @@ public final class OpenSaml4AuthenticationProvider implements AuthenticationProv
 	 * <pre>
 	 *	OpenSamlAuthenticationProvider provider = new OpenSamlAuthenticationProvider();
 	 *	Converter&lt;EncryptedAssertion, Assertion&gt; myService = ...
-	 *	provider.setResponseDecrypter((responseToken) -> {
+	 *	provider.setResponseDecrypter((responseToken) -&gt; {
 	 *	   Response response = responseToken.getResponse();
 	 *	   response.getEncryptedAssertions().stream()
 	 *	   		.map(service::decrypt).forEach(response.getAssertions()::add);
@ -226,7 +221,7 @@ public final class OpenSaml4AuthenticationProvider implements AuthenticationProv
 	 *
 	 * <pre>
 	 *	OpenSamlAuthenticationProvider provider = new OpenSamlAuthenticationProvider();
-	 *  provider.setAssertionValidator(assertionToken -> {
+	 *  provider.setAssertionValidator(assertionToken -&gt; {
 	 *		Saml2ResponseValidatorResult result = createDefaultAssertionValidator()
 	 *			.convert(assertionToken)
 	 *		return result.concat(myCustomValidator.convert(assertionToken));
@ -239,7 +234,7 @@ public final class OpenSaml4AuthenticationProvider implements AuthenticationProv
 	 * <pre>
 	 *	OpenSamlAuthenticationProvider provider = new OpenSamlAuthenticationProvider();
 	 *	provider.setAssertionValidator(
-	 *		createDefaultAssertionValidator(assertionToken -> {
+	 *		createDefaultAssertionValidator(assertionToken -&gt; {
 	 *			Map&lt;String, Object&gt; params = new HashMap&lt;&gt;();
 	 *			params.put(CLOCK_SKEW, 2 * 60 * 1000);
 	 *			// other parameters
@ -269,7 +264,7 @@ public final class OpenSaml4AuthenticationProvider implements AuthenticationProv
 	 *
 	 * <pre>
 	 *	OpenSamlAuthenticationProvider provider = new OpenSamlAuthenticationProvider();
-	 *	provider.setResponseDecrypter((assertionToken) -> {
+	 *	provider.setResponseDecrypter((assertionToken) -&gt; {
 	 *	    DecrypterParameters parameters = new DecrypterParameters();
 	 *	    // ... set parameters as needed
 	 *	    Decrypter decrypter = new Decrypter(parameters);
@ -289,7 +284,7 @@ public final class OpenSaml4AuthenticationProvider implements AuthenticationProv
 	 * <pre>
 	 *	OpenSamlAuthenticationProvider provider = new OpenSamlAuthenticationProvider();
 	 *	MyDecryptionService myService = ...
-	 *	provider.setResponseDecrypter((responseToken) -> {
+	 *	provider.setResponseDecrypter((responseToken) -&gt; {
 	 *	   	Assertion assertion = assertionToken.getAssertion();
 	 *	   	EncryptedID encrypted = assertion.getSubject().getEncryptedID();
 	 *		NameID name = myService.decrypt(encrypted);
@ -315,7 +310,7 @@ public final class OpenSaml4AuthenticationProvider implements AuthenticationProv
 	 *	OpenSamlAuthenticationProvider provider = new OpenSamlAuthenticationProvider();
 	 * 	Converter&lt;ResponseToken, Saml2Authentication&gt; authenticationConverter =
 	 * 			createDefaultResponseAuthenticationConverter();
-	 *	provider.setResponseAuthenticationConverter(responseToken -> {
+	 *	provider.setResponseAuthenticationConverter(responseToken -&gt; {
 	 *		Saml2Authentication authentication = authenticationConverter.convert(responseToken);
 	 *		User user = myUserRepository.findByUsername(authentication.getName());
 	 *		return new MyAuthentication(authentication, user);