100% JavaDoc coverage
git-svn-id: https://svn.apache.org/repos/asf/incubator/jsecurity/trunk@711113 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/src/org/jsecurity/authz/aop/AuthorizingAnnotationMethodInterceptor.java b/src/org/jsecurity/authz/aop/AuthorizingAnnotationMethodInterceptor.java
index 44bb25d..d8b9968 100644
--- a/src/org/jsecurity/authz/aop/AuthorizingAnnotationMethodInterceptor.java
+++ b/src/org/jsecurity/authz/aop/AuthorizingAnnotationMethodInterceptor.java
@@ -26,23 +26,45 @@
/**
* An <tt>AnnotationMethodInterceptor</tt> that asserts the calling code is authorized to execute the method
- * before allowing the invocation to continue.
- *
- * TODO - JavaDoc remaining methods.
+ * before allowing the invocation to continue by inspecting code annotations to perform an access control check.
*
* @author Les Hazlewood
* @since 0.1
*/
public abstract class AuthorizingAnnotationMethodInterceptor extends AnnotationMethodInterceptor {
+ /**
+ * Default constructor that merely calls {@link org.jsecurity.aop.AnnotationMethodInterceptor super(annotationClass)}
+ * @param annotationClass the specific annotatation class this interceptor will look for when performing an
+ * authorization check.
+ */
public AuthorizingAnnotationMethodInterceptor(Class<? extends Annotation> annotationClass) {
super(annotationClass);
}
+ /**
+ * Ensures the <code>methodInvocation</code> is allowed to execute first before proceeding by calling the
+ * {@link #assertAuthorized(org.jsecurity.aop.MethodInvocation) assertAuthorized} method first.
+ *
+ * @param methodInvocation the method invocation to check for authorization prior to allowing it to proceed/execute.
+ * @return the return value from the method invocation (the value of {@link org.jsecurity.aop.MethodInvocation#proceed() MethodInvocation.proceed()}).
+ * @throws AuthorizationException if the <code>MethodInvocation</code> is not allowed to proceed.
+ * @throws Throwable if any other error occurs.
+ */
public Object invoke(MethodInvocation methodInvocation) throws Throwable {
assertAuthorized(methodInvocation);
return methodInvocation.proceed();
}
+ /**
+ * Ensures the calling Subject is authorized to execute the specified <code>MethodInvocation</code>.
+ * <p/>
+ * As this is an AnnotationMethodInterceptor, the implementations of this method typically inspect the method to
+ * see if it has a specific Annotation, and if it does, performs an authorization check based on the information
+ * defined by the Annotation.
+ *
+ * @param mi the <code>MethodInvocation</code> to check to see if it is allowed to proceed/execute.
+ * @throws AuthorizationException if the method invocation is not allowed to continue/execute.
+ */
public abstract void assertAuthorized(MethodInvocation mi) throws AuthorizationException;
}
diff --git a/src/org/jsecurity/authz/aop/PermissionAnnotationMethodInterceptor.java b/src/org/jsecurity/authz/aop/PermissionAnnotationMethodInterceptor.java
index cb210db..07c696f 100644
--- a/src/org/jsecurity/authz/aop/PermissionAnnotationMethodInterceptor.java
+++ b/src/org/jsecurity/authz/aop/PermissionAnnotationMethodInterceptor.java
@@ -29,18 +29,33 @@
import java.util.Set;
/**
- * TODO - class and method JavaDoc
+ * Checks to see if a @{@link RequiresPermissions RequiresPermissions} annotation is declared, and if so, performs
+ * a permission check to see if the calling <code>Subject</code> is allowed to call the method.
* @author Les Hazlewood
* @since 0.9
*/
public class PermissionAnnotationMethodInterceptor extends AuthorizingAnnotationMethodInterceptor {
+ /**
+ * The character to look for that closes a permission definition.
+ */
private static final char ARRAY_CLOSE_CHAR = ']';
+ /**
+ * Default no-argument constructor that ensures this interceptor looks for
+ * @{@link RequiresPermissions RequiresPermissions} annotations in a method declaration.
+ */
public PermissionAnnotationMethodInterceptor() {
super(RequiresPermissions.class);
}
+ /**
+ * Infers the permission from the specified name path in the annotation.
+ * @param methodArgs the <code>MethodInvocation</code> method arguments.
+ * @param namePath the Annotation 'name' value, which is a string-based permission definition.
+ * @return the String permission representation.
+ * @throws Exception if there is an error infering the target.
+ */
protected String inferTargetFromPath(Object[] methodArgs, String namePath) throws Exception {
int propertyStartIndex = -1;
@@ -67,6 +82,11 @@
return targetValue.toString();
}
+ /**
+ * Returns the <code>MethodInvocation</code>'s arguments, or <code>null</code> if there were none.
+ * @param invocation the methodInvocation to inspect.
+ * @return the method invocation's method arguments, or <code>null</code> if there were none.
+ */
protected Object[] getMethodArguments(MethodInvocation invocation) {
if (invocation != null) {
return invocation.getArguments();
@@ -75,11 +95,25 @@
}
}
+ /**
+ * Returns the annotation {@link RequiresPermissions#value value}, from which the Permission will be constructed.
+ *
+ * @param invocation the method being invoked.
+ * @return the method annotation's <code>value</code>, from which the Permission will be constructed.
+ */
protected String getAnnotationValue(MethodInvocation invocation) {
RequiresPermissions prAnnotation = (RequiresPermissions) getAnnotation(invocation);
return prAnnotation.value();
}
+ /**
+ * Ensures that the calling <code>Subject</code> has the Annotation's specified permissions, and if not, throws an
+ * <code>AuthorizingException</code> indicating the method is not allowed to be executed.
+ *
+ * @param mi the method invocation to check for one or more permissions
+ * @throws AuthorizationException if the calling <code>Subject</code> does not have the permission(s) necessary to
+ * invoke the method.
+ */
public void assertAuthorized(MethodInvocation mi) throws AuthorizationException {
String p = getAnnotationValue(mi);
Set<String> perms = PermissionUtils.toPermissionStrings(p);
diff --git a/src/org/jsecurity/authz/aop/RoleAnnotationMethodInterceptor.java b/src/org/jsecurity/authz/aop/RoleAnnotationMethodInterceptor.java
index e7b4921..f0bd2c2 100644
--- a/src/org/jsecurity/authz/aop/RoleAnnotationMethodInterceptor.java
+++ b/src/org/jsecurity/authz/aop/RoleAnnotationMethodInterceptor.java
@@ -28,16 +28,30 @@
import java.util.Set;
/**
- * TODO - class and method JavaDoc
+ * Checks to see if a @{@link RequiresRoles RequiresRoles} annotation is declared, and if so, performs
+ * a role check to see if the calling <code>Subject</code> is allowed to invoke the method.
+ *
* @author Les Hazlewood
* @since 0.9
*/
public class RoleAnnotationMethodInterceptor extends AuthorizingAnnotationMethodInterceptor {
+ /**
+ * Default no-argument constructor that ensures this interceptor looks for
+ * @{@link RequiresRoles RequiresRoles} annotations in a method declaration.
+ */
public RoleAnnotationMethodInterceptor() {
super(RequiresRoles.class);
}
+ /**
+ * Ensures that the calling <code>Subject</code> has the Annotation's specified roles, and if not, throws an
+ * <code>AuthorizingException</code> indicating the method is not allowed to be executed.
+ *
+ * @param mi the method invocation to check for one or more roles
+ * @throws AuthorizationException if the calling <code>Subject</code> does not have the role(s) necessary to
+ * invoke the method.
+ */
public void assertAuthorized(MethodInvocation mi) throws AuthorizationException {
RequiresRoles rrAnnotation = (RequiresRoles) getAnnotation(mi);
