shiro-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From lhazlew...@apache.org
Subject svn commit: r815372 - in /incubator/shiro/trunk/core/src/main/java/org/apache/shiro: crypto/hash/AbstractHash.java realm/AuthorizingRealm.java session/mgt/eis/SessionDAO.java
Date Tue, 15 Sep 2009 15:43:10 GMT
Author: lhazlewood
Date: Tue Sep 15 15:43:09 2009
New Revision: 815372

URL: http://svn.apache.org/viewvc?rev=815372&view=rev
Log:
minor formatting and spelling and JavaDoc changes

Modified:
    incubator/shiro/trunk/core/src/main/java/org/apache/shiro/crypto/hash/AbstractHash.java
    incubator/shiro/trunk/core/src/main/java/org/apache/shiro/realm/AuthorizingRealm.java
    incubator/shiro/trunk/core/src/main/java/org/apache/shiro/session/mgt/eis/SessionDAO.java

Modified: incubator/shiro/trunk/core/src/main/java/org/apache/shiro/crypto/hash/AbstractHash.java
URL: http://svn.apache.org/viewvc/incubator/shiro/trunk/core/src/main/java/org/apache/shiro/crypto/hash/AbstractHash.java?rev=815372&r1=815371&r2=815372&view=diff
==============================================================================
--- incubator/shiro/trunk/core/src/main/java/org/apache/shiro/crypto/hash/AbstractHash.java
(original)
+++ incubator/shiro/trunk/core/src/main/java/org/apache/shiro/crypto/hash/AbstractHash.java
Tue Sep 15 15:43:09 2009
@@ -18,74 +18,81 @@
  */
 package org.apache.shiro.crypto.hash;
 
-import java.security.MessageDigest;
-import java.security.NoSuchAlgorithmException;
-import java.util.Arrays;
-import java.io.Serializable;
-
 import org.apache.shiro.codec.Base64;
 import org.apache.shiro.codec.CodecException;
 import org.apache.shiro.codec.CodecSupport;
 import org.apache.shiro.codec.Hex;
 
+import java.io.Serializable;
+import java.security.MessageDigest;
+import java.security.NoSuchAlgorithmException;
+import java.util.Arrays;
+
 /**
  * Provides a base for all Shiro Hash algorithms with support for salts and multiple hash
iterations.
- *
- * <p>Read <a href="http://www.owasp.org/index.php/Hashing_Java" target="blank">http://www.owasp.org/index.php/Hashing_Java</a>
for a
- * good article on the benefits of hashing, including what a 'salt' is as well as why it
and multiple hash iterations
- * can be useful.
- *
- * <p>This class and its subclasses support hashing with additional capabilities of
salting and multiple iterations via
- * overloaded constructors</p>.
+ * <p/>
+ * Read
+ * <a href="http://www.owasp.org/index.php/Hashing_Java" target="blank">http://www.owasp.org/index.php/Hashing_Java</a>
+ * for a good article on the benefits of hashing, including what a 'salt' is as well as why
it and multiple hash
+ * iterations can be useful.
+ * <p/>
+ * This class and its subclasses support hashing with additional capabilities of salting
and multiple iterations via
+ * overloaded constructors.
  *
  * @author Les Hazlewood
  * @since 0.9
  */
 public abstract class AbstractHash extends CodecSupport implements Hash, Serializable {
 
-    /** The hashed data */
+    /**
+     * The hashed data
+     */
     private byte[] bytes = null;
 
-    /** Cached value of the {@link #toHex() toHex()} call so multiple calls won't incur repeated
overhead. */
+    /**
+     * Cached value of the {@link #toHex() toHex()} call so multiple calls won't incur repeated
overhead.
+     */
     private transient String hexEncoded = null;
-    /** Cached value of the {@link #toBase64() toBase64()} call so multiple calls won't incur
repeated overhead. */
+    /**
+     * Cached value of the {@link #toBase64() toBase64()} call so multiple calls won't incur
repeated overhead.
+     */
     private transient String base64Encoded = null;
 
     /**
      * Creates an new instance without any of its properties set (no hashing is performed).
-     *
-     * <p>Because all constructors in this class
-     * (except this one) hash the <tt>source</tt> constructor argument, this
default, no-arg constructor is useful in
-     * scenarios whenyou have a byte array that you know is already hashed and just want
to set the bytes in their
-     * raw form directly on an instance.  After instantiating the instance with this default,
no-arg constructor, you
-     * can then immediately call {@link #setBytes setBytes} to have a fully-initiallized
instance.
+     * <p/>
+     * Because all constructors in this class (except this one) hash the {@code source} constructor
argument, this
+     * default, no-arg constructor is useful in scenarios when you have a byte array that
you know is already hashed and
+     * just want to set the bytes in their raw form directly on an instance.  After instantiating
the instance with
+     * this default, no-arg constructor, you can then immediately call {@link #setBytes setBytes}
to have a
+     * fully-initialized instance.
      */
     public AbstractHash() {
     }
 
     /**
-     * Creates a hash of the specified <tt>source</tt> with no <tt>salt</tt>
using a single hash iteration.
-     *
-     * <p>It is a convenience constructor that merely executes <code>this( source,
null, 1);</code>.
-     *
-     * <p>Please see the
+     * Creates a hash of the specified {@code source} with no {@code salt} using a single
hash iteration.
+     * <p/>
+     * It is a convenience constructor that merely executes <code>this( source, null,
1);</code>.
+     * <p/>
+     * Please see the
      * {@link #AbstractHash(Object source, Object salt, int numIterations) AbstractHash(Object,Object,int)}
      * constructor for the types of Objects that may be passed into this constructor, as
well as how to support further
      * types.
      *
      * @param source the object to be hashed.
-     * @throws CodecException if the specified <tt>source</tt> cannot be converted
into a byte array (byte[]).
+     * @throws CodecException if the specified {@code source} cannot be converted into a
byte array (byte[]).
      */
     public AbstractHash(Object source) throws CodecException {
         this(source, null, 1);
     }
 
     /**
-     * Creates a hash of the specified <tt>source</tt> using the given <tt>salt</tt>
using a single hash iteration.
-     *
-     * <p>It is a convenience constructor that merely executes <code>this( source,
salt, 1);</code>.
-     *
-     * <p>Please see the
+     * Creates a hash of the specified {@code source} using the given {@code salt} using
a single hash iteration.
+     * <p/>
+     * It is a convenience constructor that merely executes <code>this( source, salt,
1);</code>.
+     * <p/>
+     * Please see the
      * {@link #AbstractHash(Object source, Object salt, int numIterations) AbstractHash(Object,Object,int)}
      * constructor for the types of Objects that may be passed into this constructor, as
well as how to support further
      * types.
@@ -99,21 +106,21 @@
     }
 
     /**
-     * Creates a hash of the specified <tt>source</tt> using the given <tt>salt</tt>
a total of
-     * <tt>hashIterations</tt> times.
-     *
-     * <p>By default, this class only supports Object method arguments of
-     * type <tt>byte[]</tt>, <tt>char[]</tt> and <tt>String</tt>.
 If either argument is anything other than these
+     * Creates a hash of the specified {@code source} using the given {@code salt} a total
of
+     * {@code hashIterations} times.
+     * <p/>
+     * By default, this class only supports Object method arguments of
+     * type {@code byte[]}, {@code char[]} and {@code String}.  If either argument is anything
other than these
      * types a {@link org.apache.shiro.codec.CodecException CodecException} will be thrown.
-     *
-     * <p>If you want to be able to hash other object types, or use other salt types,
you need to override the
+     * <p/>
+     * If you want to be able to hash other object types, or use other salt types, you need
to override the
      * {@link #toBytes(Object) toBytes(Object)} method to support those specific types. 
Your other option is to
      * convert your arguments to one of the default three supported types first before passing
them in to this
-     * constructor</tt>.
+     * constructor}.
      *
      * @param source         the source object to be hashed.
      * @param salt           the salt to use for the hash
-     * @param hashIterations the number of times the <tt>source</tt> argument
hashed for attack resiliency.
+     * @param hashIterations the number of times the {@code source} argument hashed for attack
resiliency.
      * @throws CodecException if either Object constructor argument cannot be converted into
a byte array.
      */
     public AbstractHash(Object source, Object salt, int hashIterations) throws CodecException
{
@@ -140,8 +147,8 @@
 
     /**
      * Sets the raw bytes stored by this hash instance.
-     *
-     * <p>The bytes are kept in raw form - they will not be hashed/changed.  This is
primarily a utility method for
+     * <p/>
+     * The bytes are kept in raw form - they will not be hashed/changed.  This is primarily
a utility method for
      * constructing a Hash instance when the hashed value is already known.
      *
      * @param alreadyHashedBytes the raw already-hashed bytes to store in this instance.
@@ -156,7 +163,7 @@
      * Returns the JDK MessageDigest instance to use for executing the hash.
      *
      * @param algorithmName the algorithm to use for the hash, provided by subclasses.
-     * @return the MessageDigest object for the specfied <tt>algorithm</tt>.
+     * @return the MessageDigest object for the specified {@code algorithm}.
      */
     protected MessageDigest getDigest(String algorithmName) {
         try {
@@ -178,7 +185,7 @@
     }
 
     /**
-     * Hashes the specified byte array using the given <tt>salt</tt> for a single
iteration.
+     * Hashes the specified byte array using the given {@code salt} for a single iteration.
      *
      * @param bytes the bytes to hash
      * @param salt  the salt to use for the initial hash
@@ -189,33 +196,33 @@
     }
 
     /**
-     * Hashes the specified byte array using the given <tt>salt</tt> for the
specified number of iterations.
+     * Hashes the specified byte array using the given {@code salt} for the specified number
of iterations.
      *
      * @param bytes          the bytes to hash
      * @param salt           the salt to use for the initial hash
-     * @param hashIterations the number of times the the <tt>bytes</tt> will
be hashed (for attack resiliency).
+     * @param hashIterations the number of times the the {@code bytes} will be hashed (for
attack resiliency).
      * @return the hashed bytes.
      */
     protected byte[] hash(byte[] bytes, byte[] salt, int hashIterations) {
-        MessageDigest md = getDigest(getAlgorithmName());
+        MessageDigest digest = getDigest(getAlgorithmName());
         if (salt != null) {
-            md.reset();
-            md.update(salt);
+            digest.reset();
+            digest.update(salt);
         }
-        byte[] hashed = md.digest(bytes);
+        byte[] hashed = digest.digest(bytes);
         int iterations = hashIterations - 1; //already hashed once above
         //iterate remaining number:
         for (int i = 0; i < iterations; i++) {
-            md.reset();
-            hashed = md.digest(hashed);
+            digest.reset();
+            hashed = digest.digest(hashed);
         }
         return hashed;
     }
 
     /**
      * Returns a hex-encoded string of the underlying {@link #getBytes byte array}.
-     *
-     * <p>This implementation caches the resulting hex string so multiple calls to
this method remain performant.
+     * <p/>
+     * This implementation caches the resulting hex string so multiple calls to this method
remain efficient.
      * However, calling {@link #setBytes setBytes} will null the cached value, forcing it
to be recalculated the
      * next time this method is called.
      *
@@ -230,8 +237,8 @@
 
     /**
      * Returns a Base64-encoded string of the underlying {@link #getBytes byte array}.
-     *
-     * <p>This implementation caches the resulting Base64 string so multiple calls
to this method remain performant.
+     * <p/>
+     * This implementation caches the resulting Base64 string so multiple calls to this method
remain efficient.
      * However, calling {@link #setBytes setBytes} will null the cached value, forcing it
to be recalculated the
      * next time this method is called.
      *
@@ -255,12 +262,12 @@
     }
 
     /**
-     * Returns <tt>true</tt> if the specified object is a Hash and its {@link
#getBytes byte array} is identical to
-     * this Hash's byte array, <tt>false</tt> otherwise.
+     * Returns {@code true} if the specified object is a Hash and its {@link #getBytes byte
array} is identical to
+     * this Hash's byte array, {@code false} otherwise.
      *
      * @param o the object (Hash) to check for equality.
-     * @return <tt>true</tt> if the specified object is a Hash and its {@link
#getBytes byte array} is identical to
-     *         this Hash's byte array, <tt>false</tt> otherwise.
+     * @return {@code true} if the specified object is a Hash and its {@link #getBytes byte
array} is identical to
+     *         this Hash's byte array, {@code false} otherwise.
      */
     public boolean equals(Object o) {
         if (o instanceof Hash) {

Modified: incubator/shiro/trunk/core/src/main/java/org/apache/shiro/realm/AuthorizingRealm.java
URL: http://svn.apache.org/viewvc/incubator/shiro/trunk/core/src/main/java/org/apache/shiro/realm/AuthorizingRealm.java?rev=815372&r1=815371&r2=815372&view=diff
==============================================================================
--- incubator/shiro/trunk/core/src/main/java/org/apache/shiro/realm/AuthorizingRealm.java
(original)
+++ incubator/shiro/trunk/core/src/main/java/org/apache/shiro/realm/AuthorizingRealm.java
Tue Sep 15 15:43:09 2009
@@ -34,7 +34,7 @@
 
 
 /**
- * An <tt>AuthorizingRealm</tt> extends the <tt>AuthenticatingRealm</tt>'s
capabilities by adding Authorization
+ * An {@code AuthorizingRealm} extends the {@code AuthenticatingRealm}'s capabilities by
adding Authorization
  * (access control) support.
  * <p/>
  * This implementation will perform all role and permission checks automatically (and subclasses
do not have to
@@ -64,9 +64,9 @@
     private static final Logger log = LoggerFactory.getLogger(AuthorizingRealm.class);
 
     /**
-     * The default postfix appended to the realm name for caching AuthorizationInfos.
+     * The default suffix appended to the realm name for caching AuthorizationInfo instances.
      */
-    private static final String DEFAULT_AUTHORIZATION_CACHE_POSTFIX = "-authorization";
+    private static final String DEFAULT_AUTHORIZATION_CACHE_SUFFIX = "-authorization";
 
     private static int INSTANCE_COUNT = 0;
 
@@ -74,7 +74,7 @@
     |    I N S T A N C E   V A R I A B L E S    |
     ============================================*/
     /**
-     * The cache used by this realm to store AuthorizationInfos associated with individual
Subject principals.
+     * The cache used by this realm to store AuthorizationInfo instances associated with
individual Subject principals.
      */
     private Cache authorizationCache = null;
     private String authorizationCacheName = null;
@@ -140,15 +140,15 @@
      * <li>If the {@link #setAuthorizationCache cache} property has been set, it will
be
      * used to cache the AuthorizationInfo objects returned from {@link #getAuthorizationInfo}
      * method invocations.
-     * All future calls to <tt>getAuthorizationInfo</tt> will attempt to use
this cache first
+     * All future calls to {@code getAuthorizationInfo} will attempt to use this cache first
      * to alleviate any potentially unnecessary calls to an underlying data store.</li>
      * <li>If the {@link #setAuthorizationCache cache} property has <b>not</b>
been set,
      * the {@link #setCacheManager cacheManager} property will be checked.
-     * If a <tt>cacheManager</tt> has been set, it will be used to create an
authorization
-     * <tt>cache</tt>, and this newly created cache which will be used as specified
in #1.</li>
+     * If a {@code cacheManager} has been set, it will be used to create an authorization
+     * {@code cache}, and this newly created cache which will be used as specified in #1.</li>
      * <li>If neither the {@link #setAuthorizationCache (org.apache.shiro.cache.Cache)
cache}
      * or {@link #setCacheManager(org.apache.shiro.cache.CacheManager) cacheManager}
-     * properties are set, caching will be disabled and authorization lookups will be delegated
to
+     * properties are set, caching will be disabled and authorization look-ups will be delegated
to
      * subclass implementations for each authorization check.</li>
      * </ol>
      */
@@ -183,7 +183,7 @@
                 String cacheName = getAuthorizationCacheName();
                 if (cacheName == null) {
                     //Simple default in case they didn't provide one:
-                    cacheName = getClass().getName() + "-" + INSTANCE_COUNT++ + DEFAULT_AUTHORIZATION_CACHE_POSTFIX;
+                    cacheName = getClass().getName() + "-" + INSTANCE_COUNT++ + DEFAULT_AUTHORIZATION_CACHE_SUFFIX;
                     setAuthorizationCacheName(cacheName);
                 }
                 if (log.isDebugEnabled()) {
@@ -203,12 +203,12 @@
 
 
     /**
-     * Returns an account's authorization-specific information for the specified <code>principals</code>,
-     * or <tt>null</tt> if no account could be found.  The resulting <code>AuthorizationInfo</code>
object is used
+     * Returns an account's authorization-specific information for the specified {@code principals},
+     * or {@code null} if no account could be found.  The resulting {@code AuthorizationInfo}
object is used
      * by the other method implementations in this class to automatically perform access
control checks for the
-     * corresponding <code>Subject</code>.
+     * corresponding {@code Subject}.
      * <p/>
-     * This implementation obtains the actual <code>AuthorizationInfo</code>
object from the subclass's
+     * This implementation obtains the actual {@code AuthorizationInfo} object from the subclass's
      * implementation of
      * {@link #doGetAuthorizationInfo(org.apache.shiro.subject.PrincipalCollection) doGetAuthorizationInfo},
and then
      * caches it for efficient reuse if caching is enabled (see below).
@@ -222,29 +222,30 @@
      * But because their identity would be remembered, that is sufficient enough information
to call this method to
      * execute any necessary authorization checks.  For this reason, authentication and authorization
should be
      * loosely coupled and not depend on each other.
-     * <h4>Caching</h4>
-     * The <code>AuthorizationInfo</code> values returned from this method are
cached for performant reuse
-     * if caching is enabled.  Caching is enabled automatically when a <code>CacheManager</code>
has been
-     * {@link #setCacheManager injected} and then the realm is {@link #init initialized}.
 It can also be enabled by explictly
-     * calling {@link #initAuthorizationCache() initAuthorizationCache()}.
+     * <h3>Caching</h3>
+     * The {@code AuthorizationInfo} values returned from this method are cached for efficient
reuse
+     * if caching is enabled.  Caching is enabled automatically when a {@code CacheManager}
has been
+     * {@link #setCacheManager injected} and then the realm is {@link #init initialized}.
 It can also be enabled by
+     * explicitly calling {@link #initAuthorizationCache() initAuthorizationCache()}.
      * <p/>
      * If caching is enabled, the authorization cache will be checked first and if found,
will return the cached
-     * <code>AuthorizationInfo</code> immediately.  If caching is disabled, or
there is a cache miss from the cache
-     * lookup, the authorization info will be looked up from the underlying data store via
the
-     * {@link #doGetAuthorizationInfo(org.apache.shiro.subject.PrincipalCollection)} method,
which must be implemented by subclasses.
-     * <p/>
-     * <b>Please note:</b>  If caching is enabled and if any authorization data
for an account is changed at
-     * runtime, such as adding or removing roles and/or permissions, the subclass imlementation
should clear the
+     * {@code AuthorizationInfo} immediately.  If caching is disabled, or there is a cache
miss, the authorization
+     * info will be looked up from the underlying data store via the
+     * {@link #doGetAuthorizationInfo(org.apache.shiro.subject.PrincipalCollection)} method,
which must be implemented
+     * by subclasses.
+     * <h4>Changed Data</h4>
+     * If caching is enabled and if any authorization data for an account is changed at
+     * runtime, such as adding or removing roles and/or permissions, the subclass implementation
should clear the
      * cached AuthorizationInfo for that account via the
      * {@link #clearCachedAuthorizationInfo(org.apache.shiro.subject.PrincipalCollection)
clearCachedAuthorizationInfo}
-     * method.  This ensures that the next call to <code>getAuthorizationInfo(PrincipalCollection)</code>
will
+     * method.  This ensures that the next call to {@code getAuthorizationInfo(PrincipalCollection)}
will
      * acquire the account's fresh authorization data, where it will then be cached for efficient
reuse.  This
      * ensures that stale authorization data will not be reused.
      *
      * @param principals the corresponding Subject's identifying principals with which to
look up the Subject's
-     *                   <code>AuthorizationInfo</code>.
-     * @return the authorization information for the account associated with the specified
<code>principals</code>,
-     *         or <tt>null</tt> if no account could be found.
+     *                   {@code AuthorizationInfo}.
+     * @return the authorization information for the account associated with the specified
{@code principals},
+     *         or {@code null} if no account could be found.
      */
     protected AuthorizationInfo getAuthorizationInfo(PrincipalCollection principals) {
 
@@ -258,13 +259,13 @@
             log.trace("Retrieving AuthorizationInfo for principals [" + principals + "]");
         }
 
-        Cache authzCache = getAuthorizationCache();
-        if (authzCache != null) {
+        Cache cache = getAuthorizationCache();
+        if (cache != null) {
             if (log.isTraceEnabled()) {
                 log.trace("Attempting to retrieve the AuthorizationInfo from cache.");
             }
             Object key = getAuthorizationCacheKey(principals);
-            info = (AuthorizationInfo) authzCache.get(key);
+            info = (AuthorizationInfo) cache.get(key);
             if (log.isTraceEnabled()) {
                 if (info == null) {
                     log.trace("No AuthorizationInfo found in cache for principals [" + principals
+ "]");
@@ -276,15 +277,15 @@
 
 
         if (info == null) {
-            // Call template method if tbe info was not found in a cache
+            // Call template method if the info was not found in a cache
             info = doGetAuthorizationInfo(principals);
             // If the info is not null and the cache has been created, then cache the authorization
info.
-            if (info != null && authzCache != null) {
+            if (info != null && cache != null) {
                 if (log.isTraceEnabled()) {
                     log.trace("Caching authorization info for principals: [" + principals
+ "].");
                 }
                 Object key = getAuthorizationCacheKey(principals);
-                authzCache.put(key, info);
+                cache.put(key, info);
             }
         }
 
@@ -369,7 +370,7 @@
 
     @SuppressWarnings("deprecation")
     private boolean isPermitted(Permission permission, AuthorizationInfo info) {
-        //todo Remove this once AuthorizingAccount class is deleted
+        //TODO Remove this once AuthorizingAccount class is deleted
         if (info instanceof AuthorizingAccount) {
             return ((AuthorizingAccount) info).isPermitted(permission);
         }
@@ -400,7 +401,7 @@
 
     @SuppressWarnings("deprecation")
     protected boolean[] isPermitted(List<Permission> permissions, AuthorizationInfo
info) {
-        //todo Remove this once AuthorizingAccount class is deleted
+        //TODO Remove this once AuthorizingAccount class is deleted
         if (info instanceof AuthorizingAccount) {
             return ((AuthorizingAccount) info).isPermitted(permissions);
         }
@@ -437,7 +438,7 @@
 
     @SuppressWarnings("deprecation")
     protected boolean isPermittedAll(Collection<Permission> permissions, AuthorizationInfo
info) {
-        //todo Remove this once AuthorizingAccount class is deleted
+        //TODO Remove this once AuthorizingAccount class is deleted
         if (info instanceof AuthorizingAccount) {
             return ((AuthorizingAccount) info).isPermittedAll(permissions);
         }
@@ -464,7 +465,7 @@
 
     @SuppressWarnings("deprecation")
     protected void checkPermission(Permission permission, AuthorizationInfo info) {
-        //todo Remove this once AuthorizingAccount class is deleted
+        //TODO Remove this once AuthorizingAccount class is deleted
         if (info instanceof AuthorizingAccount) {
             ((AuthorizingAccount) info).checkPermission(permission);
         } else {
@@ -490,7 +491,7 @@
 
     @SuppressWarnings("deprecation")
     protected void checkPermissions(Collection<Permission> permissions, AuthorizationInfo
info) {
-        //todo Remove this once AuthorizingAccount class is deleted
+        //TODO Remove this once AuthorizingAccount class is deleted
         if (info instanceof AuthorizingAccount) {
             ((AuthorizingAccount) info).checkPermissions(permissions);
         } else {
@@ -509,7 +510,7 @@
 
     @SuppressWarnings("deprecation")
     protected boolean hasRole(String roleIdentifier, AuthorizationInfo info) {
-        //todo Remove this once AuthorizingAccount class is deleted
+        //TODO Remove this once AuthorizingAccount class is deleted
         if (info instanceof AuthorizingAccount) {
             return ((AuthorizingAccount) info).hasRole(roleIdentifier);
         }
@@ -527,7 +528,7 @@
 
     @SuppressWarnings("deprecation")
     protected boolean[] hasRoles(List<String> roleIdentifiers, AuthorizationInfo info)
{
-        //todo Remove this once AuthorizingAccount class is deleted
+        //TODO Remove this once AuthorizingAccount class is deleted
         if (info instanceof AuthorizingAccount) {
             return ((AuthorizingAccount) info).hasRoles(roleIdentifiers);
         }
@@ -553,7 +554,7 @@
 
     @SuppressWarnings("deprecation")
     private boolean hasAllRoles(Collection<String> roleIdentifiers, AuthorizationInfo
info) {
-        //todo Remove this once AuthorizingAccount class is deleted
+        //TODO Remove this once AuthorizingAccount class is deleted
         if (info instanceof AuthorizingAccount) {
             return ((AuthorizingAccount) info).hasAllRoles(roleIdentifiers);
         }
@@ -575,7 +576,7 @@
 
     @SuppressWarnings("deprecation")
     protected void checkRole(String role, AuthorizationInfo info) {
-        //todo Remove this once AuthorizingAccount class is deleted
+        //TODO Remove this once AuthorizingAccount class is deleted
         if (info instanceof AuthorizingAccount) {
             ((AuthorizingAccount) info).checkRole(role);
         } else {
@@ -593,7 +594,7 @@
 
     @SuppressWarnings("deprecation")
     protected void checkRoles(Collection<String> roles, AuthorizationInfo info) {
-        //todo Remove this once AuthorizingAccount class is deleted
+        //TODO Remove this once AuthorizingAccount class is deleted
         if (info instanceof AuthorizingAccount) {
             ((AuthorizingAccount) info).checkRoles(roles);
         } else {
@@ -607,7 +608,7 @@
 
     /**
      * If authorization caching is enabled, this will remove the AuthorizationInfo from the
cache.
-     * Subclasses are free to override for additional behavior, but be sure to call <tt>super.onLogout</tt>
+     * Subclasses are free to override for additional behavior, but be sure to call {@code
super.onLogout}
      * to ensure cache cleanup.
      *
      * @param principals the application-specific Subject/user identifier.
@@ -619,18 +620,18 @@
     /**
      * A utility method for subclasses that returns the first available principal of interest
to this particular realm.
      * The heuristic used to acquire the principal is as follows:
-     * <p/>
      * <ul>
      * <li>Attempt to get <em>this particular Realm's</em> 'primary' principal
in the {@code PrincipalCollection} via a
-     * <code>principals.{@link PrincipalCollection#fromRealm(String) fromRealm}( {@link
#getName() getName()} )</code>
+     * <code>principals.{@link PrincipalCollection#fromRealm(String) fromRealm}({@link
#getName() getName()})</code>
      * call.</li>
      * <li>If the previous call does not result in any principals, attempt to get the
overall 'primary' principal
      * from the PrincipalCollection via a <code>principals.{@link PrincipalCollection#asList()
asList()}.iterator().next()</code>
      * call.</li>
      * <li>If there are no principals from that call (or the PrincipalCollection argument
was null to begin with),
      * return {@code null}</li>
+     * </ul>
      *
-     * @param principals the PrincipalCollection holding all principals (from all realms)
assocatied with a single Subject.
+     * @param principals the PrincipalCollection holding all principals (from all realms)
associated with a single Subject.
      * @return the 'primary' principal attributed to this particular realm, or the fallback
'master' principal if it
      *         exists, or if not {@code null}.
      * @since 1.0

Modified: incubator/shiro/trunk/core/src/main/java/org/apache/shiro/session/mgt/eis/SessionDAO.java
URL: http://svn.apache.org/viewvc/incubator/shiro/trunk/core/src/main/java/org/apache/shiro/session/mgt/eis/SessionDAO.java?rev=815372&r1=815371&r2=815372&view=diff
==============================================================================
--- incubator/shiro/trunk/core/src/main/java/org/apache/shiro/session/mgt/eis/SessionDAO.java
(original)
+++ incubator/shiro/trunk/core/src/main/java/org/apache/shiro/session/mgt/eis/SessionDAO.java
Tue Sep 15 15:43:09 2009
@@ -33,7 +33,7 @@
  * <p/>
  * The remaining {@link #getActiveSessions()} method exists as a support mechanism to pre-emptively
orphaned sessions,
  * typically by {@link org.apache.shiro.session.mgt.ValidatingSessionManager ValidatingSessionManager}s),
and should
- * be as performant as possible, especially if there are thousands of active sessions.  Large
scale/high performance
+ * be as efficient as possible, especially if there are thousands of active sessions.  Large
scale/high performance
  * implementations will often return a subset of the total active sessions and perform validation
a little more
  * frequently, rather than return a massive set and infrequently validate.
  *
@@ -49,33 +49,33 @@
      * After this method is invoked, the {@link org.apache.shiro.session.Session#getId()}
      * method executed on the argument must return a valid session identifier.  That is,
the following should
      * always be true:
-     * <p/>
-     * <code>Serializable id = create( session );<br/>
-     * id.equals( session.getId() ) == true</code>
+     * <pre>
+     * Serializable id = create( session );
+     * id.equals( session.getId() ) == true</pre>
      * <p/>
      * Implementations are free to throw any exceptions that might occur due to
      * integrity violation constraints or other EIS related errors.
      *
      * @param session the {@link org.apache.shiro.session.Session} object to create in the
EIS.
-     * @return the EIS id (e.g. primary key) of the created <tt>Session</tt>
object.
+     * @return the EIS id (e.g. primary key) of the created {@code Session} object.
      */
     Serializable create(Session session);
 
     /**
      * Retrieves the session from the EIS uniquely identified by the specified
-     * <tt>sessionId</tt>.
+     * {@code sessionId}.
      *
      * @param sessionId the system-wide unique identifier of the Session object to retrieve
from
      *                  the EIS.
-     * @return the persisted session in the EIS identified by <tt>sessionId</tt>.
+     * @return the persisted session in the EIS identified by {@code sessionId}.
      * @throws UnknownSessionException if there is no EIS record for any session with the
-     *                                 specified <tt>sessionId</tt>
+     *                                 specified {@code sessionId}
      */
     Session readSession(Serializable sessionId) throws UnknownSessionException;
 
     /**
      * Updates (persists) data from a previously created Session instance in the EIS identified
by
-     * <tt>{@link Session#getId() session.getId()}</tt>.  This effectively propagates
+     * {@code {@link Session#getId() session.getId()}}.  This effectively propagates
      * the data in the argument to the EIS record previously saved.
      * <p/>
      * In addition to UnknownSessionException, implementations are free to throw any other
@@ -90,7 +90,7 @@
     void update(Session session) throws UnknownSessionException;
 
     /**
-     * Deletes the associated EIS record of the specified <tt>session</tt>. 
If there never
+     * Deletes the associated EIS record of the specified {@code session}.  If there never
      * existed a session EIS record with the identifier of
      * {@link Session#getId() session.getId()}, then this method does nothing.
      *
@@ -104,10 +104,10 @@
      * <p/>
      * If there are no active sessions in the EIS, this method may return an empty collection
or {@code null}.
      * <h4>Performance</h4>
-     * This method should be as performant as possible, especially in larger systems where
there might be
+     * This method should be as efficient as possible, especially in larger systems where
there might be
      * thousands of active sessions.  Large scale/high performance
      * implementations will often return a subset of the total active sessions and perform
validation a little more
-     * frequently, rather than return a massive set and validate infrequently.  If performant
and possible, it would
+     * frequently, rather than return a massive set and validate infrequently.  If efficient
and possible, it would
      * make sense to return the oldest unstopped sessions available, ordered by
      * {@link org.apache.shiro.session.Session#getLastAccessTime() lastAccessTime}.
      * <h4>Smart Results</h4>
@@ -115,17 +115,17 @@
      * Typically that is any session that is not stopped and where its lastAccessTimestamp
is older than the session
      * timeout.
      * <p/>
-     * For example, if sessions were backed by a relational database or SQL-92 'queryable'
enterprise cache, you might
+     * For example, if sessions were backed by a relational database or SQL-92 'query-able'
enterprise cache, you might
      * return something similar to the results returned by this query (assuming
      * {@link org.apache.shiro.session.mgt.SimpleSession SimpleSession}s were being stored):
      * <pre>
      * select * from sessions s where s.lastAccessTimestamp < ? and s.stopTimestamp is
null
      * </pre>
-     * where the <code>?</code> parameter is a date instance equal to 'now' minus
the session timeout
+     * where the {@code ?} parameter is a date instance equal to 'now' minus the session
timeout
      * (e.g. now - 30 minutes).
      *
-     * @return a Collection of <tt>Session</tt>s that are considered active,
or an
-     *         empty collection or <tt>null</tt> if there are no active sessions.
+     * @return a Collection of {@code Session}s that are considered active, or an
+     *         empty collection or {@code null} if there are no active sessions.
      */
     Collection<Session> getActiveSessions();
 }



Mime
View raw message