From 6bcf4796598221c91beb4ed910e2a48b88e42a2b Mon Sep 17 00:00:00 2001 From: Josh Cummings Date: Thu, 8 Apr 2021 12:00:07 -0600 Subject: [PATCH] Polish Javadoc Issue gh-9289 --- .../method/AfterMethodAuthorizationManager.java | 5 +++-- .../AuthorizationManagerMethodAfterAdvice.java | 7 +++---- .../AuthorizationManagerMethodBeforeAdvice.java | 4 ++-- .../method/AuthorizationMethodAfterAdvice.java | 15 +++++++-------- .../method/AuthorizationMethodBeforeAdvice.java | 2 +- .../method/AuthorizationMethodInterceptor.java | 5 +++-- ...DelegatingAuthorizationMethodAfterAdvice.java | 16 ++++++++++------ ...elegatingAuthorizationMethodBeforeAdvice.java | 11 ++++++++--- .../method/Jsr250AuthorizationManager.java | 6 +++--- .../method/MethodAuthorizationContext.java | 12 ++++++------ .../PostAuthorizeAuthorizationManager.java | 10 ++++++---- ...PostFilterAuthorizationMethodAfterAdvice.java | 6 +++--- .../method/PreAuthorizeAuthorizationManager.java | 9 +++++---- ...PreFilterAuthorizationMethodBeforeAdvice.java | 8 ++++---- .../method/SecuredAuthorizationManager.java | 5 ++--- 15 files changed, 66 insertions(+), 55 deletions(-) diff --git a/core/src/main/java/org/springframework/security/authorization/method/AfterMethodAuthorizationManager.java b/core/src/main/java/org/springframework/security/authorization/method/AfterMethodAuthorizationManager.java index 420c635ba1..435f05c91f 100644 --- a/core/src/main/java/org/springframework/security/authorization/method/AfterMethodAuthorizationManager.java +++ b/core/src/main/java/org/springframework/security/authorization/method/AfterMethodAuthorizationManager.java @@ -38,7 +38,7 @@ import org.springframework.security.core.Authentication; public interface AfterMethodAuthorizationManager { /** - * 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 { } /** - * 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 diff --git a/core/src/main/java/org/springframework/security/authorization/method/AuthorizationManagerMethodAfterAdvice.java b/core/src/main/java/org/springframework/security/authorization/method/AuthorizationManagerMethodAfterAdvice.java index 5442d49d15..ae347cbcc1 100644 --- a/core/src/main/java/org/springframework/security/authorization/method/AuthorizationManagerMethodAfterAdvice.java +++ b/core/src/main/java/org/springframework/security/authorization/method/AuthorizationManagerMethodAfterAdvice.java @@ -55,11 +55,10 @@ public final class AuthorizationManagerMethodAfterAdvice implements Authoriza } /** - * 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 diff --git a/core/src/main/java/org/springframework/security/authorization/method/AuthorizationManagerMethodBeforeAdvice.java b/core/src/main/java/org/springframework/security/authorization/method/AuthorizationManagerMethodBeforeAdvice.java index e0c485b8c6..d63bea9d22 100644 --- a/core/src/main/java/org/springframework/security/authorization/method/AuthorizationManagerMethodBeforeAdvice.java +++ b/core/src/main/java/org/springframework/security/authorization/method/AuthorizationManagerMethodBeforeAdvice.java @@ -54,8 +54,8 @@ public final class AuthorizationManagerMethodBeforeAdvice implements Authoriz } /** - * 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 diff --git a/core/src/main/java/org/springframework/security/authorization/method/AuthorizationMethodAfterAdvice.java b/core/src/main/java/org/springframework/security/authorization/method/AuthorizationMethodAfterAdvice.java index f059bdef84..1f360cefcd 100644 --- a/core/src/main/java/org/springframework/security/authorization/method/AuthorizationMethodAfterAdvice.java +++ b/core/src/main/java/org/springframework/security/authorization/method/AuthorizationMethodAfterAdvice.java @@ -55,16 +55,15 @@ public interface AuthorizationMethodAfterAdvice extends AfterAdvice, Pointcut } /** - * 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 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 - * returnedObject 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, T object, Object returnedObject); diff --git a/core/src/main/java/org/springframework/security/authorization/method/AuthorizationMethodBeforeAdvice.java b/core/src/main/java/org/springframework/security/authorization/method/AuthorizationMethodBeforeAdvice.java index 47b62c3a57..4b1caee6d6 100644 --- a/core/src/main/java/org/springframework/security/authorization/method/AuthorizationMethodBeforeAdvice.java +++ b/core/src/main/java/org/springframework/security/authorization/method/AuthorizationMethodBeforeAdvice.java @@ -53,7 +53,7 @@ public interface AuthorizationMethodBeforeAdvice 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 */ diff --git a/core/src/main/java/org/springframework/security/authorization/method/AuthorizationMethodInterceptor.java b/core/src/main/java/org/springframework/security/authorization/method/AuthorizationMethodInterceptor.java index 961d4a1705..4b411b3222 100644 --- a/core/src/main/java/org/springframework/security/authorization/method/AuthorizationMethodInterceptor.java +++ b/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 { diff --git a/core/src/main/java/org/springframework/security/authorization/method/DelegatingAuthorizationMethodAfterAdvice.java b/core/src/main/java/org/springframework/security/authorization/method/DelegatingAuthorizationMethodAfterAdvice.java index cf978c9bca..62acbc1657 100644 --- a/core/src/main/java/org/springframework/security/authorization/method/DelegatingAuthorizationMethodAfterAdvice.java +++ b/core/src/main/java/org/springframework/security/authorization/method/DelegatingAuthorizationMethodAfterAdvice.java @@ -74,14 +74,18 @@ public final class DelegatingAuthorizationMethodAfterAdvice implements Author } /** - * Delegates to specific {@link AuthorizationMethodAfterAdvice}s and returns the - * returnedObject (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 returnedObject (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, T object, Object returnedObject) { diff --git a/core/src/main/java/org/springframework/security/authorization/method/DelegatingAuthorizationMethodBeforeAdvice.java b/core/src/main/java/org/springframework/security/authorization/method/DelegatingAuthorizationMethodBeforeAdvice.java index 395047defa..df8705aaa4 100644 --- a/core/src/main/java/org/springframework/security/authorization/method/DelegatingAuthorizationMethodBeforeAdvice.java +++ b/core/src/main/java/org/springframework/security/authorization/method/DelegatingAuthorizationMethodBeforeAdvice.java @@ -74,11 +74,16 @@ public final class DelegatingAuthorizationMethodBeforeAdvice implements Autho } /** - * 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, T object) { diff --git a/core/src/main/java/org/springframework/security/authorization/method/Jsr250AuthorizationManager.java b/core/src/main/java/org/springframework/security/authorization/method/Jsr250AuthorizationManager.java index a878b71ca1..06cc404a18 100644 --- a/core/src/main/java/org/springframework/security/authorization/method/Jsr250AuthorizationManager.java +++ b/core/src/main/java/org/springframework/security/authorization/method/Jsr250AuthorizationManager.java @@ -70,9 +70,9 @@ public final class Jsr250AuthorizationManager implements AuthorizationManager getTargetClass() { return this.targetClass; diff --git a/core/src/main/java/org/springframework/security/authorization/method/PostAuthorizeAuthorizationManager.java b/core/src/main/java/org/springframework/security/authorization/method/PostAuthorizeAuthorizationManager.java index 57449b6e1c..7fddfa900d 100644 --- a/core/src/main/java/org/springframework/security/authorization/method/PostAuthorizeAuthorizationManager.java +++ b/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} - * by evaluating an expression from the {@link PostAuthorize} annotation. + * Determine if an {@link Authentication} has access to the returned object by + * 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} - * annotation is not present + * @param returnedObject the returned object to check + * @return an {@link AuthorizationDecision} or {@code null} if the + * {@link PostAuthorize} annotation is not present */ @Override public AuthorizationDecision check(Supplier authentication, diff --git a/core/src/main/java/org/springframework/security/authorization/method/PostFilterAuthorizationMethodAfterAdvice.java b/core/src/main/java/org/springframework/security/authorization/method/PostFilterAuthorizationMethodAfterAdvice.java index 0844da6763..e21c1172da 100644 --- a/core/src/main/java/org/springframework/security/authorization/method/PostFilterAuthorizationMethodAfterAdvice.java +++ b/core/src/main/java/org/springframework/security/authorization/method/PostFilterAuthorizationMethodAfterAdvice.java @@ -78,12 +78,12 @@ public final class PostFilterAuthorizationMethodAfterAdvice } /** - * Filters a returnedObject from the {@link MethodInvocation} by - * evaluating an expression from the {@link PostFilter} annotation. + * Filter a {@code returnedObject} using the {@link PostFilter} annotation that the + * {@link MethodAuthorizationContext} specifies. * @param authentication the {@link Supplier} of the {@link Authentication} to check * @param methodAuthorizationContext the {@link MethodAuthorizationContext} to check * check - * @return filtered returnedObject from the {@link MethodInvocation} + * @return filtered {@code returnedObject} */ @Override public Object after(Supplier authentication, MethodAuthorizationContext methodAuthorizationContext, diff --git a/core/src/main/java/org/springframework/security/authorization/method/PreAuthorizeAuthorizationManager.java b/core/src/main/java/org/springframework/security/authorization/method/PreAuthorizeAuthorizationManager.java index 9a876d7ab0..70d3f44853 100644 --- a/core/src/main/java/org/springframework/security/authorization/method/PreAuthorizeAuthorizationManager.java +++ b/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} - * by evaluating an expression from the {@link PreAuthorize} annotation. + * Determine if an {@link Authentication} has access to a method by evaluating an + * 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} - * annotation is not present + * @return an {@link AuthorizationDecision} or {@code null} if the + * {@link PreAuthorize} annotation is not present */ @Override public AuthorizationDecision check(Supplier authentication, diff --git a/core/src/main/java/org/springframework/security/authorization/method/PreFilterAuthorizationMethodBeforeAdvice.java b/core/src/main/java/org/springframework/security/authorization/method/PreFilterAuthorizationMethodBeforeAdvice.java index 9f266f8576..306bd78d5b 100644 --- a/core/src/main/java/org/springframework/security/authorization/method/PreFilterAuthorizationMethodBeforeAdvice.java +++ b/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} - * annotation. + * Filter the method argument specified in the {@link PreFilter} annotation that + * {@link MethodAuthorizationContext} specifies. * @param authentication the {@link Supplier} of the {@link Authentication} to check * @param methodAuthorizationContext the {@link MethodAuthorizationContext} to check */ diff --git a/core/src/main/java/org/springframework/security/authorization/method/SecuredAuthorizationManager.java b/core/src/main/java/org/springframework/security/authorization/method/SecuredAuthorizationManager.java index d74ad1155b..400912e7be 100644 --- a/core/src/main/java/org/springframework/security/authorization/method/SecuredAuthorizationManager.java +++ b/core/src/main/java/org/springframework/security/authorization/method/SecuredAuthorizationManager.java @@ -43,9 +43,8 @@ public final class SecuredAuthorizationManager implements AuthorizationManager