Polish Javadoc

Issue gh-9289

core/src/main/java/org/springframework/security/authorization/method/AfterMethodAuthorizationManager.java

@@ -38,7 +38,7 @@ import org.springframework.security.core.Authentication;
 public interface AfterMethodAuthorizationManager<T> {
 
 	/**
-	 * Determines if access should be granted for a specific authentication and
+	 * Determine if access should be granted for a specific authentication, object and
 	 * returnedObject.
 	 * @param authentication the {@link Supplier} of the {@link Authentication} to check
 	 * @param object the {@code T} object to check, typically a {@link MethodInvocation}
@@ -53,7 +53,8 @@ public interface AfterMethodAuthorizationManager<T> {
 	}
 
 	/**
-	 * Determines if access is granted for a specific authentication and returnedObject.
+	 * Determine if access is granted for a specific authentication, object, and
+	 * returnedObject.
 	 * @param authentication the {@link Supplier} of the {@link Authentication} to check
 	 * @param object the {@code T} object to check, typically a {@link MethodInvocation}
 	 * @param returnedObject the returned object from the method invocation to check

core/src/main/java/org/springframework/security/authorization/method/AuthorizationManagerMethodAfterAdvice.java

@@ -55,11 +55,10 @@ public final class AuthorizationManagerMethodAfterAdvice<T> implements Authoriza
 	}
 
 	/**
-	 * Determines if an {@link Authentication} has access to the {@link T} object using
+	 * Determine if an {@link Authentication} has access to the {@link T} object using the
-	 * the {@link AuthorizationManager}.
+	 * {@link AuthorizationManager}.
 	 * @param authentication the {@link Supplier} of the {@link Authentication} to check
-	 * @param object the {@link T} object to check - note that {@code T} should contain
+	 * @param object the {@link T} object to check
-	 * the returned object
 	 * @throws AccessDeniedException if access is not granted
 	 */
 	@Override

core/src/main/java/org/springframework/security/authorization/method/AuthorizationManagerMethodBeforeAdvice.java

@@ -54,8 +54,8 @@ public final class AuthorizationManagerMethodBeforeAdvice<T> implements Authoriz
 	}
 
 	/**
-	 * Determines if an {@link Authentication} has access to the {@link T} object using
+	 * Determine if an {@link Authentication} has access to the {@link T} object using the
-	 * the {@link AuthorizationManager}.
+	 * configured {@link AuthorizationManager}.
 	 * @param authentication the {@link Supplier} of the {@link Authentication} to check
 	 * @param object the {@link T} object to check
 	 * @throws AccessDeniedException if access is not granted

core/src/main/java/org/springframework/security/authorization/method/AuthorizationMethodAfterAdvice.java

@@ -55,16 +55,15 @@ public interface AuthorizationMethodAfterAdvice<T> extends AfterAdvice, Pointcut
 	}
 
 	/**
-	 * Determines if an {@link Authentication} has access to the returned object from the
+	 * Determine if an {@link Authentication} has access to a method invocation's return
-	 * {@link MethodInvocation}.
+	 * object.
 	 * @param authentication the {@link Supplier} of the {@link Authentication} to check
 	 * @param object the {@link T} object to check
-	 * @param returnedObject the returned object from the {@link MethodInvocation} to
+	 * @param returnedObject the returned object from the method invocation to check
-	 * check
+	 * @return the {@code Object} that will ultimately be returned to the caller (if an
-	 * @return the <code>Object</code> that will ultimately be returned to the caller (if
+	 * implementation does not wish to modify the object to be returned to the caller, the
-	 * an implementation does not wish to modify the object to be returned to the caller,
+	 * implementation should simply return the same object it was passed by the
-	 * the implementation should simply return the same object it was passed by the
+	 * {@code returnedObject} method argument)
-	 * <code>returnedObject</code> method argument)
 	 */
 	Object after(Supplier<Authentication> authentication, T object, Object returnedObject);
 

core/src/main/java/org/springframework/security/authorization/method/AuthorizationMethodBeforeAdvice.java

@@ -53,7 +53,7 @@ public interface AuthorizationMethodBeforeAdvice<T> extends BeforeAdvice, Pointc
 	}
 
 	/**
-	 * Determines if an {@link Authentication} has access to the {@link T} object.
+	 * Determine if an {@link Authentication} has access to the {@link T} object.
 	 * @param authentication the {@link Supplier} of the {@link Authentication} to check
 	 * @param object the {@link T} object to check
 	 */

core/src/main/java/org/springframework/security/authorization/method/AuthorizationMethodInterceptor.java

@@ -49,9 +49,10 @@ public final class AuthorizationMethodInterceptor implements MethodInterceptor {
 	}
 
 	/**
-	 * This method should be used to enforce security on a {@link MethodInvocation}.
+	 * Enforce security on this {@link MethodInvocation}.
 	 * @param mi the method being invoked which requires a security decision
-	 * @return the returned value from the {@link MethodInvocation}
+	 * @return the returned value from the {@link MethodInvocation}, possibly altered by
+	 * the configured {@link AuthorizationMethodAfterAdvice}
 	 */
 	@Override
 	public Object invoke(@NonNull MethodInvocation mi) throws Throwable {

core/src/main/java/org/springframework/security/authorization/method/DelegatingAuthorizationMethodAfterAdvice.java

@@ -74,14 +74,18 @@ public final class DelegatingAuthorizationMethodAfterAdvice<T> implements Author
 	}
 
 	/**
-	 * Delegates to specific {@link AuthorizationMethodAfterAdvice}s and returns the
+	 * Delegate to a series of {@link AuthorizationMethodAfterAdvice}s, each of which may
-	 * <code>returnedObject</code> (possibly modified) from the method argument.
+	 * replace the {@code returnedObject} with its own
+	 *
+	 * Advices may be of type {@link AuthorizationManagerMethodAfterAdvice} in which case,
+	 * they will throw an
+	 * {@link org.springframework.security.access.AccessDeniedException} in the event that
+	 * they deny access to the {@code returnedObject}.
 	 * @param authentication the {@link Supplier} of the {@link Authentication} to check
 	 * @param object the {@link MethodAuthorizationContext} to check
-	 * @param returnedObject the returned object from the {@link MethodInvocation} to
+	 * @param returnedObject the returned object from the original method invocation
-	 * check
+	 * @throws org.springframework.security.access.AccessDeniedException if any delegate
-	 * @return the <code>returnedObject</code> (possibly modified) from the method
+	 * advices deny access
-	 * argument
 	 */
 	@Override
 	public Object after(Supplier<Authentication> authentication, T object, Object returnedObject) {

core/src/main/java/org/springframework/security/authorization/method/DelegatingAuthorizationMethodBeforeAdvice.java

@@ -74,11 +74,16 @@ public final class DelegatingAuthorizationMethodBeforeAdvice<T> implements Autho
 	}
 
 	/**
-	 * Delegates to a specific {@link AuthorizationMethodBeforeAdvice} and grants access
+	 * Delegate to a series of {@link AuthorizationMethodBeforeAdvice}s
-	 * if all {@link AuthorizationMethodBeforeAdvice}s granted or abstained. Denies only
+	 *
-	 * if one of the {@link AuthorizationMethodBeforeAdvice}s denied.
+	 * Advices may be of type {@link AuthorizationManagerMethodBeforeAdvice} in which
+	 * case, they will throw an
+	 * {@link org.springframework.security.access.AccessDeniedException} in the event that
+	 * they deny access.
 	 * @param authentication the {@link Supplier} of the {@link Authentication} to check
 	 * @param object the {@link MethodAuthorizationContext} to check
+	 * @throws org.springframework.security.access.AccessDeniedException if any delegate
+	 * advices deny access
 	 */
 	@Override
 	public void before(Supplier<Authentication> authentication, T object) {

core/src/main/java/org/springframework/security/authorization/method/Jsr250AuthorizationManager.java

@@ -70,9 +70,9 @@ public final class Jsr250AuthorizationManager implements AuthorizationManager<Me
 	}
 
 	/**
-	 * Determines if an {@link Authentication} has access to the {@link MethodInvocation}
+	 * Determine if an {@link Authentication} has access to a method by evaluating the
-	 * by evaluating if the {@link Authentication} contains a specified authority from the
+	 * {@link DenyAll}, {@link PermitAll}, and {@link RolesAllowed} annotations that
-	 * JSR-250 security annotations.
+	 * {@link MethodAuthorizationContext} specifies.
 	 * @param authentication the {@link Supplier} of the {@link Authentication} to check
 	 * @param methodAuthorizationContext the {@link MethodAuthorizationContext} to check
 	 * @return an {@link AuthorizationDecision} or null if the JSR-250 security

core/src/main/java/org/springframework/security/authorization/method/MethodAuthorizationContext.java

@@ -19,8 +19,8 @@ package org.springframework.security.authorization.method;
 import org.aopalliance.intercept.MethodInvocation;
 
 /**
- * An authorization context which is holds the {@link MethodInvocation}, the target class
+ * An authorization context which is holds the {@link MethodInvocation} and the target
- * and the returned object.
+ * class
  *
  * @author Evgeniy Cheban
  * @since 5.5
@@ -42,16 +42,16 @@ public final class MethodAuthorizationContext {
 	}
 
 	/**
-	 * Returns the {@link MethodInvocation}.
+	 * Return the {@link MethodInvocation}.
-	 * @return the {@link MethodInvocation} to use
+	 * @return the {@link MethodInvocation}
 	 */
 	public MethodInvocation getMethodInvocation() {
 		return this.methodInvocation;
 	}
 
 	/**
-	 * Returns the target class.
+	 * Return the target class.
-	 * @return the target class to use
+	 * @return the target class
 	 */
 	public Class<?> getTargetClass() {
 		return this.targetClass;

core/src/main/java/org/springframework/security/authorization/method/PostAuthorizeAuthorizationManager.java

@@ -60,12 +60,14 @@ public final class PostAuthorizeAuthorizationManager
 	}
 
 	/**
-	 * Determines if an {@link Authentication} has access to the {@link MethodInvocation}
+	 * Determine if an {@link Authentication} has access to the returned object by
-	 * by evaluating an expression from the {@link PostAuthorize} annotation.
+	 * evaluating the {@link PostAuthorize} annotation that the
+	 * {@link MethodAuthorizationContext} specifies.
 	 * @param authentication the {@link Supplier} of the {@link Authentication} to check
 	 * @param methodAuthorizationContext the {@link MethodAuthorizationContext} to check
-	 * @return an {@link AuthorizationDecision} or null if the {@link PostAuthorize}
+	 * @param returnedObject the returned object to check
-	 * annotation is not present
+	 * @return an {@link AuthorizationDecision} or {@code null} if the
+	 * {@link PostAuthorize} annotation is not present
 	 */
 	@Override
 	public AuthorizationDecision check(Supplier<Authentication> authentication,

core/src/main/java/org/springframework/security/authorization/method/PostFilterAuthorizationMethodAfterAdvice.java

@@ -78,12 +78,12 @@ public final class PostFilterAuthorizationMethodAfterAdvice
 	}
 
 	/**
-	 * Filters a <code>returnedObject</code> from the {@link MethodInvocation} by
+	 * Filter a {@code returnedObject} using the {@link PostFilter} annotation that the
-	 * evaluating an expression from the {@link PostFilter} annotation.
+	 * {@link MethodAuthorizationContext} specifies.
 	 * @param authentication the {@link Supplier} of the {@link Authentication} to check
 	 * @param methodAuthorizationContext the {@link MethodAuthorizationContext} to check
 	 * check
-	 * @return filtered <code>returnedObject</code> from the {@link MethodInvocation}
+	 * @return filtered {@code returnedObject}
 	 */
 	@Override
 	public Object after(Supplier<Authentication> authentication, MethodAuthorizationContext methodAuthorizationContext,

core/src/main/java/org/springframework/security/authorization/method/PreAuthorizeAuthorizationManager.java

@@ -59,12 +59,13 @@ public final class PreAuthorizeAuthorizationManager implements AuthorizationMana
 	}
 
 	/**
-	 * Determines if an {@link Authentication} has access to the {@link MethodInvocation}
+	 * Determine if an {@link Authentication} has access to a method by evaluating an
-	 * by evaluating an expression from the {@link PreAuthorize} annotation.
+	 * expression from the {@link PreAuthorize} annotation that the
+	 * {@link MethodAuthorizationContext} specifies.
 	 * @param authentication the {@link Supplier} of the {@link Authentication} to check
 	 * @param methodAuthorizationContext the {@link MethodAuthorizationContext} to check
-	 * @return an {@link AuthorizationDecision} or null if the {@link PreAuthorize}
+	 * @return an {@link AuthorizationDecision} or {@code null} if the
-	 * annotation is not present
+	 * {@link PreAuthorize} annotation is not present
 	 */
 	@Override
 	public AuthorizationDecision check(Supplier<Authentication> authentication,

core/src/main/java/org/springframework/security/authorization/method/PreFilterAuthorizationMethodBeforeAdvice.java

@@ -52,7 +52,7 @@ public final class PreFilterAuthorizationMethodBeforeAdvice
 	private MethodSecurityExpressionHandler expressionHandler = new DefaultMethodSecurityExpressionHandler();
 
 	/**
-	 * Create a {@link PreFilterAuthorizationMethodBeforeAdvice} using the provided
+	 * Creates a {@link PreFilterAuthorizationMethodBeforeAdvice} using the provided
 	 * parameters
 	 * @param pointcut the {@link Pointcut} for when this advice applies
 	 */
@@ -61,7 +61,7 @@ public final class PreFilterAuthorizationMethodBeforeAdvice
 	}
 
 	/**
-	 * Sets the {@link MethodSecurityExpressionHandler}.
+	 * Use this {@link MethodSecurityExpressionHandler}
 	 * @param expressionHandler the {@link MethodSecurityExpressionHandler} to use
 	 */
 	public void setExpressionHandler(MethodSecurityExpressionHandler expressionHandler) {
@@ -78,8 +78,8 @@ public final class PreFilterAuthorizationMethodBeforeAdvice
 	}
 
 	/**
-	 * Filters a method argument by evaluating an expression from the {@link PreFilter}
+	 * Filter the method argument specified in the {@link PreFilter} annotation that
-	 * annotation.
+	 * {@link MethodAuthorizationContext} specifies.
 	 * @param authentication the {@link Supplier} of the {@link Authentication} to check
 	 * @param methodAuthorizationContext the {@link MethodAuthorizationContext} to check
 	 */

core/src/main/java/org/springframework/security/authorization/method/SecuredAuthorizationManager.java

@@ -43,9 +43,8 @@ public final class SecuredAuthorizationManager implements AuthorizationManager<M
 	private final SecuredAuthorizationManagerRegistry registry = new SecuredAuthorizationManagerRegistry();
 
 	/**
-	 * Determines if an {@link Authentication} has access to the {@link MethodInvocation}
+	 * Determine if an {@link Authentication} has access to a method by evaluating the
-	 * by evaluating if the {@link Authentication} contains a specified authority from the
+	 * {@link Secured} annotation that {@link MethodAuthorizationContext} specifies.
-	 * Spring Security's {@link Secured} annotation.
 	 * @param authentication the {@link Supplier} of the {@link Authentication} to check
 	 * @param methodAuthorizationContext the {@link MethodAuthorizationContext} to check
 	 * @return an {@link AuthorizationDecision} or null if the {@link Secured} annotation