100% JavaDoc coverage
git-svn-id: https://svn.apache.org/repos/asf/incubator/jsecurity/trunk@711114 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/src/org/jsecurity/authz/ModularRealmAuthorizer.java b/src/org/jsecurity/authz/ModularRealmAuthorizer.java
index cd07632..43b3a0b 100644
--- a/src/org/jsecurity/authz/ModularRealmAuthorizer.java
+++ b/src/org/jsecurity/authz/ModularRealmAuthorizer.java
@@ -35,21 +35,38 @@
*/
public class ModularRealmAuthorizer implements Authorizer, PermissionResolverAware {
- //TODO - JavaDoc methods
-
+ /**
+ * The realms to consult during any authorization check.
+ */
protected Collection<Realm> realms;
+ /**
+ * Default no-argument constructor, does nothing.
+ */
public ModularRealmAuthorizer() {
}
+ /**
+ * Constructor that accepts the <code>Realm</code>s to consult during an authorization check. Immediately calls
+ * {@link #setRealms setRealms(realms)}.
+ * @param realms the realms to consult during an authorization check.
+ */
public ModularRealmAuthorizer(Collection<Realm> realms) {
setRealms(realms);
}
+ /**
+ * Returns the realms wrapped by this <code>Authorizer</code> which are consulted during an authorization check.
+ * @return the realms wrapped by this <code>Authorizer</code> which are consulted during an authorization check.
+ */
public Collection<Realm> getRealms() {
return this.realms;
}
+ /**
+ * Sets the realms wrapped by this <code>Authorizer</code> which are consulted during an authorization check.
+ * @param realms the realms wrapped by this <code>Authorizer</code> which are consulted during an authorization check.
+ */
public void setRealms(Collection<Realm> realms) {
this.realms = realms;
}
@@ -69,6 +86,13 @@
}
}
+ /**
+ * Sets the specified {@link PermissionResolver PermissionResolver} on any of the wrapped realms that implement
+ * the {@link org.jsecurity.authz.permission.PermissionResolverAware PermissionResolverAware} interface.
+ *
+ * @param permissionResolver the permissionResolver to set on all of the wrapped realms that implement the
+ * {@link org.jsecurity.authz.permission.PermissionResolverAware PermissionResolverAware} interface.
+ */
public void setPermissionResolver(PermissionResolver permissionResolver) {
Collection<Realm> realms = getRealms();
if (realms != null && !realms.isEmpty()) {
@@ -80,6 +104,11 @@
}
}
+ /**
+ * Returns <code>true</code> if any of the configured realms'
+ * {@link Realm#isPermitted(org.jsecurity.subject.PrincipalCollection, String)} returns <code>true</code>,
+ * <code>false</code> otherwise.
+ */
public boolean isPermitted(PrincipalCollection principals, String permission) {
assertRealmsConfigured();
for (Realm realm : getRealms()) {
@@ -90,6 +119,11 @@
return false;
}
+ /**
+ * Returns <code>true</code> if any of the configured realms'
+ * {@link Realm#isPermitted(org.jsecurity.subject.PrincipalCollection, Permission)} call returns <code>true</code>,
+ * <code>false</code> otherwise.
+ */
public boolean isPermitted(PrincipalCollection principals, Permission permission) {
assertRealmsConfigured();
for (Realm realm : getRealms()) {
@@ -100,6 +134,11 @@
return false;
}
+ /**
+ * Returns <code>true</code> if any of the configured realms'
+ * {@link Realm#isPermitted(org.jsecurity.subject.PrincipalCollection, String[])} call returns <code>true</code>,
+ * <code>false</code> otherwise.
+ */
public boolean[] isPermitted(PrincipalCollection principals, String... permissions) {
if (permissions != null && permissions.length > 0) {
boolean[] isPermitted = new boolean[permissions.length];
@@ -111,6 +150,11 @@
return new boolean[0];
}
+ /**
+ * Returns <code>true</code> if any of the configured realms'
+ * {@link Realm#isPermitted(org.jsecurity.subject.PrincipalCollection, List<Permission>)} call returns <code>true</code>,
+ * <code>false</code> otherwise.
+ */
public boolean[] isPermitted(PrincipalCollection principals, List<Permission> permissions) {
if (permissions != null && !permissions.isEmpty()) {
boolean[] isPermitted = new boolean[permissions.size()];
@@ -124,6 +168,11 @@
return new boolean[0];
}
+ /**
+ * Returns <code>true</code> if any of the configured realms'
+ * {@link Realm#isPermitted(org.jsecurity.subject.PrincipalCollection, String)} call returns <code>true</code>
+ * for <em>all</em> of the specified string permissions, <code>false</code> otherwise.
+ */
public boolean isPermittedAll(PrincipalCollection principals, String... permissions) {
if (permissions != null && permissions.length > 0) {
for (String perm : permissions) {
@@ -135,6 +184,11 @@
return true;
}
+ /**
+ * Returns <code>true</code> if any of the configured realms'
+ * {@link Realm#isPermitted(org.jsecurity.subject.PrincipalCollection, Permission)} call returns <code>true</code>
+ * for <em>all</em> of the specified Permissions, <code>false</code> otherwise.
+ */
public boolean isPermittedAll(PrincipalCollection principals, Collection<Permission> permissions) {
if (permissions != null && !permissions.isEmpty()) {
for (Permission permission : permissions) {
@@ -146,18 +200,30 @@
return true;
}
+ /**
+ * If !{@link #isPermitted(org.jsecurity.subject.PrincipalCollection, String) isPermitted(permission)}, throws
+ * an <code>UnauthorizedException</code> otherwise returns quietly.
+ */
public void checkPermission(PrincipalCollection principals, String permission) throws AuthorizationException {
if (!isPermitted(principals, permission)) {
throw new UnauthorizedException("Subject does not have permission [" + permission + "]");
}
}
+ /**
+ * If !{@link #isPermitted(org.jsecurity.subject.PrincipalCollection, Permission) isPermitted(permission)}, throws
+ * an <code>UnauthorizedException</code> otherwise returns quietly.
+ */
public void checkPermission(PrincipalCollection principals, Permission permission) throws AuthorizationException {
if (!isPermitted(principals, permission)) {
throw new UnauthorizedException("Subject does not have permission [" + permission + "]");
}
}
+ /**
+ * If !{@link #isPermitted(org.jsecurity.subject.PrincipalCollection, String[]) isPermitted(permission)}, throws
+ * an <code>UnauthorizedException</code> otherwise returns quietly.
+ */
public void checkPermissions(PrincipalCollection principals, String... permissions) throws AuthorizationException {
if (permissions != null && permissions.length > 0) {
for (String perm : permissions) {
@@ -166,6 +232,11 @@
}
}
+ /**
+ * If !{@link #isPermitted(org.jsecurity.subject.PrincipalCollection, Permission) isPermitted(permission)} for
+ * <em>all</em> the given Permissions, throws
+ * an <code>UnauthorizedException</code> otherwise returns quietly.
+ */
public void checkPermissions(PrincipalCollection principals, Collection<Permission> permissions) throws AuthorizationException {
if (permissions != null) {
for (Permission permission : permissions) {
@@ -174,6 +245,11 @@
}
}
+ /**
+ * Returns <code>true</code> if any of the configured realms'
+ * {@link Realm#hasRole(org.jsecurity.subject.PrincipalCollection, String)} call returns <code>true</code>,
+ * <code>false</code> otherwise.
+ */
public boolean hasRole(PrincipalCollection principals, String roleIdentifier) {
assertRealmsConfigured();
for (Realm realm : getRealms()) {
@@ -184,20 +260,28 @@
return false;
}
+ /**
+ * Calls {@link #hasRole(org.jsecurity.subject.PrincipalCollection, String)} for each role name in the specified
+ * collection and places the return value from each call at the respective location in the returned array.
+ */
public boolean[] hasRoles(PrincipalCollection principals, List<String> roleIdentifiers) {
if (roleIdentifiers != null && !roleIdentifiers.isEmpty()) {
- boolean[] isPermitted = new boolean[roleIdentifiers.size()];
+ boolean[] hasRoles = new boolean[roleIdentifiers.size()];
int i = 0;
for (String roleId : roleIdentifiers) {
- isPermitted[i++] = hasRole(principals, roleId);
+ hasRoles[i++] = hasRole(principals, roleId);
}
- return isPermitted;
+ return hasRoles;
}
return new boolean[0];
}
-
+ /**
+ * Returns <code>true</code> iff any of the configured realms'
+ * {@link Realm#hasRole(org.jsecurity.subject.PrincipalCollection, String)} call returns <code>true</code> for
+ * <em>all</em> roles specified, <code>false</code> otherwise.
+ */
public boolean hasAllRoles(PrincipalCollection principals, Collection<String> roleIdentifiers) {
for (String roleIdentifier : roleIdentifiers) {
if (!hasRole(principals, roleIdentifier)) {
@@ -207,12 +291,19 @@
return true;
}
+ /**
+ * If !{@link #hasRole(org.jsecurity.subject.PrincipalCollection, String) hasRole(role)}, throws
+ * an <code>UnauthorizedException</code> otherwise returns quietly.
+ */
public void checkRole(PrincipalCollection principals, String role) throws AuthorizationException {
if (!hasRole(principals, role)) {
throw new UnauthorizedException("Subject does not have role [" + role + "]");
}
}
+ /**
+ * Calls {@link #checkRole(org.jsecurity.subject.PrincipalCollection, String) checkRole} for each role specified.
+ */
public void checkRoles(PrincipalCollection principals, Collection<String> roles) throws AuthorizationException {
if (roles != null) {
for (String role : roles) {
diff --git a/src/org/jsecurity/crypto/hash/AbstractHash.java b/src/org/jsecurity/crypto/hash/AbstractHash.java
index d1d8eb9..7475b70 100644
--- a/src/org/jsecurity/crypto/hash/AbstractHash.java
+++ b/src/org/jsecurity/crypto/hash/AbstractHash.java
@@ -42,10 +42,12 @@
*/
public abstract class AbstractHash extends CodecSupport implements Hash {
+ /** The hashed data */
private byte[] bytes = null;
- //cache string ops to ensure multiple calls won't incur repeated overhead:
+ /** Cached value of the {@link #toHex() toHex()} call so multiple calls won't incur repeated overhead. */
private String hexEncoded = null;
+ /** Cached value of the {@link #toBase64() toBase64()} call so multiple calls won't incur repeated overhead. */
private String base64Encoded = null;
/**
@@ -213,8 +215,8 @@
* 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.
- * (However, calling {@link #setBytes setBytes} will null the cached value, forcing it to be recalculated the
- * next time this method is called).
+ * However, calling {@link #setBytes setBytes} will null the cached value, forcing it to be recalculated the
+ * next time this method is called.
*
* @return a hex-encoded string of the underlying {@link #getBytes byte array}.
*/
@@ -229,8 +231,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.
- * (However, calling {@link #setBytes setBytes} will null the cached value, forcing it to be recalculated the
- * next time this method is called).
+ * However, calling {@link #setBytes setBytes} will null the cached value, forcing it to be recalculated the
+ * next time this method is called.
*
* @return a Base64-encoded string of the underlying {@link #getBytes byte array}.
*/
diff --git a/src/org/jsecurity/session/mgt/eis/CachingSessionDAO.java b/src/org/jsecurity/session/mgt/eis/CachingSessionDAO.java
index cdeb3c6..002cc99 100644
--- a/src/org/jsecurity/session/mgt/eis/CachingSessionDAO.java
+++ b/src/org/jsecurity/session/mgt/eis/CachingSessionDAO.java
@@ -43,16 +43,28 @@
*/
public abstract class CachingSessionDAO implements SessionDAO, CacheManagerAware {
- //TODO - complete JavaDoc
-
+ /**
+ * The default active sessions cache name, equal to <code>jsecurity-activeSessionCache</code>.
+ */
public static final String ACTIVE_SESSION_CACHE_NAME = "jsecurity-activeSessionCache";
+ /**
+ * The CacheManager to use to acquire the Session cache.
+ */
private CacheManager cacheManager;
+
+ /**
+ * The Cache instance responsible for caching Sessions.
+ */
private Cache activeSessions;
+
+ /**
+ * The name of the session cache, defaults to {@link #ACTIVE_SESSION_CACHE_NAME}.
+ */
private String activeSessionsCacheName = ACTIVE_SESSION_CACHE_NAME;
/**
- * JavaBeans compatible constructor.
+ * Default no-arg constructor.
*/
public CachingSessionDAO() {
}
@@ -77,18 +89,41 @@
return cacheManager;
}
+ /**
+ * Returns the name of the actives sessions cache to be returned by the <code>CacheManager</code>. Unless
+ * overridden by {@link #setActiveSessionsCacheName(String)}, defaults to {@link #ACTIVE_SESSION_CACHE_NAME}.
+ * @return the name of the active sessions cache.
+ */
public String getActiveSessionsCacheName() {
return activeSessionsCacheName;
}
+ /**
+ * Sets the name of the active sessions cache to be returned by the <code>CacheManager</code>. Defaults to
+ * {@link #ACTIVE_SESSION_CACHE_NAME}.
+ * @param activeSessionsCacheName the name of the active sessions cache to be returned by the <code>CacheManager</code>.
+ */
public void setActiveSessionsCacheName(String activeSessionsCacheName) {
this.activeSessionsCacheName = activeSessionsCacheName;
}
+ /**
+ * Returns the cache instance to use for storing active sessions.
+ * @return the cache instance to use for storing active sessions.
+ */
public Cache getActiveSessionsCache() {
return this.activeSessions;
}
+ /**
+ * Returns the active sessions cache, but if that cache instance is null, first lazily creates the cache instance
+ * via the {@link #createActiveSessionsCache()} method and then returns the instance.
+ * <p/>
+ * Note that this method will only return a non-null value code if the <code>CacheManager</code> has been set. If
+ * not set, there will be no cache.
+ *
+ * @return the active sessions cache instance.
+ */
protected Cache getActiveSessionsCacheLazy() {
if (this.activeSessions == null) {
this.activeSessions = createActiveSessionsCache();
@@ -96,10 +131,23 @@
return this.activeSessions;
}
+ /**
+ * Sets the cache instance to use for storing active sessions.
+ * @param cache the cache instance to use for storing active sessions.
+ */
public void setActiveSessionsCache(Cache cache) {
this.activeSessions = cache;
}
+ /**
+ * Creates a cache instance used to store active sessions. Creation is done by first
+ * {@link #getCacheManager() acquiring} the <code>CacheManager</code>. If the cache manager is not null, the
+ * cache returned is that resulting from the following call:
+ * <pre> String name = {@link #getActiveSessionsCacheName() getActiveSessionsCacheName()};
+ * cacheManager.getCache(name);</pre>
+ * @return a cache instance used to store active sessions, or <em>null</code> if the <code>CacheManager</code> has
+ * not been set.
+ */
protected Cache createActiveSessionsCache() {
Cache cache = null;
CacheManager mgr = getCacheManager();
@@ -123,6 +171,14 @@
return sessionId;
}
+ /**
+ * Returns the cached session with the corresponding <code>sessionId</code> or <code>null</code> if there is
+ * no session cached under that id (or if there is no Cache).
+ *
+ * @param sessionId the id of the cached session to acquire.
+ * @return the cached session with the corresponding <code>sessionId</code>, or <code>null</code> if the session
+ * does not exist or is not cached.
+ */
protected Session getCachedSession(Serializable sessionId) {
Session cached = null;
if (sessionId != null) {
@@ -134,10 +190,25 @@
return cached;
}
+ /**
+ * Returns the Session with the specified id from the specified cache. This method simply calls
+ * <code>cache.get(sessionId)</code> and can be overridden by subclasses for custom acquisition behavior.
+ * @param sessionId the id of the session to acquire.
+ * @param cache the cache to acquire the session from
+ * @return the cached session, or <code>null</code> if the session wasn't in the cache.
+ */
protected Session getCachedSession(Serializable sessionId, Cache cache) {
return (Session) cache.get(sessionId);
}
+ /**
+ * Caches the specified session under the key <code>sessionId</code>. If the Session is an instance of
+ * {@link org.jsecurity.session.mgt.ValidatingSession ValidatingSession}, it will only be cached if the
+ * session is {@link org.jsecurity.session.mgt.ValidatingSession#isValid() valid}.
+ *
+ * @param session the session to cache
+ * @param sessionId the id of the session, to be used as the cache key.
+ */
protected void cacheValidSession(Session session, Serializable sessionId) {
if (session == null || sessionId == null) {
return;
@@ -155,6 +226,14 @@
}
}
+ /**
+ * Caches the specified session in the given cache under the key of <code>sessionId</code>. This implementation
+ * simply calls <code>cache.put(sessionId, session)</code> and can be overridden for custom behavior.
+ *
+ * @param session the session to cache
+ * @param sessionId the id of the session, expected to be the cache key.
+ * @param cache the cache to store the session
+ */
protected void cache(Session session, Serializable sessionId, Cache cache) {
cache.put(sessionId, session);
}
@@ -277,6 +356,11 @@
*/
protected abstract void doDelete(Session session);
+ /**
+ * Removes the specified Session from the cache.
+ *
+ * @param session the session to remove from the cache.
+ */
protected void uncache(Session session) {
if (session == null) {
return;
diff --git a/support/ehcache/src/org/jsecurity/cache/ehcache/EhCacheManager.java b/support/ehcache/src/org/jsecurity/cache/ehcache/EhCacheManager.java
index 9efc0e1..7b0e1f9 100644
--- a/support/ehcache/src/org/jsecurity/cache/ehcache/EhCacheManager.java
+++ b/support/ehcache/src/org/jsecurity/cache/ehcache/EhCacheManager.java
@@ -32,7 +32,12 @@
import java.io.InputStream;
/**
- * <p>JSecurity <code>CacheManager</code> implementation utilizing the Ehcache framework for all cache functionality.</p>
+ * JSecurity <code>CacheManager</code> implementation utilizing the Ehcache framework for all cache functionality.
+ * <p/>
+ * This class can {@link #setCacheManager(net.sf.ehcache.CacheManager) accept} a manually configured
+ * {@link net.sf.ehcache.CacheManager net.sf.ehcache.CacheManager} instance,
+ * or an <code>ehcache.xml</code> path location can be specified instead and one will be constructed. If neither are
+ * specified, JSecurity's failsafe <code><a href="./ehcache.xml">ehcache.xml</a></code> file will be used by default.
*
* <p>This implementation requires EhCache 1.2 and above. Make sure EhCache 1.1 or earlier
* is not in the classpath or it will not work.</p>
@@ -46,24 +51,46 @@
*/
public class EhCacheManager implements CacheManager, Initializable, Destroyable {
- //TODO - complete JavaDoc
-
+ /**
+ * The default name for the active sessions cache, equal to
+ * {@link CachingSessionDAO#ACTIVE_SESSION_CACHE_NAME CachingSessionDAO.ACTIVE_SESSION_CACHE_NAME}.
+ */
public static final String DEFAULT_ACTIVE_SESSIONS_CACHE_NAME = CachingSessionDAO.ACTIVE_SESSION_CACHE_NAME;
+
+ /**
+ * The default maximum number of active sessions in cache <em>memory</em>, equal to <code>20,000</code>.
+ */
public static final int DEFAULT_ACTIVE_SESSIONS_CACHE_MAX_ELEM_IN_MEM = 20000;
+
+ /**
+ * The default time the active sessions disk expiration thread will run, equal to <code>600</code> (10 minutes).
+ */
public static final int DEFAULT_ACTIVE_SESSIONS_DISK_EXPIRY_THREAD_INTERVAL_SECONDS = 600;
+ /**
+ * This class's private log instance.
+ */
private static final Log log = LogFactory.getLog(EhCacheManager.class);
/**
* The EhCache cache manager used by this implementation to create caches.
*/
protected net.sf.ehcache.CacheManager manager;
- private boolean cacheManagerImplicitlyCreated = false;
+
/**
- * Classpath file location.
+ * Indicates if the CacheManager instance was implicitly/automatically created by this instance, indicating that
+ * it should be automatically cleaned up as well on shutdown.
+ */
+ private boolean cacheManagerImplicitlyCreated = false;
+
+ /**
+ * Classpath file location of the ehcache CacheManager config file.
*/
private String cacheManagerConfigFile = "classpath:org/jsecurity/cache/ehcache/ehcache.xml";
+ /**
+ * Default no argument constructor
+ */
public EhCacheManager() {
}
@@ -115,6 +142,13 @@
this.cacheManagerConfigFile = classpathLocation;
}
+ /**
+ * Acquires the InputStream for the ehcache configuration file using
+ * {@link ResourceUtils#getInputStreamForPath(String) ResourceUtils.getInputStreamForPath} with the
+ * path returned from {@link #getCacheManagerConfigFile() getCacheManagerConfigFile()}.
+ *
+ * @return the InputStream for the ehcache configuration file.
+ */
protected InputStream getCacheManagerConfigFileInputStream() {
String configFile = getCacheManagerConfigFile();
try {
