shiro-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From lhazlew...@apache.org
Subject svn commit: r828933 - in /incubator/shiro/trunk/core/src/main/java/org/apache/shiro/authc/pam: AuthenticationStrategy.java ModularRealmAuthenticator.java
Date Fri, 23 Oct 2009 04:44:34 GMT
Author: lhazlewood
Date: Fri Oct 23 04:44:34 2009
New Revision: 828933

URL: http://svn.apache.org/viewvc?rev=828933&view=rev
Log:
SHIRO-104 - fixed JavaDoc to reflect the previous code change

Modified:
    incubator/shiro/trunk/core/src/main/java/org/apache/shiro/authc/pam/AuthenticationStrategy.java
    incubator/shiro/trunk/core/src/main/java/org/apache/shiro/authc/pam/ModularRealmAuthenticator.java

Modified: incubator/shiro/trunk/core/src/main/java/org/apache/shiro/authc/pam/AuthenticationStrategy.java
URL: http://svn.apache.org/viewvc/incubator/shiro/trunk/core/src/main/java/org/apache/shiro/authc/pam/AuthenticationStrategy.java?rev=828933&r1=828932&r2=828933&view=diff
==============================================================================
--- incubator/shiro/trunk/core/src/main/java/org/apache/shiro/authc/pam/AuthenticationStrategy.java
(original)
+++ incubator/shiro/trunk/core/src/main/java/org/apache/shiro/authc/pam/AuthenticationStrategy.java
Fri Oct 23 04:44:34 2009
@@ -18,35 +18,35 @@
  */
 package org.apache.shiro.authc.pam;
 
-import java.util.Collection;
-
 import org.apache.shiro.authc.AuthenticationException;
 import org.apache.shiro.authc.AuthenticationInfo;
 import org.apache.shiro.authc.AuthenticationToken;
 import org.apache.shiro.realm.Realm;
 
+import java.util.Collection;
+
 
 /**
- * A <tt>AuthenticationStrategy</tt> implementation assists the {@link ModularRealmAuthenticator}
during the
+ * A {@code AuthenticationStrategy} implementation assists the {@link ModularRealmAuthenticator}
during the
  * log-in process in a pluggable realm (PAM) environment.
  *
- * <p>The <tt>ModularRealmAuthenticator</tt> will consult implementations
of this interface on what to do during each
+ * <p>The {@code ModularRealmAuthenticator} will consult implementations of this interface
on what to do during each
  * interaction with the configured Realms.  This allows a pluggable strategy of whether or
not an authentication
  * attempt must be successful for all realms, only 1 or more realms, no realms, etc.
  *
  * @author Les Hazlewood
- * @see AllSuccessfulStrategy AllSuccessfulAuthenticationStrategy
- * @see AtLeastOneSuccessfulStrategy AtLeastOneSuccessfulAuthenticationStrategy
- * @see FirstSuccessfulStrategy FirstSuccessfulAuthenticationStrategy
+ * @see AllSuccessfulStrategy
+ * @see AtLeastOneSuccessfulStrategy
+ * @see FirstSuccessfulStrategy
  * @since 0.2
  */
 public interface AuthenticationStrategy {
 
     /**
      * Method invoked by the ModularAuthenticator signifying that the authentication process
is about to begin for the
-     * specified <tt>token</tt> - called before any <tt>Realm</tt>
is actually invoked.
+     * specified {@code token} - called before any {@code Realm} is actually invoked.
      *
-     * <p>The <code>AuthenticationInfo</code> object returned from this
method is essentially an empty place holder for
+     * <p>The {@code AuthenticationInfo} object returned from this method is essentially
an empty place holder for
      * aggregating account data across multiple realms.  It should be populated by the strategy
implementation over the
      * course of authentication attempts across the multiple realms.  It will be passed into
the
      * {@link #beforeAttempt} calls, allowing inspection of the aggregated account data up
to that point in the
@@ -63,17 +63,18 @@
      * Method invoked by the ModularAuthenticator just prior to the realm being consulted
for account data,
      * allowing pre-authentication-attempt logic for that realm only.
      *
-     * <p>This method returns an <code>AuthenticationInfo</code> object
that will be used for further interaction with realms.  Most
-     * implementations will merely return the <code>aggregate</code> method argument
if they don't have a need to
+     * <p>This method returns an {@code AuthenticationInfo} object that will be used
for further interaction with realms.  Most
+     * implementations will merely return the {@code aggregate} method argument if they don't
have a need to
      * manipulate it.
      *
-     * @param realm     the realm that will be consulted for <tt>AuthenticationInfo</tt>
for the specified <tt>token</tt>.
-     * @param token     the <tt>AuthenticationToken</tt> submitted for the subject
attempting system log-in.
+     * @param realm     the realm that will be consulted for {@code AuthenticationInfo} for
the specified {@code token}.
+     * @param token     the {@code AuthenticationToken} submitted for the subject attempting
system log-in.
      * @param aggregate the aggregated AuthenticationInfo object being used across the multi-realm
authentication attempt
      * @return the AuthenticationInfo object that will be presented to further realms in
the authentication process - returning
-     *         the <code>aggregate</code> method argument is the normal case
if no special action needs to be taken.
-     * @throws org.apache.shiro.authc.AuthenticationException an exception thrown by the
Strategy implementation if it wishes the login
-     *                                 process for the associated subject (user) to stop
immediately.
+     *         the {@code aggregate} method argument is the normal case if no special action
needs to be taken.
+     * @throws org.apache.shiro.authc.AuthenticationException
+     *          an exception thrown by the Strategy implementation if it wishes the login
+     *          process for the associated subject (user) to stop immediately.
      */
     AuthenticationInfo beforeAttempt(Realm realm, AuthenticationToken token, AuthenticationInfo
aggregate) throws AuthenticationException;
 
@@ -81,17 +82,17 @@
      * Method invoked by the ModularAuthenticator just after the given realm has been consulted
for authentication,
      * allowing post-authentication-attempt logic for that realm only.
      *
-     * <p>This method returns an <code>AuthenticationInfo</code> object
that will be used for further interaction with realms.  Most
-     * implementations will merge the <code>singleRealmInfo</code> into the <code>aggregateInfo</code>
and
-     * just return the <code>aggregateInfo</code> for continued use throughout
the authentication process.</p>
-     *
-     * @param realm              the realm that was just consulted for <tt>AuthenticationInfo</tt>
for the given <tt>token</tt>.
-     * @param token              the <tt>AuthenticationToken</tt> submitted for
the subject attempting system log-in.
-     * @param singleRealmInfo    the info returned from a single realm.
-     * @param aggregateInfo      the aggregate info representing all realms in a multi-realm
environment.
-     * @param t                  the Throwable thrown by the Realm during the attempt, or
<tt>null</tt> if the method returned normally.
+     * <p>This method returns an {@code AuthenticationInfo} object that will be used
for further interaction with realms.  Most
+     * implementations will merge the {@code singleRealmInfo} into the {@code aggregateInfo}
and
+     * just return the {@code aggregateInfo} for continued use throughout the authentication
process.</p>
+     *
+     * @param realm           the realm that was just consulted for {@code AuthenticationInfo}
for the given {@code token}.
+     * @param token           the {@code AuthenticationToken} submitted for the subject attempting
system log-in.
+     * @param singleRealmInfo the info returned from a single realm.
+     * @param aggregateInfo   the aggregate info representing all realms in a multi-realm
environment.
+     * @param t               the Throwable thrown by the Realm during the attempt, or {@code
null} if the method returned normally.
      * @return the AuthenticationInfo object that will be presented to further realms in
the authentication process - returning
-     *         the <code>aggregateAccount</code> method argument is the normal
case if no special action needs to be taken.
+     *         the {@code aggregateAccount} method argument is the normal case if no special
action needs to be taken.
      * @throws AuthenticationException an exception thrown by the Strategy implementation
if it wishes the login process
      *                                 for the associated subject (user) to stop immediately.
      */
@@ -106,9 +107,9 @@
      * This is most likely the aggregate AuthenticationInfo object that has been populated
by many realms, but the actual return value is
      * always up to the implementation.
      *
-     * @param token     the <tt>AuthenticationToken</tt> submitted for the subject
attempting system log-in.
-     * @param aggregate the aggregate <tt>AuthenticationInfo</tt> instance populated
by all realms during the log-in attempt.
-     * @return the final <code>AuthenticationInfo</code> object to return to
the Authenticator.authenticate() caller.
+     * @param token     the {@code AuthenticationToken} submitted for the subject attempting
system log-in.
+     * @param aggregate the aggregate {@code AuthenticationInfo} instance populated by all
realms during the log-in attempt.
+     * @return the final {@code AuthenticationInfo} object to return to the Authenticator.authenticate()
caller.
      * @throws AuthenticationException if the Strategy implementation wishes to fail the
authentication attempt.
      */
     AuthenticationInfo afterAllAttempts(AuthenticationToken token, AuthenticationInfo aggregate)
throws AuthenticationException;

Modified: incubator/shiro/trunk/core/src/main/java/org/apache/shiro/authc/pam/ModularRealmAuthenticator.java
URL: http://svn.apache.org/viewvc/incubator/shiro/trunk/core/src/main/java/org/apache/shiro/authc/pam/ModularRealmAuthenticator.java?rev=828933&r1=828932&r2=828933&view=diff
==============================================================================
--- incubator/shiro/trunk/core/src/main/java/org/apache/shiro/authc/pam/ModularRealmAuthenticator.java
(original)
+++ incubator/shiro/trunk/core/src/main/java/org/apache/shiro/authc/pam/ModularRealmAuthenticator.java
Fri Oct 23 04:44:34 2009
@@ -29,12 +29,12 @@
 import java.util.List;
 
 /**
- * A <tt>ModularRealmAuthenticator</tt> delgates account lookups to a pluggable
(modular) collection of
+ * A {@code ModularRealmAuthenticator} delgates account lookups to a pluggable (modular)
collection of
  * {@link Realm}s.  This enables PAM (Pluggable Authentication Module) behavior in Shiro.
  * In addition to authorization duties, a Shiro Realm can also be thought of a PAM 'module'.
  * <p/>
  * <p>Using this Authenticator allows you to &quot;plug-in&quot; your own
- * <tt>Realm</tt>s as you see fit.  Common realms are those based on accessing
+ * {@code Realm}s as you see fit.  Common realms are those based on accessing
  * LDAP, relational databases, file systems, etc.
  * <p/>
  * <p>If only one realm is configured (this is often the case for most applications),
authentication success is naturally
@@ -53,14 +53,15 @@
  * determine what constitutes a success or failure in a multi-realm (PAM) scenario.  And
because this only makes sense
  * in a mult-realm scenario, the strategy object is only utilized when more than one Realm
is configured.
  * <p/>
- * <p>For greater security in a multi-realm configuration, unless overridden, the default
implementation is the
- * {@link AllSuccessfulStrategy AllSuccessfulAuthenticationStrategy}
+ * <p>As most multi-realm applications require at least one Realm authenticates successfully,
the default
+ * implementation is the {@link AtLeastOneSuccessfulStrategy}.
  *
  * @author Jeremy Haile
  * @author Les Hazlewood
  * @see #setRealms
- * @see AllSuccessfulStrategy
  * @see AtLeastOneSuccessfulStrategy
+ * @see AllSuccessfulStrategy
+ * @see FirstSuccessfulStrategy
  * @since 0.1
  */
 public class ModularRealmAuthenticator extends AbstractAuthenticator {
@@ -79,7 +80,8 @@
     private Collection<Realm> realms;
 
     /**
-     * The authentication strategy to use during authentication attempts.
+     * The authentication strategy to use during authentication attempts, defaults to a
+     * {@link org.apache.shiro.authc.pam.AtLeastOneSuccessfulStrategy} instance.
      */
     private AuthenticationStrategy authenticationStrategy;
 
@@ -88,17 +90,16 @@
     ============================================*/
     /**
      * Default no-argument constructor which
-     * {@link #setAuthenticationStrategy(AuthenticationStrategy) enables}  a
-     * {@link AllSuccessfulStrategy AllSuccessfulAuthenticationStrategy}
+     * {@link #setAuthenticationStrategy(AuthenticationStrategy) enables}  an
+     * {@link org.apache.shiro.authc.pam.AtLeastOneSuccessfulStrategy}
      * by default.
      */
     public ModularRealmAuthenticator() {
-        AuthenticationStrategy strategy = new AtLeastOneSuccessfulStrategy();
-        setAuthenticationStrategy(strategy);
+        this.authenticationStrategy = new AtLeastOneSuccessfulStrategy();
     }
 
     /**
-     * Constructor which initializes this <code>Authenticator</code> with a single
realm to use during
+     * Constructor which initializes this {@code Authenticator} with a single realm to use
during
      * an authentiation attempt.  Because
      * this would set a single realm, no {@link #setAuthenticationStrategy(AuthenticationStrategy)
      * AuthenticationStrategy} would be used during authentication attempts.
@@ -110,7 +111,7 @@
     }
 
     /**
-     * Constructor which initializes this <code>Authenticator</code> with multiple
realms that will be
+     * Constructor which initializes this {@code Authenticator} with multiple realms that
will be
      * consulted during an authentication attempt, effectively enabling PAM (Pluggable Authentication
Module)
      * behavior according to the configured
      * {@link #setAuthenticationStrategy(AuthenticationStrategy) AuthenticationStrategy}.
@@ -146,23 +147,23 @@
     }
 
     /**
-     * Returns the realm(s) used by this <code>Authenticator</code> during an
authentication attempt.
+     * Returns the realm(s) used by this {@code Authenticator} during an authentication attempt.
      *
-     * @return the realm(s) used by this <code>Authenticator</code> during an
authentication attempt.
+     * @return the realm(s) used by this {@code Authenticator} during an authentication attempt.
      */
     protected Collection<Realm> getRealms() {
         return this.realms;
     }
 
     /**
-     * Returns the <tt>AuthenticationStrategy</tt> utilized by this modular authenticator
during a multi-realm
+     * Returns the {@code AuthenticationStrategy} utilized by this modular authenticator
during a multi-realm
      * log-in attempt.  This object is only used when two or more Realms are configured.
      * <p/>
      * <p>Unless overridden by
      * the {@link #setAuthenticationStrategy(AuthenticationStrategy)} method, the default
implementation
-     * is the {@link AllSuccessfulStrategy}.
+     * is the {@link org.apache.shiro.authc.pam.AtLeastOneSuccessfulStrategy}.
      *
-     * @return the <tt>AuthenticationStrategy</tt> utilized by this modular authenticator
during a log-in attempt.
+     * @return the {@code AuthenticationStrategy} utilized by this modular authenticator
during a log-in attempt.
      * @since 0.2
      */
     public AuthenticationStrategy getAuthenticationStrategy() {
@@ -170,7 +171,7 @@
     }
 
     /**
-     * Allows overriding the default <tt>AuthenticationStrategy</tt> utilized
during multi-realm log-in attempts.
+     * Allows overriding the default {@code AuthenticationStrategy} utilized during multi-realm
log-in attempts.
      * This object is only used when two or more Realms are configured.
      *
      * @param authenticationStrategy the strategy implementation to use during log-in attempts.
@@ -184,10 +185,10 @@
     |               M E T H O D S               |
     ============================================*/
     /**
-     * Used by the internal {@link #doAuthenticate} implementation to ensure that the <tt>realms</tt>
property
+     * Used by the internal {@link #doAuthenticate} implementation to ensure that the {@code
realms} property
      * has been set.  The default implementation ensures the property is not null and not
empty.
      *
-     * @throws IllegalStateException if the <tt>realms</tt> property is configured
incorrectly.
+     * @throws IllegalStateException if the {@code realms} property is configured incorrectly.
      */
     protected void assertRealmsConfigured() throws IllegalStateException {
         Collection<Realm> realms = getRealms();
@@ -204,7 +205,7 @@
      *
      * @param realm the realm to consult for AuthenticationInfo.
      * @param token the submitted AuthenticationToken representing the subject's (user's)
log-in principals and credentials.
-     * @return the AuthenticationInfo associated with the user account corresponding to the
specified <tt>token</tt>
+     * @return the AuthenticationInfo associated with the user account corresponding to the
specified {@code token}
      */
     protected AuthenticationInfo doSingleRealmAuthentication(Realm realm, AuthenticationToken
token) {
         if (!realm.supports(token)) {
@@ -224,7 +225,7 @@
 
     /**
      * Performs the multi-realm authentication attempt by calling back to a {@link AuthenticationStrategy}
object
-     * as each realm is consulted for <tt>AuthenticationInfo</tt> for the specified
<tt>token</tt>.
+     * as each realm is consulted for {@code AuthenticationInfo} for the specified {@code
token}.
      *
      * @param realms the multiple realms configured on this Authenticator instance.
      * @param token  the submitted AuthenticationToken representing the subject's (user's)
log-in principals and credentials.
@@ -275,12 +276,12 @@
     /**
      * <p>Attempts to authenticate the given token by iterating over the internal collection
of
      * {@link Realm}s.  For each realm, first the {@link Realm#supports(org.apache.shiro.authc.AuthenticationToken)}
-     * method will be called to determine if the realm supports the <tt>authenticationToken</tt>
method argument.
+     * method will be called to determine if the realm supports the {@code authenticationToken}
method argument.
      * <p/>
      * If a realm does support
      * the token, its {@link Realm#getAuthenticationInfo(org.apache.shiro.authc.AuthenticationToken)}
      * method will be called.  If the realm returns a non-null account, the token will be
-     * considered authenticated for that realm and the account data recorded.  If the realm
returns <tt>null</tt>,
+     * considered authenticated for that realm and the account data recorded.  If the realm
returns {@code null},
      * the next realm will be consulted.  If no realms support the token or all supporting
realms return null,
      * an {@link AuthenticationException} will be thrown to indicate that the user could
not be authenticated.
      * <p/>
@@ -306,11 +307,11 @@
 
     /**
      * First calls <code>super.onLogout(principals)</code> to ensure a logout
notification is issued, and for each
-     * wrapped <tt>Realm</tt> that implements the {@link LogoutAware LogoutAware}
interface, calls
+     * wrapped {@code Realm} that implements the {@link LogoutAware LogoutAware} interface,
calls
      * <code>((LogoutAware)realm).onLogout(principals)</code> to allow each realm
the opportunity to perform
      * logout/cleanup operations during an user-logout.
      * <p/>
-     * <p>Shiro's Realm implementations all implement the <tt>LogoutAware</tt>
interface by default and can be
+     * <p>Shiro's Realm implementations all implement the {@code LogoutAware} interface
by default and can be
      * overridden for realm-specific logout logic.
      *
      * @param principals the application-specific Subject/user identifier.



Mime
View raw message