Polish Javadoc

Issue gh-9289

Author: jzheaux

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

@@ -38,7 +38,7 @@
 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 @@ default void verify(Supplier<Authentication> authentication, T object, Object re
 	}
 
 	/**
-	 * 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 AuthorizationManagerMethodAfterAdvice(Pointcut pointcut,
 	}
 
 	/**
-	 * Determines if an {@link Authentication} has access to the {@link T} object using
-	 * the {@link AuthorizationManager}.
+	 * Determine if an {@link Authentication} has access to the {@link T} object using the
+	 * {@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
-	 * the returned object
+	 * @param object the {@link T} object to check
 	 * @throws AccessDeniedException if access is not granted
 	 */
 	@Override

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

@@ -54,8 +54,8 @@ public AuthorizationManagerMethodBeforeAdvice(Pointcut pointcut, AuthorizationMa
 	}
 
 	/**
-	 * Determines if an {@link Authentication} has access to the {@link T} object using
-	 * the {@link AuthorizationManager}.
+	 * Determine if an {@link Authentication} has access to the {@link T} object using the
+	 * 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 @@ default Advice getAdvice() {
 	}
 
 	/**
-	 * Determines if an {@link Authentication} has access to the returned object from the
-	 * {@link MethodInvocation}.
+	 * Determine if an {@link Authentication} has access to a method invocation's return
+	 * 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
-	 * check
-	 * @return the <code>Object</code> that will ultimately be returned to the caller (if
-	 * an implementation does not wish to modify the object to be returned to the caller,
-	 * the implementation should simply return the same object it was passed by the
-	 * <code>returnedObject</code> method argument)
+	 * @param returnedObject the returned object from the method invocation to check
+	 * @return the {@code Object} that will ultimately be returned to the caller (if an
+	 * implementation does not wish to modify the object to be returned to the caller, the
+	 * implementation should simply return the same object it was passed by the
+	 * {@code returnedObject} 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 @@ default Advice getAdvice() {
 	}
 
 	/**
-	 * 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 AuthorizationMethodInterceptor(AuthorizationMethodBeforeAdvice<MethodAuth
 	}
 
 	/**
-	 * 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 Pointcut getPointcut() {
 	}
 
 	/**
-	 * Delegates to specific {@link AuthorizationMethodAfterAdvice}s and returns the
-	 * <code>returnedObject</code> (possibly modified) from the method argument.
+	 * Delegate to a series of {@link AuthorizationMethodAfterAdvice}s, each of which may
+	 * 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
-	 * check
-	 * @return the <code>returnedObject</code> (possibly modified) from the method
-	 * argument
+	 * @param returnedObject the returned object from the original method invocation
+	 * @throws org.springframework.security.access.AccessDeniedException if any delegate
+	 * advices deny access
 	 */
 	@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 Pointcut getPointcut() {
 	}
 
 	/**
-	 * Delegates to a specific {@link AuthorizationMethodBeforeAdvice} and grants access
-	 * if all {@link AuthorizationMethodBeforeAdvice}s granted or abstained. Denies only
-	 * if one of the {@link AuthorizationMethodBeforeAdvice}s denied.
+	 * Delegate to a series of {@link AuthorizationMethodBeforeAdvice}s
+	 *
+	 * 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 void setRolePrefix(String rolePrefix) {
 	}
 
 	/**
-	 * Determines if an {@link Authentication} has access to the {@link MethodInvocation}
-	 * by evaluating if the {@link Authentication} contains a specified authority from the
-	 * JSR-250 security annotations.
+	 * Determine if an {@link Authentication} has access to a method by evaluating the
+	 * {@link DenyAll}, {@link PermitAll}, and {@link RolesAllowed} annotations that
+	 * {@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 @@
 import org.aopalliance.intercept.MethodInvocation;
 
 /**
- * An authorization context which is holds the {@link MethodInvocation}, the target class
- * and the returned object.
+ * An authorization context which is holds the {@link MethodInvocation} and the target
+ * class
  *
  * @author Evgeniy Cheban
  * @since 5.5
@@ -42,16 +42,16 @@ public MethodAuthorizationContext(MethodInvocation methodInvocation, Class<?> ta
 	}
 
 	/**
-	 * Returns the {@link MethodInvocation}.
-	 * @return the {@link MethodInvocation} to use
+	 * Return the {@link MethodInvocation}.
+	 * @return the {@link MethodInvocation}
 	 */
 	public MethodInvocation getMethodInvocation() {
 		return this.methodInvocation;
 	}
 
 	/**
-	 * Returns the target class.
-	 * @return the target class to use
+	 * Return the target class.
+	 * @return the target class
 	 */
 	public Class<?> getTargetClass() {
 		return this.targetClass;