final javadoc updates and code modifications for RC1
git-svn-id: https://svn.apache.org/repos/asf/incubator/jsecurity/trunk@711055 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/src/org/jsecurity/crypto/BlowfishCipher.java b/src/org/jsecurity/crypto/BlowfishCipher.java
index e834f60..9e05ebc 100644
--- a/src/org/jsecurity/crypto/BlowfishCipher.java
+++ b/src/org/jsecurity/crypto/BlowfishCipher.java
@@ -43,10 +43,11 @@
* to you and you think the default key still makes things 'sufficiently difficult', then you can ignore this issue.
*
* <p>However, if you do feel this constitutes sensitive information, it is recommended that you provide your own
- * <tt>Key</tt> via the {@link # setKey setDefaultKey} method to a Key known only to your application,
+ * <tt>Key</tt> via the {@link #setKey setKey} method to a Key known only to your application,
* guaranteeing that no third party can decrypt your data. If you want to know how to do this, you can browse this
- * class's source code for the {@link #generateNewKey()} method to see how we created our default. Then you can duplicate the same in
- * your environment and set the result on an instance of this class via the <code>setKey</code> method.
+ * class's source code for the {@link #generateNewKey()} method to see how we created our default. Then you can
+ * duplicate the same in your environment and set the result on an instance of this class via the
+ * <code>setKey</code> method.
*
* @author Les Hazlewood
* @author Jeremy Haile
diff --git a/src/org/jsecurity/io/ResourceUtils.java b/src/org/jsecurity/io/ResourceUtils.java
index d260a87..6f5d4d8 100644
--- a/src/org/jsecurity/io/ResourceUtils.java
+++ b/src/org/jsecurity/io/ResourceUtils.java
@@ -58,8 +58,13 @@
}
/**
- * @param resourcePath
- * @return
+ * Returns <code>true</code> if the resource path is not null and starts with one of the recognized
+ * resource prefixes ({@link #CLASSPATH_PREFIX CLASSPATH_PREFIX},
+ * {@link #URL_PREFIX URL_PREFIX}, or {@link #FILE_PREFIX FILE_PREFIX}), <code>false</code> otherwise.
+ *
+ * @param resourcePath the resource path to check
+ * @return <code>true</code> if the resource path is not null and starts with one of the recognized
+ * resource prefixes, <code>false</code> otherwise.
* @since 0.9
*/
public static boolean hasResourcePrefix(String resourcePath) {
@@ -70,8 +75,9 @@
}
/**
- * @param resourcePath
- * @return
+ * Returns <code>true</code> if the resource at the specified path exists, <code>false</code> otherwise.
+ * @param resourcePath the path of the resource to check.
+ * @return <code>true</code> if the resource at the specified path exists, <code>false</code> otherwise.
* @since 0.9
*/
public static boolean resourceExists(String resourcePath) {
diff --git a/src/org/jsecurity/realm/AuthorizingRealm.java b/src/org/jsecurity/realm/AuthorizingRealm.java
index c94ae11..aa4aad8 100644
--- a/src/org/jsecurity/realm/AuthorizingRealm.java
+++ b/src/org/jsecurity/realm/AuthorizingRealm.java
@@ -139,11 +139,11 @@
* method invocations.
* All future calls to <tt>getAuthorizationInfo</tt> 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,
+ * <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>
- * <li>If neither the {@link # setAuthorizationCache (org.jsecurity.cache.Cache) cache}
+ * <li>If neither the {@link #setAuthorizationCache (org.jsecurity.cache.Cache) cache}
* or {@link #setCacheManager(org.jsecurity.cache.CacheManager) cacheManager}
* properties are set, caching will be disabled and authorization lookups will be delegated to
* subclass implementations for each authorization check.</li>
diff --git a/src/org/jsecurity/realm/ldap/AbstractLdapRealm.java b/src/org/jsecurity/realm/ldap/AbstractLdapRealm.java
index adfd447..e98610c 100644
--- a/src/org/jsecurity/realm/ldap/AbstractLdapRealm.java
+++ b/src/org/jsecurity/realm/ldap/AbstractLdapRealm.java
@@ -48,8 +48,8 @@
*
* @author Jeremy Haile
* @author Les Hazlewood
- * @see # queryForAuthenticationInfo (org.jsecurity.authc.AuthenticationToken, LdapContextFactory)
- * @see # queryForAuthorizationInfo (PrincipalCollection, LdapContextFactory)
+ * @see #queryForAuthenticationInfo(org.jsecurity.authc.AuthenticationToken, LdapContextFactory)
+ * @see #queryForAuthorizationInfo(PrincipalCollection, LdapContextFactory)
* @since 0.1
*/
public abstract class AbstractLdapRealm extends AuthorizingRealm {
diff --git a/src/org/jsecurity/session/Session.java b/src/org/jsecurity/session/Session.java
index 5d93de8..efde797 100644
--- a/src/org/jsecurity/session/Session.java
+++ b/src/org/jsecurity/session/Session.java
@@ -160,7 +160,6 @@
* corresponding session automatically, and also allows framework code to execute additional cleanup logic.
*
* @throws InvalidSessionException if this session has stopped or expired prior to calling this method.
- * @see #getStopTimestamp
*/
void stop() throws InvalidSessionException;
diff --git a/src/org/jsecurity/session/mgt/AbstractValidatingSessionManager.java b/src/org/jsecurity/session/mgt/AbstractValidatingSessionManager.java
index 549c132..646b739 100644
--- a/src/org/jsecurity/session/mgt/AbstractValidatingSessionManager.java
+++ b/src/org/jsecurity/session/mgt/AbstractValidatingSessionManager.java
@@ -86,10 +86,10 @@
return sessionValidationScheduler;
}
- public void startSessionValidationIfNecessary() {
+ public void enableSessionValidationIfNecessary() {
SessionValidationScheduler scheduler = getSessionValidationScheduler();
- if (isSessionValidationSchedulerEnabled() && (scheduler == null || !scheduler.isRunning())) {
- startSessionValidation();
+ if (isSessionValidationSchedulerEnabled() && (scheduler == null || !scheduler.isEnabled())) {
+ enableSessionValidation();
}
}
@@ -148,14 +148,14 @@
}
protected final Session doGetSession(Serializable sessionId) throws InvalidSessionException {
- startSessionValidationIfNecessary();
+ enableSessionValidationIfNecessary();
return retrieveSession(sessionId);
}
protected abstract Session retrieveSession(Serializable sessionId) throws InvalidSessionException;
protected final Session createSession(InetAddress originatingHost) throws HostUnauthorizedException, IllegalArgumentException {
- startSessionValidationIfNecessary();
+ enableSessionValidationIfNecessary();
return doCreateSession(originatingHost);
}
@@ -207,34 +207,34 @@
return scheduler;
}
- protected void startSessionValidation() {
+ protected void enableSessionValidation() {
SessionValidationScheduler scheduler = getSessionValidationScheduler();
if (scheduler == null) {
scheduler = createSessionValidationScheduler();
setSessionValidationScheduler(scheduler);
}
if (log.isInfoEnabled()) {
- log.info("Starting session validation scheduler...");
+ log.info("Enabling session validation scheduler...");
}
- scheduler.startSessionValidation();
- afterSessionValidationStarted();
+ scheduler.enableSessionValidation();
+ afterSessionValidationEnabled();
}
- protected void afterSessionValidationStarted() {
+ protected void afterSessionValidationEnabled() {
}
- protected void stopSessionValidation() {
- beforeSessionValidationStopped();
+ protected void disableSessionValidation() {
+ beforeSessionValidationDisabled();
SessionValidationScheduler scheduler = getSessionValidationScheduler();
if (scheduler != null) {
try {
- scheduler.stopSessionValidation();
+ scheduler.disableSessionValidation();
if (log.isInfoEnabled()) {
- log.info("Stopped session validation scheduler.");
+ log.info("Disabled session validation scheduler.");
}
} catch (Exception e) {
if (log.isDebugEnabled()) {
- String msg = "Unable to stop SessionValidationScheduler. Ignoring (shutting down)...";
+ String msg = "Unable to disable SessionValidationScheduler. Ignoring (shutting down)...";
log.debug(msg, e);
}
}
@@ -243,11 +243,11 @@
}
}
- protected void beforeSessionValidationStopped() {
+ protected void beforeSessionValidationDisabled() {
}
public void destroy() {
- stopSessionValidation();
+ disableSessionValidation();
}
/**
diff --git a/src/org/jsecurity/session/mgt/ExecutorServiceSessionValidationScheduler.java b/src/org/jsecurity/session/mgt/ExecutorServiceSessionValidationScheduler.java
index 6a9324e..dd357b7 100644
--- a/src/org/jsecurity/session/mgt/ExecutorServiceSessionValidationScheduler.java
+++ b/src/org/jsecurity/session/mgt/ExecutorServiceSessionValidationScheduler.java
@@ -40,7 +40,7 @@
ValidatingSessionManager sessionManager;
private ScheduledExecutorService service;
private long interval = DefaultSessionManager.DEFAULT_SESSION_VALIDATION_INTERVAL;
- private boolean running = false;
+ private boolean enabled = false;
public ExecutorServiceSessionValidationScheduler() {
super();
@@ -66,15 +66,15 @@
this.interval = interval;
}
- public boolean isRunning() {
- return this.running;
+ public boolean isEnabled() {
+ return this.enabled;
}
- public void startSessionValidation() {
+ public void enableSessionValidation() {
if (this.interval > 0l) {
this.service = Executors.newSingleThreadScheduledExecutor();
this.service.scheduleAtFixedRate(this, interval, interval, TimeUnit.MILLISECONDS);
- this.running = true;
+ this.enabled = true;
}
}
@@ -90,8 +90,8 @@
}
}
- public void stopSessionValidation() {
+ public void disableSessionValidation() {
this.service.shutdownNow();
- this.running = false;
+ this.enabled = false;
}
}
diff --git a/src/org/jsecurity/session/mgt/SessionValidationScheduler.java b/src/org/jsecurity/session/mgt/SessionValidationScheduler.java
index 2fd5b5d..80976f5 100644
--- a/src/org/jsecurity/session/mgt/SessionValidationScheduler.java
+++ b/src/org/jsecurity/session/mgt/SessionValidationScheduler.java
@@ -23,26 +23,32 @@
* basis. This interface is used as a delegate for session validation by the {@link DefaultSessionManager}
*
* @author Jeremy Haile
+ * @author Les Hazlewood
* @see DefaultSessionManager#setSessionValidationScheduler(SessionValidationScheduler)
* @since 0.1
*/
public interface SessionValidationScheduler {
/**
- * Indicates that this Scheduler has been started - not that it is currently actively validating sessions.
+ * Returns <code>true</code> if this Scheduler is enabled and ready to begin validation at the appropriate time,
+ * <code>false</code> otherwise.
+ * <p/>
+ * It does <em>not</em> indicate if the validation is actually executing at that instant - only that it is prepared
+ * to do so at the appropriate time.
*
- * @return
+ * @return <code>true</code> if this Scheduler is enabled and ready to begin validation at the appropriate time,
+ * <code>false</code> otherwise.
*/
- boolean isRunning();
+ boolean isEnabled();
/**
- * Starts the session validation job.
+ * Enables the session validation job.
*/
- void startSessionValidation();
+ void enableSessionValidation();
/**
- * Stops the session validation job.
+ * Disables the session validation job.
*/
- void stopSessionValidation();
+ void disableSessionValidation();
}
\ No newline at end of file
diff --git a/src/org/jsecurity/session/mgt/quartz/QuartzSessionValidationScheduler.java b/src/org/jsecurity/session/mgt/quartz/QuartzSessionValidationScheduler.java
index 8e513df..5f39b3a 100644
--- a/src/org/jsecurity/session/mgt/quartz/QuartzSessionValidationScheduler.java
+++ b/src/org/jsecurity/session/mgt/quartz/QuartzSessionValidationScheduler.java
@@ -67,7 +67,7 @@
private boolean schedulerImplicitlyCreated = false;
- private boolean running = false;
+ private boolean enabled = false;
/**
* The session manager used to validate sessions.
@@ -118,8 +118,8 @@
this.sessionManager = sessionManager;
}
- public boolean isRunning() {
- return this.running;
+ public boolean isEnabled() {
+ return this.enabled;
}
/**
@@ -142,7 +142,7 @@
* Starts session validation by creating a Quartz simple trigger, linking it to
* the {@link QuartzSessionValidationJob}, and scheduling it with the Quartz scheduler.
*/
- public void startSessionValidation() {
+ public void enableSessionValidation() {
if (log.isDebugEnabled()) {
log.debug("Scheduling session validation job using Quartz with " +
@@ -167,7 +167,7 @@
log.debug("Successfully started implicitly created Quartz Scheduler instance.");
}
}
- this.running = true;
+ this.enabled = true;
if (log.isDebugEnabled()) {
log.debug("Session validation job successfully scheduled with Quartz.");
@@ -180,7 +180,7 @@
}
}
- public void stopSessionValidation() {
+ public void disableSessionValidation() {
if (log.isDebugEnabled()) {
log.debug("Stopping Quartz session validation job...");
}
@@ -215,7 +215,7 @@
}
}
- this.running = false;
+ this.enabled = false;
if (schedulerImplicitlyCreated) {
try {
diff --git a/src/org/jsecurity/util/StringUtils.java b/src/org/jsecurity/util/StringUtils.java
index 0560542..c2a457a 100644
--- a/src/org/jsecurity/util/StringUtils.java
+++ b/src/org/jsecurity/util/StringUtils.java
@@ -39,8 +39,13 @@
*/
public class StringUtils {
+ /** Constant representing the empty string, equal to "" */
public static final String EMPTY_STRING = "";
+
+ /** Constant representing the default delimiter character (comma), equal to <code>','</code> */
public static final char DEFAULT_DELIMITER_CHAR = ',';
+
+ /** Constant representing the default quote character (double quote), equal to '"'</code> */
public static final char DEFAULT_QUOTE_CHAR = '"';
/**
@@ -120,6 +125,22 @@
return lcStr.equals(lcPrefix);
}
+ /**
+ * Returns a 'cleaned' representation of the specified argument. 'Cleaned' is defined as the following:
+ *
+ * <ol>
+ * <li>If the specified <code>String</code> is <code>null</code>, return <code>null</code></li>
+ * <li>If not <code>null</code>, {@link String#trim() trim()} it.</li>
+ * <li>If the trimmed string is equal to the empty String (i.e. ""), return <code>null</code></li>
+ * <li>If the trimmed string is not the empty string, return the trimmed version</li>.
+ * </ol>
+ *
+ * Therefore this method always ensures that any given string has trimmed text, and if it doesn't, <code>null</code>
+ * is returned.
+ *
+ * @param in the input String to clean.
+ * @return a populated-but-trimmed String or <code>null</code> otherwise
+ */
public static String clean(String in) {
String out = in;
diff --git a/src/org/jsecurity/web/filter/AccessControlFilter.java b/src/org/jsecurity/web/filter/AccessControlFilter.java
index 73f9a2f..9b28de3 100644
--- a/src/org/jsecurity/web/filter/AccessControlFilter.java
+++ b/src/org/jsecurity/web/filter/AccessControlFilter.java
@@ -45,7 +45,10 @@
public static final String DEFAULT_LOGIN_URL = "/login.jsp";
/** Constant representing the HTTP 'GET' request method, equal to <code>GET</code>. */
- protected static final String GET_METHOD = "GET";
+ public static final String GET_METHOD = "GET";
+
+ /** Constant representing the HTTP 'POST' request method, equal to <code>POST</code>. */
+ public static final String POST_METHOD = "POST";
/** The login url to used to authenticate a user, used when redirecting users if authentication is required. */
private String loginUrl = DEFAULT_LOGIN_URL;
@@ -125,9 +128,6 @@
* otherwise returns the result of
* {@link #onAccessDenied(javax.servlet.ServletRequest, javax.servlet.ServletResponse) onAccessDenied}.
*
- * @param request the incoming <code>ServletRequest</code>
- * @param response the outgoing <code>ServletResponse</code>
- * @param mappedValue the filter-specific config value mapped to this filter in the URL rules mappings.
* @return <code>true</code> if
* {@link #isAccessAllowed(javax.servlet.ServletRequest, javax.servlet.ServletResponse, Object) isAccessAllowed},
* otherwise returns the result of
diff --git a/src/org/jsecurity/web/filter/PathMatchingFilter.java b/src/org/jsecurity/web/filter/PathMatchingFilter.java
index cdd2c32..bfccf23 100644
--- a/src/org/jsecurity/web/filter/PathMatchingFilter.java
+++ b/src/org/jsecurity/web/filter/PathMatchingFilter.java
@@ -39,8 +39,10 @@
*/
public abstract class PathMatchingFilter extends AdviceFilter implements PathConfigProcessor {
- private static final Log log = LogFactory.getLog(PathMatchingFilter.class);
+ /** Log available to this class only */
+ private static final Log log = LogFactory.getLog(PathMatchingFilter.class);
+ /** PathMatcher used in determining which paths to react to for a given request. */
protected AntPathMatcher pathMatcher = new AntPathMatcher();
/**
@@ -53,6 +55,22 @@
*/
protected Map<String, Object> appliedPaths = new LinkedHashMap<String, Object>();
+ /**
+ * Splits any comma-delmited values that might be found in the <code>config</code> argument and sets the resulting
+ * <code>String[]</code> array on the <code>appliedPaths</code> internal Map.
+ * <p/>
+ * That is:
+ * <pre><code>
+ * String[] values = null;
+ * if (config != null) {
+ * values = split(config);
+ * }
+ *
+ * this.{@link #appliedPaths appliedPaths}.put(path, values);
+ * </code></pre>
+ * @param path the application context path to match for executing this filter.
+ * @param config the specified for <em>this particular filter only</em> for the given <code>path</code>
+ */
public void processPathConfig(String path, String config) {
String[] values = null;
if (config != null) {
@@ -69,8 +87,8 @@
* {@link WebUtils#getPathWithinApplication(javax.servlet.http.HttpServletRequest) WebUtils.getPathWithinApplication(request)},
* but can be overridden by subclasses for custom logic.
*
- * @param request
- * @return
+ * @param request the incoming <code>ServletRequest</code>
+ * @return the context path within the application.
*/
protected String getPathWithinApplication(ServletRequest request) {
return WebUtils.getPathWithinApplication(WebUtils.toHttp(request));
@@ -162,12 +180,12 @@
*
* @param request the incoming ServletRequest
* @param response the outgoing ServletResponse
- * @param configValue the configured value for this filter for the matching path.
+ * @param mappedValue the filter-specific config value mapped to this filter in the URL rules mappings.
* @return <code>true</code> if the request should be able to continue, <code>false</code> if the filter will
- * handle the request directly.
+ * handle the response directly.
* @throws Exception if an error occurs
*/
- protected boolean onPreHandle(ServletRequest request, ServletResponse response, Object configValue) throws Exception {
+ protected boolean onPreHandle(ServletRequest request, ServletResponse response, Object mappedValue) throws Exception {
return true;
}
}
diff --git a/src/org/jsecurity/web/filter/authc/AnonymousFilter.java b/src/org/jsecurity/web/filter/authc/AnonymousFilter.java
index 8f30c48..56c2913 100644
--- a/src/org/jsecurity/web/filter/authc/AnonymousFilter.java
+++ b/src/org/jsecurity/web/filter/authc/AnonymousFilter.java
@@ -53,6 +53,11 @@
*/
public class AnonymousFilter extends PathMatchingFilter {
+ /**
+ * Always returns <code>true</code> allowing unchecked access to the underlying path or resource.
+ *
+ * @return <code>true</code> always, allowing unchecked access to the underlying path or resource.
+ */
@Override
public boolean onPreHandle(ServletRequest request, ServletResponse response, Object mappedValue) {
// Always return true since we allow access to anyone
diff --git a/src/org/jsecurity/web/filter/authc/AuthenticationFilter.java b/src/org/jsecurity/web/filter/authc/AuthenticationFilter.java
index 4bf695b..8c05285 100644
--- a/src/org/jsecurity/web/filter/authc/AuthenticationFilter.java
+++ b/src/org/jsecurity/web/filter/authc/AuthenticationFilter.java
@@ -33,6 +33,7 @@
*
* @author Allan Ditzel
* @author Jeremy Haile
+ * @author Les Hazlewood
* @since 0.9
*/
public abstract class AuthenticationFilter extends AccessControlFilter {
@@ -41,7 +42,6 @@
private String successUrl = DEFAULT_SUCCESS_URL;
-
protected String getSuccessUrl() {
return successUrl;
}
@@ -60,10 +60,11 @@
/**
* Determines whether the current subject is authenticated.
+ * <p/>
+ * The default implementation {@link #getSubject(javax.servlet.ServletRequest, javax.servlet.ServletResponse) acquires}
+ * the currently executing Subject and then returns
+ * {@link org.jsecurity.subject.Subject#isAuthenticated() subject.isAuthenticated()};
*
- * @param request the servlet request.
- * @param response the servlet response.
- * @param mappedValue
* @return true if the subject is authenticated; false if the subject is unauthenticated
*/
protected boolean isAccessAllowed(ServletRequest request, ServletResponse response, Object mappedValue) {
diff --git a/src/org/jsecurity/web/filter/authc/BasicHttpAuthenticationFilter.java b/src/org/jsecurity/web/filter/authc/BasicHttpAuthenticationFilter.java
index a811d66..426ece3 100644
--- a/src/org/jsecurity/web/filter/authc/BasicHttpAuthenticationFilter.java
+++ b/src/org/jsecurity/web/filter/authc/BasicHttpAuthenticationFilter.java
@@ -39,10 +39,10 @@
* request to continue, and if they're not, forces the user to login via the HTTP Basic protocol-specific challenge.
* Upon successful login, they're allowed to continue on to the requested resource/url.
*
- * <p>This implementation is a 'clean room' Java implementation of Basic HTTP Authentication as specified in
+ * <p>This implementation is a 'clean room' Java implementation of Basic HTTP Authentication specification per
* <a href="ftp://ftp.isi.edu/in-notes/rfc2617.txt">RFC 2617</a>.</p>
*
- * <p>Basic authentication works as follows:</p>
+ * <p>Basic authentication functions as follows:</p>
*
* <ol>
* <li>A request comes in for a resource that requires authentication.</li>
@@ -63,6 +63,7 @@
* @author Allan Ditzel
* @author Les Hazlewood
* @see <a href="ftp://ftp.isi.edu/in-notes/rfc2617.txt">RFC 2617</a>
+ * @see <a href="http://en.wikipedia.org/wiki/Basic_access_authentication">Basic Access Authentication</a>
* @since 0.9
*/
public class BasicHttpAuthenticationFilter extends AuthenticationFilter {
@@ -227,21 +228,21 @@
/**
* Default implementation that returns <code>true</code> if the specified <code>authzHeader</code>
* starts with the same (case-insensitive) characters specified by the
- * {@link #getAuthzScheme() authzHeaderScheme}, <code>false</code> otherwise.
+ * {@link #getAuthzScheme() authzScheme}, <code>false</code> otherwise.
* <p/>
* That is:
* <p/>
- * <code>String authzHeaderScheme = getAuthzHeaderScheme().toLowerCase();<br/>
- * return authzHeader.toLowerCase().startsWith(authzHeaderScheme);</code>
+ * <code>String authzScheme = getAuthzScheme().toLowerCase();<br/>
+ * return authzHeader.toLowerCase().startsWith(authzScheme);</code>
*
* @param authzHeader the 'Authorization' header value (guaranteed to be non-null if the
* {@link #isLoginAttempt(javax.servlet.ServletRequest, javax.servlet.ServletResponse)} method is not overriden).
* @return <code>true</code> if the authzHeader value matches that configured as defined by
- * the {@link # getAuthzScheme () authzHeaderScheme}.
+ * the {@link #getAuthzScheme() authzScheme}.
*/
protected boolean isLoginAttempt(String authzHeader) {
- String authzHeaderScheme = getAuthzScheme().toLowerCase();
- return authzHeader.toLowerCase().startsWith(authzHeaderScheme);
+ String authzScheme = getAuthzScheme().toLowerCase();
+ return authzHeader.toLowerCase().startsWith(authzScheme);
}
/**
@@ -250,7 +251,7 @@
* <p/>
* The header value constructed is equal to:
* <p/>
- * <code>{@link #getAuthcScheme() getAuthcHeaderScheme()} + " realm=\"" + {@link #getApplicationName() getApplicationName()} + "\"";</code>
+ * <code>{@link #getAuthcScheme() getAuthcScheme()} + " realm=\"" + {@link #getApplicationName() getApplicationName()} + "\"";</code>
*
* @param request incoming ServletRequest, ignored by this implementation
* @param response outgoing ServletResponse
@@ -388,7 +389,7 @@
* <code>String decoded = Base64.decodeToString(encoded);<br/>
* return decoded.split(":");</code>
*
- * @param scheme the {@link #getAuthcScheme() authcHeaderScheme} found in the request
+ * @param scheme the {@link #getAuthcScheme() authcScheme} found in the request
* {@link #getAuthzHeader(javax.servlet.ServletRequest) authzHeader}. It is ignored by this implementation,
* but available to overriding implementations should they find it useful.
* @param encoded the Base64-encoded username:password value found after the scheme in the header
diff --git a/src/org/jsecurity/web/filter/authc/FormAuthenticationFilter.java b/src/org/jsecurity/web/filter/authc/FormAuthenticationFilter.java
index adeffdb..7d04b54 100644
--- a/src/org/jsecurity/web/filter/authc/FormAuthenticationFilter.java
+++ b/src/org/jsecurity/web/filter/authc/FormAuthenticationFilter.java
@@ -173,7 +173,7 @@
* @return <code>true</code> if the request is an HTTP <code>POST</code>, <code>false</code> otherwise.
*/
protected boolean isLoginSubmission(ServletRequest request, ServletResponse response) {
- return (request instanceof HttpServletRequest) && toHttp(request).getMethod().equalsIgnoreCase("POST");
+ return (request instanceof HttpServletRequest) && toHttp(request).getMethod().equalsIgnoreCase(POST_METHOD);
}
protected boolean executeLogin(ServletRequest request, ServletResponse response) throws Exception {
diff --git a/src/org/jsecurity/web/filter/authc/PassThruAuthenticationFilter.java b/src/org/jsecurity/web/filter/authc/PassThruAuthenticationFilter.java
index cf21c10..106188e 100644
--- a/src/org/jsecurity/web/filter/authc/PassThruAuthenticationFilter.java
+++ b/src/org/jsecurity/web/filter/authc/PassThruAuthenticationFilter.java
@@ -30,7 +30,8 @@
* on a login submission (by default an HTTP POST to the login URL), the <code>FormAuthenticationFilter</code> filter
* attempts to automatically authenticate the user by passing the <code>username</code> and <code>password</code>
* request parameter values to
- * {@link org.jsecurity.subject.Subject#login(org.jsecurity.authc.AuthenticationToken) Subject.login(usernamePasswordToken)}.
+ * {@link org.jsecurity.subject.Subject#login(org.jsecurity.authc.AuthenticationToken) Subject.login(usernamePasswordToken)}
+ * directly.
* <p/>
* Conversely, this controller always passes all requests to the {@link #setLoginUrl loginUrl} through, both GETs and
* POSTs. This is useful in cases where the developer wants to write their own login behavior, which should include a
diff --git a/src/org/jsecurity/web/servlet/AdviceFilter.java b/src/org/jsecurity/web/servlet/AdviceFilter.java
index ddcd6b7..4fafc86 100644
--- a/src/org/jsecurity/web/servlet/AdviceFilter.java
+++ b/src/org/jsecurity/web/servlet/AdviceFilter.java
@@ -39,18 +39,21 @@
*/
public abstract class AdviceFilter extends OncePerRequestFilter {
+ /** The static logger available to this class only */
private static final Log log = LogFactory.getLog(AdviceFilter.class);
/**
* Returns <code>true</code> if the filter chain should be allowed to continue, <code>false</code> otherwise.
- * Called before the chain is actually consulted/executed.
+ * It is called before the chain is actually consulted/executed.
+ * <p/>
+ * The default implementation returns <code>true</code> always and exists as a template method for subclasses.
*
* @param request the incoming ServletRequest
* @param response the outgoing ServletResponse
* @return <code>true</code> if the filter chain should be allowed to continue, <code>false</code> otherwise.
* @throws Exception if there is any error.
*/
- public boolean preHandle(ServletRequest request, ServletResponse response) throws Exception {
+ protected boolean preHandle(ServletRequest request, ServletResponse response) throws Exception {
return true;
}
@@ -62,13 +65,13 @@
* implementation, which is guaranteed to be called for every request, even when the chain processing throws
* an Exception.
* <p/>
- * The default implementation is a no-op, and exists as a template method for subclasses.
+ * The default implementation does nothing (no-op) and exists as a template method for subclasses.
*
* @param request the incoming ServletRequest
* @param response the outgoing ServletResponse
* @throws Exception if an error occurs.
*/
- public void postHandle(ServletRequest request, ServletResponse response) throws Exception {
+ protected void postHandle(ServletRequest request, ServletResponse response) throws Exception {
}
/**
@@ -76,7 +79,7 @@
* <code>false</code> or if an exception is thrown during filter chain processing. Can be used for resource
* cleanup if so desired.
* <p/>
- * The default implementation is a no-op, and exists as a template method for subclasses.
+ * The default implementation does nothing (no-op) and exists as a template method for subclasses.
*
* @param request the incoming ServletRequest
* @param response the outgoing ServletResponse
@@ -103,7 +106,11 @@
}
/**
- * Actually implements the chain execution logic, utilizing pre, post, and after advice hooks.
+ * Actually implements the chain execution logic, utilizing
+ * {@link #preHandle(javax.servlet.ServletRequest, javax.servlet.ServletResponse) pre},
+ * {@link #postHandle(javax.servlet.ServletRequest, javax.servlet.ServletResponse) post}, and
+ * {@link #afterCompletion(javax.servlet.ServletRequest, javax.servlet.ServletResponse, Exception) after}
+ * advice hooks.
*
* @param request the incoming ServletRequest
* @param response the outgoing ServletResponse
@@ -136,27 +143,49 @@
} catch (Exception e) {
exception = e;
} finally {
- try {
- afterCompletion(request, response, exception);
- if (log.isTraceEnabled()) {
- log.trace("Successfully invoked afterCompletion method.");
- }
- } catch (Exception e) {
- if (exception == null) {
- exception = e;
- }
+ cleanup( request, response, exception );
+ }
+ }
+
+ /**
+ * Executes cleanup logic in the <code>finally</code> code block in the
+ * {@link #doFilterInternal(javax.servlet.ServletRequest, javax.servlet.ServletResponse, javax.servlet.FilterChain) doFilterInternal}
+ * implementation.
+ * <p/>
+ * This implementation specifically calls
+ * {@link #afterCompletion(javax.servlet.ServletRequest, javax.servlet.ServletResponse, Exception) afterCompletion}
+ * as well as handles any exceptions properly.
+ *
+ * @param request the incoming <code>ServletRequest</code>
+ * @param response the outgoing <code>ServletResponse</code>
+ * @param existing any exception that might have occurred while executing the <code>FilterChain</code> or
+ * pre or post advice, or <code>null</code> if the pre/chain/post excution did not throw an <code>Exception</code>.
+ * @throws ServletException if any exception other than an <code>IOException</code> is thrown.
+ * @throws IOException if the pre/chain/post execution throw an <code>IOException</code>
+ */
+ protected void cleanup( ServletRequest request, ServletResponse response, Exception existing )
+ throws ServletException, IOException {
+ Exception exception = existing;
+ try {
+ afterCompletion(request, response, exception);
+ if (log.isTraceEnabled()) {
+ log.trace("Successfully invoked afterCompletion method.");
}
- if (exception != null) {
- if (exception instanceof ServletException) {
- throw (ServletException) exception;
- } else if (exception instanceof IOException) {
- throw (IOException) exception;
- } else {
- String msg = "Filter execution resulted in an unexpected Exception " +
- "(not IOException or ServletException as the Filter api recommends). " +
- "Wrapping in ServletException and propagating.";
- throw new ServletException(msg, exception);
- }
+ } catch (Exception e) {
+ if (exception == null) {
+ exception = e;
+ }
+ }
+ if (exception != null) {
+ if (exception instanceof ServletException) {
+ throw (ServletException) exception;
+ } else if (exception instanceof IOException) {
+ throw (IOException) exception;
+ } else {
+ String msg = "Filter execution resulted in an unexpected Exception " +
+ "(not IOException or ServletException as the Filter api recommends). " +
+ "Wrapping in ServletException and propagating.";
+ throw new ServletException(msg, exception);
}
}
}
