You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@shiro.apache.org by lh...@apache.org on 2009/04/06 22:35:04 UTC
svn commit: r762496 -
/incubator/jsecurity/trunk/web/src/main/java/org/apache/ki/web/filter/authz/AuthorizationFilter.java
Author: lhazlewood
Date: Mon Apr 6 20:35:04 2009
New Revision: 762496
URL: http://svn.apache.org/viewvc?rev=762496&view=rev
Log:
Added JavaDoc
Modified:
incubator/jsecurity/trunk/web/src/main/java/org/apache/ki/web/filter/authz/AuthorizationFilter.java
Modified: incubator/jsecurity/trunk/web/src/main/java/org/apache/ki/web/filter/authz/AuthorizationFilter.java
URL: http://svn.apache.org/viewvc/incubator/jsecurity/trunk/web/src/main/java/org/apache/ki/web/filter/authz/AuthorizationFilter.java?rev=762496&r1=762495&r2=762496&view=diff
==============================================================================
--- incubator/jsecurity/trunk/web/src/main/java/org/apache/ki/web/filter/authz/AuthorizationFilter.java (original)
+++ incubator/jsecurity/trunk/web/src/main/java/org/apache/ki/web/filter/authz/AuthorizationFilter.java Mon Apr 6 20:35:04 2009
@@ -18,50 +18,102 @@
*/
package org.apache.ki.web.filter.authz;
-import java.io.IOException;
-import javax.servlet.ServletRequest;
-import javax.servlet.ServletResponse;
-import javax.servlet.http.HttpServletResponse;
-
import org.apache.ki.subject.Subject;
import org.apache.ki.util.StringUtils;
import org.apache.ki.web.WebUtils;
import org.apache.ki.web.filter.AccessControlFilter;
+import javax.servlet.ServletRequest;
+import javax.servlet.ServletResponse;
+import javax.servlet.http.HttpServletResponse;
+import java.io.IOException;
+
/**
- * Superclass for authorization-related filters. For unauthorized requests, this filter redirects to the
- * login page if the current user is unknown (i.e. not authenticated or remembered). If the user is known,
- * the filter redirects to an unauthorized URL or returns an unauthorized HTTP status code if no unauthorized
- * URL is specified.
+ * Superclass for authorization-related filters. If an request is unauthorized, response handling is delegated to the
+ * {@link #onAccessDenied(javax.servlet.ServletRequest, javax.servlet.ServletResponse) onAccessDenied} method, which
+ * provides reasonable handling for most applications.
*
+ * @see #onAccessDenied(javax.servlet.ServletRequest, javax.servlet.ServletResponse)
+ *
* @author Les Hazlewood
* @author Jeremy Haile
* @since 0.9
*/
public abstract class AuthorizationFilter extends AccessControlFilter {
- //TODO - complete JavaDoc
-
+ /**
+ * The URL to which users should be redirected if they are denied access to an underlying path or resource,
+ * {@code null} by default which will issue a raw {@link HttpServletResponse#SC_UNAUTHORIZED} response
+ * (401 Unauthorized).
+ */
private String unauthorizedUrl;
+ /**
+ * Returns the URL to which users should be redirected if they are denied access to an underlying path or resource,
+ * or {@code null} if a raw {@link HttpServletResponse#SC_UNAUTHORIZED} response should be issued (401 Unauthorized).
+ * <p/>
+ * The default is {@code null}, ensuring default web server behavior. Override this default by calling the
+ * {@link #setUnauthorizedUrl(String) setUnauthorizedUrl} method with a meaningful path within your application
+ * if you would like to show the user a 'nice' page in the event of unauthorized access.
+ *
+ * @return the URL to which users should be redirected if they are denied access to an underlying path or resource,
+ * or {@code null} if a raw {@link HttpServletResponse#SC_UNAUTHORIZED} response should be issued (401 Unauthorized).
+ */
protected String getUnauthorizedUrl() {
return unauthorizedUrl;
}
+ /**
+ * Sets the URL to which users should be redirected if they are denied access to an underlying path or resource.
+ * <p/>
+ * If the value is {@code null} a raw {@link HttpServletResponse#SC_UNAUTHORIZED} response will
+ * be issued (401 Unauthorized), retaining default web server behavior.
+ * <p/>
+ * Unless overridden by calling this method, the default value is {@code null}. If desired, you can specify a
+ * meaningful path within your application if you would like to show the user a 'nice' page in the event of
+ * unauthorized access.
+ *
+ * @param unauthorizedUrl the URL to which users should be redirected if they are denied access to an underlying
+ * path or resource, or {@code null} to a ensure raw {@link HttpServletResponse#SC_UNAUTHORIZED} response is
+ * issued (401 Unauthorized).
+ */
public void setUnauthorizedUrl(String unauthorizedUrl) {
this.unauthorizedUrl = unauthorizedUrl;
}
+ /**
+ * Handles the response when access has been denied. It behaves as follows:
+ * <ul>
+ * <li>If the {@code Subject} is unknown<sup><a href="#known">[1]</a></sup>:
+ * <ol><li>The incoming request will be saved and they will be redirected to the login page for authentication
+ * (via the {@link #saveRequestAndRedirectToLogin(javax.servlet.ServletRequest, javax.servlet.ServletResponse)}
+ * method).</li>
+ * <li>Once successfully authenticated, they will be redirected back to the originally attempted page.</li></ol>
+ * </li>
+ * <li>If the Subject is known:</li>
+ * <ol>
+ * <li>The HTTP {@link HttpServletResponse#SC_UNAUTHORIZED} header will be set (401 Unauthorized)</li>
+ * <li>If the {@link #getUnauthorizedUrl() unauthorizedUrl} has been configured, a redirect will be issued to that
+ * URL. Otherwise the 401 response is rendered normally</li>
+ * </ul>
+ * <code><a name="known">[1]</a></code>: A {@code Subject} is 'known' when
+ * <code>subject.{@link org.apache.ki.subject.Subject#getPrincipal() getPrincipal()}</code> is not {@code null},
+ * which implicitly means that the subject is either currently authenticated or they have been remembered via
+ * 'remember me' services.
+ *
+ * @param request the incoming <code>ServletRequest</code>
+ * @param response the outgoing <code>ServletResponse</code>
+ * @return {@code false} always for this implementation.
+ * @throws IOException if there is any servlet error.
+ */
protected boolean onAccessDenied(ServletRequest request, ServletResponse response) throws IOException {
Subject subject = getSubject(request, response);
// If the subject isn't identified, redirect to login URL
if (subject.getPrincipal() == null) {
saveRequestAndRedirectToLogin(request, response);
- return false;
} else {
-
- // If subject is known but not authorized, redirect to the unauthorized URL if there is one
+ // If subject is known but not authorized, redirect to the unauthorized URL if there is one
// If no unauthorized URL is specified, just return an unauthorized HTTP status code
WebUtils.toHttp(response).setStatus(HttpServletResponse.SC_UNAUTHORIZED);
if (StringUtils.hasText(getUnauthorizedUrl())) {