javadoc and renamed FilterChainWrapper to ProxiedFilterChain
git-svn-id: https://svn.apache.org/repos/asf/incubator/jsecurity/trunk@711116 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/changes.txt b/changes.txt
index 7326f09..5ae847e 100644
--- a/changes.txt
+++ b/changes.txt
@@ -2,6 +2,7 @@
* org.jsecurity.spring.SpringWebConfiguration renamed to org.jsecurity.spring.SpringIniWebConfiguration
* org.jsecurity.util.ThreadContext fixed to correctly work in child/spawned threads from a parent thread (sometimes surfaced in Tomcat environments)
+* org.jsecurity.web.servlet.FilterChainWrapper renamed to org.jsecurity.web.servlet.ProxiedFilterChain to maintain parallel naming conventions with ProxiedSession.
[0.9 RC2]
diff --git a/src/org/jsecurity/authc/pam/AtLeastOneSuccessfulModularAuthenticationStrategy.java b/src/org/jsecurity/authc/pam/AtLeastOneSuccessfulModularAuthenticationStrategy.java
index 4b7bee2..0206507 100644
--- a/src/org/jsecurity/authc/pam/AtLeastOneSuccessfulModularAuthenticationStrategy.java
+++ b/src/org/jsecurity/authc/pam/AtLeastOneSuccessfulModularAuthenticationStrategy.java
@@ -44,7 +44,7 @@
/**
* 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
+ * is not <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 {
diff --git a/src/org/jsecurity/authc/pam/ModularAuthenticationStrategy.java b/src/org/jsecurity/authc/pam/ModularAuthenticationStrategy.java
index 4e34df4..4676b06 100644
--- a/src/org/jsecurity/authc/pam/ModularAuthenticationStrategy.java
+++ b/src/org/jsecurity/authc/pam/ModularAuthenticationStrategy.java
@@ -34,8 +34,9 @@
* attempt must be successful for all realms, only 1 or more realms, no realms, etc.
*
* @author Les Hazlewood
- * @see AllSuccessfulModularAuthenticationStrategy
- * @see AtLeastOneSuccessfulModularAuthenticationStrategy
+ * @see org.jsecurity.authc.pam.AllSuccessfulModularAuthenticationStrategy AllSuccessfulModularAuthenticationStrategy
+ * @see org.jsecurity.authc.pam.AtLeastOneSuccessfulModularAuthenticationStrategy AtLeastOneSuccessfulModularAuthenticationStrategy
+ * @see org.jsecurity.authc.pam.FirstSuccessfulAuthenticationStrategy FirstSuccessfulAuthenticationStrategy
* @since 0.2
*/
public interface ModularAuthenticationStrategy {
diff --git a/src/org/jsecurity/io/IniResource.java b/src/org/jsecurity/io/IniResource.java
index 28b2f78..c64ec0f 100644
--- a/src/org/jsecurity/io/IniResource.java
+++ b/src/org/jsecurity/io/IniResource.java
@@ -45,10 +45,9 @@
public static final String HEADER_PREFIX = "[";
public static final String HEADER_SUFFIX = "]";
- protected Map<String, Map<String, String>> sections;
+ protected Map<String, Map<String, String>> sections = new LinkedHashMap<String, Map<String, String>>();
public IniResource() {
- sections = new LinkedHashMap<String, Map<String, String>>();
}
public IniResource(String configBodyOrResourcePath) {
diff --git a/src/org/jsecurity/mgt/AuthenticatingSecurityManager.java b/src/org/jsecurity/mgt/AuthenticatingSecurityManager.java
index 4738e80..a7c6aef 100644
--- a/src/org/jsecurity/mgt/AuthenticatingSecurityManager.java
+++ b/src/org/jsecurity/mgt/AuthenticatingSecurityManager.java
@@ -44,41 +44,54 @@
public abstract class AuthenticatingSecurityManager extends RealmSecurityManager
implements AuthenticationListenerRegistrar {
- //TODO - complete JavaDoc
-
+ /**
+ * The internal <code>Authenticator</code> delegate instance that this SecurityManager instance will use
+ * to perform all authentication operations.
+ */
private Authenticator authenticator;
/**
- * Default no-arg constructor.
+ * Default no-arg constructor that initializes its internal
+ * <code>authenticator</code> instance to be a {@link ModularRealmAuthenticator ModularRealmAuthenticator}.
*/
public AuthenticatingSecurityManager() {
- ensureAuthenticator();
+ this.authenticator = new ModularRealmAuthenticator();
}
+ /**
+ * Returns the delegate <code>Authenticator</code> instance that this SecurityManager uses to perform all
+ * authentication operations. Unless overridden by the
+ * {@link #setAuthenticator(org.jsecurity.authc.Authenticator) setAuthenticator}, the default instance is a
+ * {@link org.jsecurity.authc.pam.ModularRealmAuthenticator ModularRealmAuthenticator}.
+ * @return the delegate <code>Authenticator</code> instance that this SecurityManager uses to perform all
+ * authentication operations.
+ */
public Authenticator getAuthenticator() {
return authenticator;
}
- public void setAuthenticator(Authenticator authenticator) {
+ /**
+ * Sets the delegate <code>Authenticator</code> instance that this SecurityManager uses to perform all
+ * authentication operations. Unless overridden by this method, the default instance is a
+ * {@link org.jsecurity.authc.pam.ModularRealmAuthenticator ModularRealmAuthenticator}.
+ * @param authenticator the delegate <code>Authenticator</code> instance that this SecurityManager will use to
+ * perform all authentication operations.
+ * @throws IllegalArgumentException if the argument is <code>null</code>.
+ */
+ public void setAuthenticator(Authenticator authenticator) throws IllegalArgumentException {
if (authenticator == null) {
- String msg = "Authenticator instance cannot be null.";
+ String msg = "Authenticator argument cannot be null.";
throw new IllegalArgumentException(msg);
}
this.authenticator = authenticator;
}
- protected void ensureAuthenticator() {
- Authenticator authc = getAuthenticator();
- if (authc == null) {
- authc = createAuthenticator();
- setAuthenticator(authc);
- }
- }
-
- protected Authenticator createAuthenticator() {
- return new ModularRealmAuthenticator();
- }
-
+ /**
+ * Sets the {@link org.jsecurity.authc.pam.ModularAuthenticationStrategy ModularAuthenticationStrategy} to use
+ * in multi-realm environments.
+ *
+ * @param strategy the <code>ModularAuthenticationStrategy</code> to use in multi-realm environments.
+ */
public void setModularAuthenticationStrategy(ModularAuthenticationStrategy strategy) {
if (!(this.authenticator instanceof ModularRealmAuthenticator)) {
String msg = "Configuring a ModularAuthenticationStrategy is only applicable when the underlying " +
@@ -124,6 +137,11 @@
((AuthenticationListenerRegistrar) this.authenticator).setAuthenticationListeners(listeners);
}
+ /**
+ * Ensures that <code>this.authenticator</code> implements the
+ * {@link org.jsecurity.authc.AuthenticationListenerRegistrar AuthenticationListenerRegistrar} interface to ensure
+ * listeners can be registered.
+ */
private void assertAuthenticatorListenerSupport() {
if (!(this.authenticator instanceof AuthenticationListenerRegistrar)) {
String msg = "AuthenticationListener registration failed: The underlying Authenticator instance of " +
@@ -146,6 +164,13 @@
((AuthenticationListenerRegistrar) authc).remove(listener);
}
+ /**
+ * Immediately calls {@link RealmSecurityManager#setRealms(java.util.Collection) super.setRealms} and then
+ * additionally passes on those realms to the internal delegate <code>Authenticator</code> instance so
+ * that it may use them during authentication attempts.
+ * @param realms realms the realms managed by this <tt>SecurityManager</tt> instance and subsequently the internal
+ * delegate <code>Authenticator</code> instance.
+ */
public void setRealms(Collection<Realm> realms) {
super.setRealms(realms);
if (this.authenticator instanceof ModularRealmAuthenticator) {
@@ -153,14 +178,25 @@
}
}
+ /**
+ * Lifecycle cleanup method that first calls {@link #beforeAuthenticatorDestroyed() beforeAuthenticatorDestroyed()}
+ * to allow subclass cleanup and then calls {@link #destroyAuthenticator() destroyAuthenticator()} to actually
+ * clean up the internal delegate instance.
+ */
protected void beforeRealmsDestroyed() {
beforeAuthenticatorDestroyed();
destroyAuthenticator();
}
+ /**
+ * Template hook to allow subclass cleanup when the SecurityManager is being shut down.
+ */
protected void beforeAuthenticatorDestroyed() {
}
+ /**
+ * Cleans up ('destroys') the internal delegate <code>Authenticator</code> instance. Called during shut down.
+ */
protected void destroyAuthenticator() {
LifecycleUtils.destroy(getAuthenticator());
}
diff --git a/src/org/jsecurity/mgt/CachingSecurityManager.java b/src/org/jsecurity/mgt/CachingSecurityManager.java
index 999b34d..efc4121 100644
--- a/src/org/jsecurity/mgt/CachingSecurityManager.java
+++ b/src/org/jsecurity/mgt/CachingSecurityManager.java
@@ -41,15 +41,18 @@
*/
public abstract class CachingSecurityManager implements SecurityManager, Destroyable, CacheManagerAware {
- //TODO - complete JavaDoc
-
+ /**
+ * Internal private static log instance.
+ */
private static final Log log = LogFactory.getLog(CachingSecurityManager.class);
+ /**
+ * The CacheManager to use to perform caching operations to enhance performance. Can be null.
+ */
protected CacheManager cacheManager;
/**
* Default no-arg constructor that will automatically attempt to initialize a default cacheManager
- * by calling {@link #ensureCacheManager() ensureCacheManager()}.
*/
public CachingSecurityManager() {
ensureCacheManager();
@@ -148,14 +151,25 @@
return manager;
}
+ /**
+ * First calls {@link #beforeCacheManagerDestroyed() beforeCacheManagerDestroyed()} to allow subclasses to clean up
+ * first, then calls {@link #destroyCacheManager() destroyCacheManager()} to clean up the internal
+ * {@link CacheManager CacheManager}.
+ */
public void destroy() {
beforeCacheManagerDestroyed();
destroyCacheManager();
}
+ /**
+ * Template hook for subclasses to perform cleanup behavior during shutdown.
+ */
protected void beforeCacheManagerDestroyed() {
}
+ /**
+ * Cleans up the internal <code>CacheManager</code> instance during shutdown.
+ */
protected void destroyCacheManager() {
LifecycleUtils.destroy(getCacheManager());
}
diff --git a/src/org/jsecurity/mgt/RealmSecurityManager.java b/src/org/jsecurity/mgt/RealmSecurityManager.java
index 04f4aeb..efc1cb5 100644
--- a/src/org/jsecurity/mgt/RealmSecurityManager.java
+++ b/src/org/jsecurity/mgt/RealmSecurityManager.java
@@ -39,10 +39,14 @@
*/
public abstract class RealmSecurityManager extends CachingSecurityManager {
- //TODO - complete JavaDoc
+ /**
+ * Internal private log instance.
+ */
+ private static final Log log = LogFactory.getLog(RealmSecurityManager.class);
- private static final Log log = LogFactory.getLog(RealmSecurityManager.class);
-
+ /**
+ * Internal collection of <code>Realm</code>s used for all authentication and authorization operations.
+ */
protected Collection<Realm> realms;
/**
@@ -83,6 +87,13 @@
applyCacheManagerToRealms();
}
+ /**
+ * Ensures at least one realm exists, and if not calls {@link #createDefaultRealm() createDefaultRealm()} and sets
+ * it on this instance via the {@link #setRealm(Realm) setRealm} method.
+ * <p/>
+ * This method is used to lazily ensure at least one default Realm exists in all environments, even if it is just
+ * with demo data, to ensure that JSecurity is usuable with the smallest (even no) configuration.
+ */
protected void ensureRealms() {
Collection<Realm> realms = getRealms();
if (realms == null || realms.isEmpty()) {
@@ -94,6 +105,13 @@
}
}
+ /**
+ * Creates a default Realm implementation to use in lazy-initialization use cases.
+ * <p/>
+ * The implementation returned is a {@link PropertiesRealm PropertiesRealm}, which supports very simple
+ * properties-based user/role/permission configuration in testing, sample, and simple applications.
+ * @return the default Realm implementation (a {@link PropertiesRealm PropertiesRealm} to use in lazy-init use cases.
+ */
protected Realm createDefaultRealm() {
PropertiesRealm realm;
CacheManager cacheManager = getCacheManager();
@@ -114,6 +132,18 @@
return realms;
}
+ /**
+ * Sets the internal {@link #getCacheManager CacheManager} on any internal configured
+ * {@link #getRealms Realms} that implement the {@link CacheManagerAware CacheManagerAware} interface.
+ * <p/>
+ * This method is called after setting a cacheManager on this securityManager via the
+ * {@link #setCacheManager(org.jsecurity.cache.CacheManager) setCacheManager} method to allow it to be propagated
+ * down to all the internal Realms that would need to use it.
+ * <p/>
+ * It is also called after setting one or more realms via the {@link #setRealm setRealm} or
+ * {@link #setRealms setRealms} methods to allow these newly available realms to be given the cache manager
+ * already in use.
+ */
protected void applyCacheManagerToRealms() {
CacheManager cacheManager = getCacheManager();
Collection<Realm> realms = getRealms();
@@ -126,25 +156,38 @@
}
}
+ /**
+ * Simply calls {@link #applyCacheManagerToRealms() applyCacheManagerToRealms()} to allow the
+ * newly set {@link CacheManager CacheManager} to be propagated to the internal collection of <code>Realm</code>
+ * that would need to use it.
+ *
+ */
protected void afterCacheManagerSet() {
applyCacheManagerToRealms();
}
+ /**
+ * First calls {@link #beforeRealmsDestroyed() beforeRealmsDestroyed()} to allow subclasses to clean up
+ * first, then calls {@link #destroyRealms() destroyRealms()} to clean up the internal <code>Realm</code>s
+ * collection.
+ */
protected void beforeCacheManagerDestroyed() {
beforeRealmsDestroyed();
destroyRealms();
}
+ /**
+ * Template hook for subclasses to perform clean up logic during shut-down.
+ */
protected void beforeRealmsDestroyed() {
}
+ /**
+ * Cleans up ('destroys') the internal collection of Realms by calling
+ * {@link LifecycleUtils#destroy(Collection) LifecycleUtils.destroy(getRealms())}.
+ */
protected void destroyRealms() {
- Collection<Realm> realms = getRealms();
- if (realms != null && !realms.isEmpty()) {
- for (Realm realm : realms) {
- LifecycleUtils.destroy(realm);
- }
- }
+ LifecycleUtils.destroy(getRealms());
this.realms = null;
}
diff --git a/src/org/jsecurity/mgt/SecurityManager.java b/src/org/jsecurity/mgt/SecurityManager.java
index bd64254..5a23e7d 100644
--- a/src/org/jsecurity/mgt/SecurityManager.java
+++ b/src/org/jsecurity/mgt/SecurityManager.java
@@ -64,11 +64,13 @@
/**
* Logs in a user, returning a Subject instance if the authentication is successful or throwing an
* <code>AuthenticationException</code> if it is not.
- *
- * <p>Note that using this method is an alternative to calling
- * <code>{@link Subject#login(org.jsecurity.authc.AuthenticationToken) Subject.login(authenticationToken)}</code>.
- * However most application developers find calling <code>subject.login(token)</code> more convenient than calling
- * this method on the <code>SecurityManager</code> directly.
+ * <p/>
+ * Note that most application developers should probably not call this method directly unless they have a good
+ * reason for doing so. The preferred way to log in a Subject is to call
+ * <code>{@link Subject#login Subject.login(authenticationToken)}</code> (usually after acquiring the
+ * Subject by calling {@link org.jsecurity.SecurityUtils#getSubject() SecurityUtils.getSubject()}).
+ * <p/>
+ * Framework developers on the other hand might find calling this method directly useful in certain cases.
*
* @param authenticationToken the token representing the Subject's principal(s) and credential(s)
* @return an authenticated Subject upon a successful attempt
@@ -83,6 +85,8 @@
* <p>Note that most application developers should not call this method unless they have a good reason for doing
* so. The preferred way to logout a Subject is to call <code>{@link Subject#logout Subject.logout()}</code>, not
* the <code>SecurityManager</code> directly.
+ * <p/>
+ * Framework developers on the other hand might find calling this method directly useful in certain cases.
*
* @param subjectIdentifier the identifier of the subject/user to log out.
* @see #getSubject()
diff --git a/src/org/jsecurity/mgt/SecurityManagerFactory.java b/src/org/jsecurity/mgt/SecurityManagerFactory.java
index a74f663..56181c2 100644
--- a/src/org/jsecurity/mgt/SecurityManagerFactory.java
+++ b/src/org/jsecurity/mgt/SecurityManagerFactory.java
@@ -25,7 +25,9 @@
*/
public interface SecurityManagerFactory {
- //TODO - complete JavaDoc
-
+ /**
+ * Returns a fully configured and initialized <code>SecurityManager</code>.
+ * @return a fully configured and initialized <code>SecurityManager</code>.
+ */
SecurityManager getSecurityManager();
}
diff --git a/src/org/jsecurity/mgt/SessionsSecurityManager.java b/src/org/jsecurity/mgt/SessionsSecurityManager.java
index c3c77e2..e96fd5c 100644
--- a/src/org/jsecurity/mgt/SessionsSecurityManager.java
+++ b/src/org/jsecurity/mgt/SessionsSecurityManager.java
@@ -53,12 +53,15 @@
*/
public abstract class SessionsSecurityManager extends AuthorizingSecurityManager implements SessionListenerRegistrar {
- //TODO - complete JavaDoc
-
+ /**
+ * The internal delegate <code>SessionManager</code> used by this security manager that manages all the
+ * application's {@link Session Session}s.
+ */
protected SessionManager sessionManager;
/**
- * Default no-arg constructor.
+ * Default no-arg constructor, internally creates a suitable default {@link SessionManager SessionManager} delegate
+ * instance via the {@link #ensureSessionManager() ensureSessionManager()} method.
*/
public SessionsSecurityManager() {
ensureSessionManager();
@@ -81,10 +84,20 @@
this.sessionManager = sessionManager;
}
+ /**
+ * Returns this security manager's internal delegate {@link SessionManager SessionManager}.
+ * @return this security manager's internal delegate {@link SessionManager SessionManager}.
+ * @see #setSessionManager(org.jsecurity.session.mgt.SessionManager) setSessionManager
+ */
public SessionManager getSessionManager() {
return this.sessionManager;
}
+ /**
+ * Ensures that the internal delegate <code>SessionManager</code> exists, and if not, calls
+ * {@link #createSessionManager createSessionManager} and sets the resulting instance via the
+ * {@link #setSessionManager(org.jsecurity.session.mgt.SessionManager) setSessionManager} method.
+ */
protected void ensureSessionManager() {
SessionManager sessionManager = getSessionManager();
if (sessionManager == null) {
@@ -93,6 +106,16 @@
}
}
+ /**
+ * Constructs a new <code>SessionManager</code> instance to be used as the internal delegate for this security
+ * manager. After creation via the {@link #newSessionManagerInstance() newSessionManagerInstance()} call, the
+ * internal {@link #getCacheManager CacheManager} is set on it if the session manager instance implements the
+ * {@link CacheManagerAware CacheManagerAware} interface to allow it to utilize the cache manager for its own
+ * internal caching needs.
+ *
+ * @return a new initialized {@link SessionManager SessionManager} to use as this security manager's internal
+ * delegate.
+ */
protected SessionManager createSessionManager() {
SessionManager sm = newSessionManagerInstance();
CacheManager cm = getCacheManager();
@@ -104,15 +127,32 @@
return sm;
}
+ /**
+ * Merely instantiates (but does not initalize) the default <code>SessionManager</code> implementation. This method
+ * merely returns <code>new {@link DefaultSessionManager DefaultSessionManager}()</code>.
+ * @return a new, uninitialized {@link SessionManager SessionManager} instance.
+ */
protected SessionManager newSessionManagerInstance() {
return new DefaultSessionManager();
}
+ /**
+ * Calls {@link super#afterCacheManagerSet() super.afterCacheManagerSet()} and then immediately calls
+ * {@link #applyCacheManagerToSessionManager() applyCacheManagerToSessionManager()} to ensure the
+ * <code>CacheManager</code> is applied to the SessionManager as necessary.
+ */
protected void afterCacheManagerSet() {
super.afterCacheManagerSet();
applyCacheManagerToSessionManager();
}
+ /**
+ * Ensures the internal delegate <code>SessionManager</code> is injected with the newly set
+ * {@link #setCacheManager CacheManager} so it may use it for its internal caching needs.
+ * <p/>
+ * Note: This implementation only injects the CacheManager into the SessionManager if the SessionManager
+ * instance implements the {@link CacheManagerAware CacheManagerAware} interface.
+ */
protected void applyCacheManagerToSessionManager() {
SessionManager sm = getSessionManager();
if (sm instanceof CacheManagerAware) {
@@ -141,7 +181,14 @@
((SessionListenerRegistrar) this.sessionManager).setSessionListeners(sessionListeners);
}
- private void assertSessionListenerSupport() {
+ /**
+ * Ensures the internal SessionManager instance is an <code>instanceof</code>
+ * {@link org.jsecurity.session.SessionListenerRegistrar SessionListenerRegistrar} to ensure that any
+ * listeners attempting to be registered can actually do so with the internal delegate instance.
+ * @throws IllegalStateException if the internal delegate SessionManager instance does not implement the
+ * <code>SessionListenerRegistrar</code> interface.
+ */
+ private void assertSessionListenerSupport() throws IllegalStateException {
if (!(this.sessionManager instanceof SessionListenerRegistrar)) {
String msg = "SessionListener registration failed: The underlying SessionManager instance of " +
"type [" + sessionManager.getClass().getName() + "] does not implement the " +
@@ -151,25 +198,52 @@
}
}
+ /**
+ * Asserts the internal delegate <code>SessionManager</code> instance
+ * {@link #assertSessionListenerSupport() supports session listener registration} and then
+ * {@link SessionListenerRegistrar#add adds} the listener to the
+ * delegate instance.
+ * @param listener the <code>SessionListener</code> to register for session events.
+ */
public void add(SessionListener listener) {
assertSessionListenerSupport();
SessionManager sm = getSessionManager();
((SessionListenerRegistrar) sm).add(listener);
}
+ /**
+ * Removes the specified listener from receiving session events from the internal delegate
+ * {@link SessionManager} instance.
+ *
+ * @param listener the listener to remove that no longer wishes to be notified of session events.
+ * @return <code>true</code> if the listener was removed from the internal delegate <code>SessionManager</code>
+ * instance, <code>false</code> otherwise.
+ */
public boolean remove(SessionListener listener) {
SessionManager sm = getSessionManager();
return (sm instanceof SessionListenerRegistrar) &&
((SessionListenerRegistrar) sm).remove(listener);
}
+ /**
+ * Template hook for subclasses that wish to perform clean up behavior during shutdown.
+ */
protected void beforeSessionManagerDestroyed() {
}
+ /**
+ * Cleans up ('destroys') the internal delegate <code>SessionManager</code> by calling
+ * {@link LifecycleUtils#destroy LifecycleUtils.destroy(getSessionManager())}.
+ */
protected void destroySessionManager() {
LifecycleUtils.destroy(getSessionManager());
}
+ /**
+ * Calls {@link #beforeSessionManagerDestroyed() beforeSessionManagerDestroyed()} to allow subclass clean up and
+ * then immediatley calls {@link #destroySessionManager() destroySessionManager()} to clean up the internal
+ * delegate instance.
+ */
protected void beforeAuthorizerDestroyed() {
beforeSessionManagerDestroyed();
destroySessionManager();
diff --git a/src/org/jsecurity/session/SessionListenerRegistrar.java b/src/org/jsecurity/session/SessionListenerRegistrar.java
index 40ed22f..265350f 100644
--- a/src/org/jsecurity/session/SessionListenerRegistrar.java
+++ b/src/org/jsecurity/session/SessionListenerRegistrar.java
@@ -22,7 +22,7 @@
/**
* A <code>SessionListenerRegistrar</code> is a component that is capable of registering interested
- * {@link SessionListener AuthenticationListener}s that wish to be notified during
+ * {@link SessionListener SessionListener}s that wish to be notified during
* {@link Session Session} lifecycle events.
* <p/>
* This interface only guarantees that registered listeners will be notified during a <code>Session</code>'s
diff --git a/src/org/jsecurity/session/mgt/SimpleSession.java b/src/org/jsecurity/session/mgt/SimpleSession.java
index dcfa11d..f8fd8af 100644
--- a/src/org/jsecurity/session/mgt/SimpleSession.java
+++ b/src/org/jsecurity/session/mgt/SimpleSession.java
@@ -31,7 +31,7 @@
import java.util.*;
/**
- * Simple {@link org.jsecurity.session.Session} implementation, intended to be used on the business/server tier.
+ * Simple {@link org.jsecurity.session.Session} POJO implementation, intended to be used on the business/server tier.
*
* @author Les Hazlewood
* @since 0.1
diff --git a/src/org/jsecurity/subject/RememberMeManager.java b/src/org/jsecurity/subject/RememberMeManager.java
index fbc2768..eebba0b 100644
--- a/src/org/jsecurity/subject/RememberMeManager.java
+++ b/src/org/jsecurity/subject/RememberMeManager.java
@@ -23,7 +23,7 @@
import org.jsecurity.authc.AuthenticationToken;
/**
- * A RememberMeManager is responsible for remembering a Subject's identity across that subject's sessions with
+ * A RememberMeManager is responsible for remembering a Subject's identity across that Subject's sessions with
* the application.
*
* @author Les Hazlewood
diff --git a/src/org/jsecurity/util/LifecycleUtils.java b/src/org/jsecurity/util/LifecycleUtils.java
index d603514..ab212e5 100644
--- a/src/org/jsecurity/util/LifecycleUtils.java
+++ b/src/org/jsecurity/util/LifecycleUtils.java
@@ -77,7 +77,10 @@
}
/**
- * @param c
+ * Calls {@link #destroy destroy) for each object in the collection. If the collection is <code>null</code> or
+ * empty, this method returns quietly.
+ *
+ * @param c the collection of objects to {@link #destroy destroy}.
* @since 0.9
*/
public static void destroy(Collection c) {
diff --git a/src/org/jsecurity/web/config/IniWebConfiguration.java b/src/org/jsecurity/web/config/IniWebConfiguration.java
index 62040b6..2e2d1c8 100644
--- a/src/org/jsecurity/web/config/IniWebConfiguration.java
+++ b/src/org/jsecurity/web/config/IniWebConfiguration.java
@@ -37,7 +37,7 @@
import org.jsecurity.web.filter.authz.PermissionsAuthorizationFilter;
import org.jsecurity.web.filter.authz.RolesAuthorizationFilter;
import org.jsecurity.web.servlet.AdviceFilter;
-import org.jsecurity.web.servlet.FilterChainWrapper;
+import org.jsecurity.web.servlet.ProxiedFilterChain;
import javax.servlet.*;
import java.util.*;
@@ -174,7 +174,7 @@
* calls this method.
* <p/>
* The default implementation merely returns
- * <code>new {@link org.jsecurity.web.servlet.FilterChainWrapper FilterChainWrapper(filters, originalChain)}</code>,
+ * <code>new {@link org.jsecurity.web.servlet.ProxiedFilterChain FilterChainWrapper(filters, originalChain)}</code>,
* and can be overridden by subclasses for custom creation.
*
* @param filters the configured filter chain for the incoming request application path
@@ -182,7 +182,7 @@
* @return a new FilterChain based on the specified configured url filter chain and original chain.
*/
protected FilterChain createChain(List<Filter> filters, FilterChain originalChain) {
- return new FilterChainWrapper(originalChain, filters);
+ return new ProxiedFilterChain(originalChain, filters);
}
/**
diff --git a/src/org/jsecurity/web/servlet/ProxiedFilterChain.java b/src/org/jsecurity/web/servlet/ProxiedFilterChain.java
new file mode 100644
index 0000000..e6f8306
--- /dev/null
+++ b/src/org/jsecurity/web/servlet/ProxiedFilterChain.java
@@ -0,0 +1,62 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.jsecurity.web.servlet;
+
+import org.apache.commons.logging.Log;
+import org.apache.commons.logging.LogFactory;
+
+import javax.servlet.*;
+import java.io.IOException;
+import java.util.List;
+
+/**
+ * @author Les Hazlewood
+ * @since 0.9
+ */
+public class ProxiedFilterChain implements FilterChain {
+
+ //TODO - complete JavaDoc
+
+ private static final Log log = LogFactory.getLog(ProxiedFilterChain.class);
+
+ private FilterChain orig;
+ private List<Filter> filters;
+ private int index = 0;
+
+ public ProxiedFilterChain(FilterChain orig, List<Filter> filters) {
+ this.orig = orig;
+ this.filters = filters;
+ this.index = 0;
+ }
+
+ public void doFilter(ServletRequest request, ServletResponse response) throws IOException, ServletException {
+ if (this.filters == null || this.filters.size() == this.index) {
+ //we've reached the end of the wrapped chain, so invoke the original one:
+ if (log.isTraceEnabled()) {
+ log.trace("Invoking original filter chain.");
+ }
+ this.orig.doFilter(request, response);
+ } else {
+ if (log.isTraceEnabled()) {
+ log.trace("Invoking wrapped filter at index [" + this.index + "]");
+ }
+ this.filters.get(this.index++).doFilter(request, response, this);
+ }
+ }
+}
diff --git a/src/org/jsecurity/web/session/WebSessionManager.java b/src/org/jsecurity/web/session/WebSessionManager.java
index 47daa2c..b2f1fa0 100644
--- a/src/org/jsecurity/web/session/WebSessionManager.java
+++ b/src/org/jsecurity/web/session/WebSessionManager.java
@@ -25,15 +25,24 @@
import javax.servlet.ServletResponse;
/**
- * TODO - class javadoc
+ * A <code>WebSessionManager</code> is a <code>SessionManager</code> that has the ability to obtain
+ * {@link Session Session}s based on a {@link ServletRequest ServletRequest}/{@link ServletResponse ServletResponse}
+ * pair.
*
* @author Les Hazlewood
- * @since Apr 22, 2008 10:16:22 AM
+ * @since 0.9
*/
public interface WebSessionManager extends SessionManager {
- //TODO - complete JavaDoc
-
+ /**
+ * Returns the current {@link Session Session} associated with the specified request pair, or
+ * <code>null</code> if there is no session associated with the request.
+ *
+ * @param request the incoming <code>ServletRequest</code>
+ * @param response the outgoing <code>ServletResponse</code>
+ * @return the current {@link Session Session} associated with the specified request pair, or
+ * <code>null</code> if there is no session associated with the request.
+ */
Session getSession(ServletRequest request, ServletResponse response);
}
diff --git a/support/spring/src/org/jsecurity/spring/LifecycleBeanPostProcessor.java b/support/spring/src/org/jsecurity/spring/LifecycleBeanPostProcessor.java
index 5b628ef..1710f30 100644
--- a/support/spring/src/org/jsecurity/spring/LifecycleBeanPostProcessor.java
+++ b/support/spring/src/org/jsecurity/spring/LifecycleBeanPostProcessor.java
@@ -42,8 +42,9 @@
*/
public class LifecycleBeanPostProcessor implements DestructionAwareBeanPostProcessor {
- //TODO - complete JavaDoc
-
+ /**
+ * Private internal class log instance.
+ */
private static final Log log = LogFactory.getLog(LifecycleBeanPostProcessor.class);
/**
@@ -70,6 +71,9 @@
}
+ /**
+ * Does nothing - merely returns the object argument immediately.
+ */
public Object postProcessAfterInitialization(Object object, String name) throws BeansException {
// Does nothing after initialization
return object;
diff --git a/support/spring/src/org/jsecurity/spring/SpringJSecurityFilter.java b/support/spring/src/org/jsecurity/spring/SpringJSecurityFilter.java
index 8cd2221..1c9d7c5 100644
--- a/support/spring/src/org/jsecurity/spring/SpringJSecurityFilter.java
+++ b/support/spring/src/org/jsecurity/spring/SpringJSecurityFilter.java
@@ -21,7 +21,26 @@
import org.jsecurity.web.servlet.JSecurityFilter;
/**
- * <p>Extension of JSecurityFilter that uses {@link SpringIniWebConfiguration} to configure the JSecurity instance.</p>
+ * Extension of JSecurityFilter that uses {@link SpringIniWebConfiguration} to configure JSecurity in a Spring web
+ * environment.
+ * <p/>
+ * Using this class in web.xml essentially enables the following:
+ * <pre><filter>
+ * <filter-name>JSecurityFilter</filter-name>
+ * <filter-class>org.jsecurity.web.servlet.JSecurityFilter</filter-class>
+ * <init-param>
+ * <param-name>configClassName</param-name>
+ * <param-value>org.jsecurity.spring.SpringIniWebConfiguration<param-value>
+ * </init-param>
+ * <init-param>
+ * <param-name>config</param-name>
+ * <param-value>
+ * ... normal .ini config ...
+ * <param-value>
+ * </init-param>
+<filter></pre>
+ * <p/>
+ * That is, you don't have to specify the additional <code>configClassName</code> <code>init-param</code>.
*
* @author Les Hazlewood
* @author Jeremy Haile
@@ -31,6 +50,10 @@
//TODO - complete JavaDoc
+ /**
+ * Default constructor, merely calls
+ * <code>{@link #configClassName this.configClassName} = {@link SpringIniWebConfiguration SpringIniWebConfiguration}.class.getName()}</code>.
+ */
public SpringJSecurityFilter() {
this.configClassName = SpringIniWebConfiguration.class.getName();
}
diff --git a/support/spring/src/org/jsecurity/spring/security/interceptor/AuthorizationAttributeSourceAdvisor.java b/support/spring/src/org/jsecurity/spring/security/interceptor/AuthorizationAttributeSourceAdvisor.java
index e5333bd..bc37257 100644
--- a/support/spring/src/org/jsecurity/spring/security/interceptor/AuthorizationAttributeSourceAdvisor.java
+++ b/support/spring/src/org/jsecurity/spring/security/interceptor/AuthorizationAttributeSourceAdvisor.java
@@ -46,7 +46,7 @@
public AuthorizationAttributeSourceAdvisor() {
}
- public org.jsecurity.mgt.SecurityManager getSecurityManager() {
+ public SecurityManager getSecurityManager() {
return securityManager;
}
