javadoc
git-svn-id: https://svn.apache.org/repos/asf/incubator/jsecurity/trunk@711093 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/src/org/jsecurity/aop/AnnotationMethodInterceptor.java b/src/org/jsecurity/aop/AnnotationMethodInterceptor.java
index a3b2faa..1fea165 100644
--- a/src/org/jsecurity/aop/AnnotationMethodInterceptor.java
+++ b/src/org/jsecurity/aop/AnnotationMethodInterceptor.java
@@ -30,13 +30,29 @@
*/
public abstract class AnnotationMethodInterceptor extends MethodInterceptorSupport {
+ /**
+ * The type of annotation this interceptor will inspect on methods at runtime.
+ */
protected Class<? extends Annotation> annotationClass;
- public AnnotationMethodInterceptor( Class<? extends Annotation> annotationClass ) {
+ /**
+ * Constructs an <code>AnnotationMethodInterceptor</code> who processes annotations of the
+ * specified type. Immediately calls {@link #setAnnotationClass(Class)}.
+ *
+ * @param annotationClass the type of annotation this interceptor will process.
+ */
+ public AnnotationMethodInterceptor(Class<? extends Annotation> annotationClass) {
setAnnotationClass(annotationClass);
}
- protected void setAnnotationClass(Class<? extends Annotation> annotationClass) {
+ /**
+ * Sets the type of annotation this interceptor will inspect on methods at runtime.
+ *
+ * @param annotationClass the type of annotation this interceptor will process.
+ * @throws IllegalArgumentException if the argument is <code>null</code>.
+ */
+ protected void setAnnotationClass(Class<? extends Annotation> annotationClass)
+ throws IllegalArgumentException {
if (annotationClass == null) {
String msg = "annotationClass argument cannot be null";
throw new IllegalArgumentException(msg);
@@ -44,15 +60,45 @@
this.annotationClass = annotationClass;
}
+ /**
+ * Returns the type of annotation this interceptor inspects on methods at runtime.
+ *
+ * @return the type of annotation this interceptor inspects on methods at runtime.
+ */
public Class<? extends Annotation> getAnnotationClass() {
return this.annotationClass;
}
+ /**
+ * Returns <code>true</code> if this interceptor supports, that is, should inspect, the specified
+ * <code>MethodInvocation</code>, <code>false</code> otherwise.
+ * <p/>
+ * The default implementation simply does the following:
+ * <p/>
+ * <code>return {@link #getAnnotation(MethodInvocation) getAnnotation(mi)} != null</code>
+ *
+ * @param mi the <code>MethodInvocation</code> for the method being invoked.
+ * @return <code>true</code> if this interceptor supports, that is, should inspect, the specified
+ * <code>MethodInvocation</code>, <code>false</code> otherwise.
+ */
public boolean supports(MethodInvocation mi) {
return getAnnotation(mi) != null;
}
- protected Annotation getAnnotation(MethodInvocation mi) {
+ /**
+ * Returns the Annotation that this interceptor will process for the specified method invocation.
+ * <p/>
+ * The default implementation merely gets the underlying {@link Method Method} from the supplied
+ * <code>MethodInvocation</code> argument, and returns:
+ * <p/>
+ * <code>mi.{@link Method#getAnnotation(Class) getAnnotation}({@link #getAnnotationClass() getAnnotationClass()});</code>
+ *
+ * @param mi the MethodInvocation wrapping the Method from which the Annotation will be acquired.
+ * @return the Annotation that this interceptor will process for the specified method invocation.
+ * @throws IllegalArgumentException if the supplied <code>MethodInvocation</code> argument is <code>null</code> or
+ * its underlying <code>Method</code> is <code>null</code>.
+ */
+ protected Annotation getAnnotation(MethodInvocation mi) throws IllegalArgumentException {
if (mi == null) {
throw new IllegalArgumentException("method argument cannot be null");
}
@@ -64,7 +110,6 @@
}
return m.getAnnotation(getAnnotationClass());
-
}
}
diff --git a/src/org/jsecurity/aop/MethodInterceptor.java b/src/org/jsecurity/aop/MethodInterceptor.java
index 6ece18b..4325b97 100644
--- a/src/org/jsecurity/aop/MethodInterceptor.java
+++ b/src/org/jsecurity/aop/MethodInterceptor.java
@@ -29,6 +29,14 @@
*/
public interface MethodInterceptor {
+ /**
+ * Invokes the specified <code>MethodInvocation</code>, allowing implementations to perform pre/post/finally
+ * surrounding the actual invocation.
+ *
+ * @param methodInvocation the <code>MethodInvocation</code> to execute.
+ * @return the result of the invocation
+ * @throws Throwable if the method invocation throws a Throwable or if an error occurs in pre/post/finally advice.
+ */
Object invoke(MethodInvocation methodInvocation) throws Throwable;
}
diff --git a/src/org/jsecurity/aop/MethodInterceptorSupport.java b/src/org/jsecurity/aop/MethodInterceptorSupport.java
index 553433c..f1ddc03 100644
--- a/src/org/jsecurity/aop/MethodInterceptorSupport.java
+++ b/src/org/jsecurity/aop/MethodInterceptorSupport.java
@@ -18,8 +18,6 @@
*/
package org.jsecurity.aop;
-import org.apache.commons.logging.Log;
-import org.apache.commons.logging.LogFactory;
import org.jsecurity.SecurityUtils;
import org.jsecurity.subject.Subject;
@@ -33,11 +31,19 @@
*/
public abstract class MethodInterceptorSupport implements MethodInterceptor {
- private static final Log log = LogFactory.getLog(MethodInterceptorSupport.class);
-
+ /**
+ * Default no-argument constructor for subclasses.
+ */
public MethodInterceptorSupport() {
}
+ /**
+ * Returns the {@link Subject Subject} associated with the currently-executing code.
+ * <p/>
+ * This default implementation merely calls <code>{@link SecurityUtils#getSubject SecurityUtils.getSubject()}</code>.
+ *
+ * @return the {@link Subject Subject} associated with the currently-executing code.
+ */
protected Subject getSubject() {
return SecurityUtils.getSubject();
}
diff --git a/src/org/jsecurity/aop/MethodInvocation.java b/src/org/jsecurity/aop/MethodInvocation.java
index 33c7d92..9efad09 100644
--- a/src/org/jsecurity/aop/MethodInvocation.java
+++ b/src/org/jsecurity/aop/MethodInvocation.java
@@ -39,16 +39,16 @@
Object proceed() throws Throwable;
/**
- * The method that is being invoked.
+ * Returns the actual {@link Method Method} to be invoked.
*
- * @return a {@link Method} object representing the invoked method.
+ * @return the actual {@link Method Method} to be invoked.
*/
Method getMethod();
/**
- * The arguments given to the method invocation.
+ * Returns the (possibly null) arguments to be supplied to the method invocation.
*
- * @return the arguments passed to the method invocation.
+ * @return the (possibly null) arguments to be supplied to the method invocation.
*/
Object[] getArguments();
diff --git a/src/org/jsecurity/authc/credential/Md2CredentialsMatcher.java b/src/org/jsecurity/authc/credential/Md2CredentialsMatcher.java
index 613faeb..f12f629 100644
--- a/src/org/jsecurity/authc/credential/Md2CredentialsMatcher.java
+++ b/src/org/jsecurity/authc/credential/Md2CredentialsMatcher.java
@@ -37,10 +37,19 @@
*/
public class Md2CredentialsMatcher extends HashedCredentialsMatcher {
+ /**
+ * Creates a new <em>uninitialized</em> {@link Md2Hash Md2Hash} instance, without it's byte array set.
+ *
+ * @return a new <em>uninitialized</em> {@link Md2Hash Md2Hash} instance, without it's byte array set.
+ */
protected AbstractHash newHashInstance() {
return new Md2Hash();
}
+ /**
+ * This implementation merely returns
+ * <code>new {@link Md2Hash#Md2Hash(Object, Object, int) Md2Hash(credentials,salt,hashIterations)}</code>.
+ */
protected Hash hashProvidedCredentials(Object credentials, Object salt, int hashIterations) {
return new Md2Hash(credentials, salt, hashIterations);
}
diff --git a/src/org/jsecurity/authc/credential/Md5CredentialsMatcher.java b/src/org/jsecurity/authc/credential/Md5CredentialsMatcher.java
index 33c235e..bc2fdb2 100644
--- a/src/org/jsecurity/authc/credential/Md5CredentialsMatcher.java
+++ b/src/org/jsecurity/authc/credential/Md5CredentialsMatcher.java
@@ -37,10 +37,19 @@
*/
public class Md5CredentialsMatcher extends HashedCredentialsMatcher {
+ /**
+ * Creates a new <em>uninitialized</em> {@link Md5Hash Md5Hash} instance, without it's byte array set.
+ *
+ * @return a new <em>uninitialized</em> {@link Md5Hash Md5Hash} instance, without it's byte array set.
+ */
protected AbstractHash newHashInstance() {
return new Md5Hash();
}
+ /**
+ * This implementation merely returns
+ * <code>new {@link Md5Hash#Md5Hash(Object, Object, int) Md5Hash(credentials,salt,hashIterations)}</code>.
+ */
protected Hash hashProvidedCredentials(Object credentials, Object salt, int hashIterations) {
return new Md5Hash(credentials, salt, hashIterations);
}
diff --git a/src/org/jsecurity/authc/credential/Sha1CredentialsMatcher.java b/src/org/jsecurity/authc/credential/Sha1CredentialsMatcher.java
index 207fc9c..d7c7b84 100644
--- a/src/org/jsecurity/authc/credential/Sha1CredentialsMatcher.java
+++ b/src/org/jsecurity/authc/credential/Sha1CredentialsMatcher.java
@@ -37,10 +37,19 @@
*/
public class Sha1CredentialsMatcher extends HashedCredentialsMatcher {
+ /**
+ * Creates a new <em>uninitialized</em> {@link Sha1Hash Sha1Hash} instance, without it's byte array set.
+ *
+ * @return a new <em>uninitialized</em> {@link Sha1Hash Sha1Hash} instance, without it's byte array set.
+ */
protected AbstractHash newHashInstance() {
return new Sha1Hash();
}
+ /**
+ * This implementation merely returns
+ * <code>new {@link Sha1Hash#Sha1Hash(Object, Object, int) Sha1Hash(credentials,salt,hashIterations)}</code>.
+ */
protected Hash hashProvidedCredentials(Object credentials, Object salt, int hashIterations) {
return new Sha1Hash(credentials, salt, hashIterations);
}
diff --git a/src/org/jsecurity/authc/credential/Sha256CredentialsMatcher.java b/src/org/jsecurity/authc/credential/Sha256CredentialsMatcher.java
index 2123f44..4cb1df8 100644
--- a/src/org/jsecurity/authc/credential/Sha256CredentialsMatcher.java
+++ b/src/org/jsecurity/authc/credential/Sha256CredentialsMatcher.java
@@ -31,10 +31,19 @@
*/
public class Sha256CredentialsMatcher extends HashedCredentialsMatcher {
+ /**
+ * Creates a new <em>uninitialized</em> {@link Sha256Hash Sha256Hash} instance, without it's byte array set.
+ *
+ * @return a new <em>uninitialized</em> {@link Sha256Hash Sha256Hash} instance, without it's byte array set.
+ */
protected AbstractHash newHashInstance() {
return new Sha256Hash();
}
+ /**
+ * This implementation merely returns
+ * <code>new {@link Sha256Hash#Sha256Hash(Object, Object, int) Sha256Hash(credentials,salt,hashIterations)}</code>.
+ */
protected Hash hashProvidedCredentials(Object credentials, Object salt, int hashIterations) {
return new Sha256Hash(credentials, salt, hashIterations);
}
diff --git a/src/org/jsecurity/authc/credential/Sha384CredentialsMatcher.java b/src/org/jsecurity/authc/credential/Sha384CredentialsMatcher.java
index 552f8a8..40ea703 100644
--- a/src/org/jsecurity/authc/credential/Sha384CredentialsMatcher.java
+++ b/src/org/jsecurity/authc/credential/Sha384CredentialsMatcher.java
@@ -31,10 +31,19 @@
*/
public class Sha384CredentialsMatcher extends HashedCredentialsMatcher {
+ /**
+ * Creates a new <em>uninitialized</em> {@link Sha384Hash Sha384Hash} instance, without it's byte array set.
+ *
+ * @return a new <em>uninitialized</em> {@link Sha384Hash Sha384Hash} instance, without it's byte array set.
+ */
protected AbstractHash newHashInstance() {
return new Sha384Hash();
}
+ /**
+ * This implementation merely returns
+ * <code>new {@link Sha384Hash#Sha384Hash(Object, Object, int) Sha384Hash(credentials,salt,hashIterations)}</code>.
+ */
protected Hash hashProvidedCredentials(Object credentials, Object salt, int hashIterations) {
return new Sha384Hash(credentials, salt, hashIterations);
}
diff --git a/src/org/jsecurity/authc/credential/Sha512CredentialsMatcher.java b/src/org/jsecurity/authc/credential/Sha512CredentialsMatcher.java
index 2b8f6d3..0205386 100644
--- a/src/org/jsecurity/authc/credential/Sha512CredentialsMatcher.java
+++ b/src/org/jsecurity/authc/credential/Sha512CredentialsMatcher.java
@@ -31,10 +31,19 @@
*/
public class Sha512CredentialsMatcher extends HashedCredentialsMatcher {
+ /**
+ * Creates a new <em>uninitialized</em> {@link Sha512Hash Sha512Hash} instance, without it's byte array set.
+ *
+ * @return a new <em>uninitialized</em> {@link Sha512Hash Sha512Hash} instance, without it's byte array set.
+ */
protected AbstractHash newHashInstance() {
return new Sha512Hash();
}
+ /**
+ * This implementation merely returns
+ * <code>new {@link Sha512Hash#Sha512Hash(Object, Object, int) Sha512Hash(credentials,salt,hashIterations)}</code>.
+ */
protected Hash hashProvidedCredentials(Object credentials, Object salt, int hashIterations) {
return new Sha512Hash(credentials, salt, hashIterations);
}
diff --git a/src/org/jsecurity/authc/pam/AtLeastOneSuccessfulModularAuthenticationStrategy.java b/src/org/jsecurity/authc/pam/AtLeastOneSuccessfulModularAuthenticationStrategy.java
index c769e35..4b7bee2 100644
--- a/src/org/jsecurity/authc/pam/AtLeastOneSuccessfulModularAuthenticationStrategy.java
+++ b/src/org/jsecurity/authc/pam/AtLeastOneSuccessfulModularAuthenticationStrategy.java
@@ -41,6 +41,12 @@
*/
public class AtLeastOneSuccessfulModularAuthenticationStrategy extends AbstractAuthenticationStrategy {
+ /**
+ * Ensures that the <code>aggregate</code> method argument is not <code>null</code> and
+ * <code>aggregate.{@link org.jsecurity.authc.AuthenticationInfo#getPrincipals() getPrincipals()}</code>
+ * <code>null</code>, and if either is <code>null</code>, throws an AuthenticationException to indicate
+ * that none of the realms authenticated successfully.
+ */
public AuthenticationInfo afterAllAttempts(AuthenticationToken token, AuthenticationInfo aggregate) throws AuthenticationException {
//we know if one or more were able to succesfully authenticate if the aggregated account object does not
//contain null or empty data:
diff --git a/src/org/jsecurity/authc/pam/FirstSuccessfulAuthenticationStrategy.java b/src/org/jsecurity/authc/pam/FirstSuccessfulAuthenticationStrategy.java
index 0a13b48..8b2c116 100644
--- a/src/org/jsecurity/authc/pam/FirstSuccessfulAuthenticationStrategy.java
+++ b/src/org/jsecurity/authc/pam/FirstSuccessfulAuthenticationStrategy.java
@@ -27,9 +27,13 @@
/**
* {@link ModularAuthenticationStrategy} implementation that only accepts the account data from
- * the first successfully consulted Realm and ignores all subsequent realms.
+ * the first successfully consulted Realm and ignores all subsequent realms. This is slightly
+ * different behavior than
+ * {@link org.jsecurity.authc.pam.AtLeastOneSuccessfulModularAuthenticationStrategy AtLeastOneSuccessfulModularAuthenticationStrategy},
+ * so please review both to see which one meets your needs better.
*
* @author Les Hazlewood
+ * @see org.jsecurity.authc.pam.AtLeastOneSuccessfulModularAuthenticationStrategy AtLeastOneSuccessfulModularAuthenticationStrategy
* @since 0.9
*/
public class FirstSuccessfulAuthenticationStrategy extends AbstractAuthenticationStrategy {
