Update to use contextConfigLocation.

core/src/main/java/org/acegisecurity/ui/webapp/AuthenticationProcessingFilter.java

@@ -76,7 +76,7 @@ import javax.servlet.http.HttpServletResponse;
  * WebApplicationContextUtils#getWebApplicationContext(ServletContext sc)}
  * method to obtain an ApplicationContext instance, inside which must be a
  * configured AuthenticationManager instance. In the case where it is
- * desireable for  this filter to instantiate its own ApplicationContext
+ * desirable for  this filter to instantiate its own ApplicationContext
  * instance from which to obtain the AuthenticationManager, the location of
  * the config for this context may be specified with the optional
  * <code>appContextLocation</code> init param.
@@ -105,7 +105,7 @@ import javax.servlet.http.HttpServletResponse;
  * <code>/j_acegi_security_check</code>.
  * </li>
  * <li>
- * <code>appContextLocation</code> (optional, normally not used), indicates the
+ * <code>contextConfigLocation</code> (optional, normally not used), indicates the
  * path to an application context that contains an {@link
  * AuthenticationManager} which should be used to process each authentication
  * request. If not specified, {@link
@@ -116,7 +116,7 @@ import javax.servlet.http.HttpServletResponse;
  * 
  *
  * @author Ben Alex
- * @author colin sampaleanu
+ * @author Colin Sampaleanu
  * @version $Id$
  */
 public class AuthenticationProcessingFilter implements Filter {
@@ -126,7 +126,7 @@ public class AuthenticationProcessingFilter implements Filter {
      * Name of (optional) servlet filter parameter that can specify the config
      * location for a new ApplicationContext used to config this filter.
      */
-    public static final String CONFIG_LOCATION_PARAM = "appContextLocation";
+    public static final String CONFIG_LOCATION_PARAM = "contextConfigLocation";
     public static final String ACEGI_SECURITY_TARGET_URL_KEY = "ACEGI_SECURITY_TARGET_URL";
     public static final String ACEGI_SECURITY_FORM_USERNAME_KEY = "j_username";
     public static final String ACEGI_SECURITY_FORM_PASSWORD_KEY = "j_password";

core/src/test/java/org/acegisecurity/intercept/web/SecurityEnforcementFilterTests.java

@@ -132,11 +132,11 @@ public class SecurityEnforcementFilterTests extends TestCase {
             request.getSession().getAttribute(AuthenticationProcessingFilter.ACEGI_SECURITY_TARGET_URL_KEY));
     }
 
-    public void testStartupDetectsInvalidAppContextLocation()
+    public void testStartupDetectsInvalidcontextConfigLocation()
         throws Exception {
         MockFilterConfig config = new MockFilterConfig();
         config.setInitParmeter("loginFormUrl", "/login.jsp");
-        config.setInitParmeter("appContextLocation",
+        config.setInitParmeter("contextConfigLocation",
             "net/sf/acegisecurity/intercept/web/securityfiltertest-invalid.xml");
 
         SecurityEnforcementFilter filter = new SecurityEnforcementFilter();
@@ -163,7 +163,7 @@ public class SecurityEnforcementFilterTests extends TestCase {
             assertTrue(expected.getMessage().startsWith("Error obtaining/creating ApplicationContext for config."));
         }
 
-        config.setInitParmeter("appContextLocation", "");
+        config.setInitParmeter("contextConfigLocation", "");
 
         try {
             filter.init(config);
@@ -173,11 +173,11 @@ public class SecurityEnforcementFilterTests extends TestCase {
         }
     }
 
-    public void testStartupDetectsMissingInvalidAppContextLocation()
+    public void testStartupDetectsMissingInvalidcontextConfigLocation()
         throws Exception {
         MockFilterConfig config = new MockFilterConfig();
         config.setInitParmeter("loginFormUrl", "/login.jsp");
-        config.setInitParmeter("appContextLocation", "DOES_NOT_EXIST");
+        config.setInitParmeter("contextConfigLocation", "DOES_NOT_EXIST");
 
         SecurityEnforcementFilter filter = new SecurityEnforcementFilter();
 
@@ -192,7 +192,7 @@ public class SecurityEnforcementFilterTests extends TestCase {
     public void testStartupDetectsMissingLoginFormUrl()
         throws Exception {
         MockFilterConfig config = new MockFilterConfig();
-        config.setInitParmeter("appContextLocation",
+        config.setInitParmeter("contextConfigLocation",
             "net/sf/acegisecurity/intercept/web/securityfiltertest-valid.xml");
 
         SecurityEnforcementFilter filter = new SecurityEnforcementFilter();
@@ -237,7 +237,7 @@ public class SecurityEnforcementFilterTests extends TestCase {
     public void testSuccessfulStartupAndShutdownDown()
         throws Exception {
         MockFilterConfig config = new MockFilterConfig();
-        config.setInitParmeter("appContextLocation",
+        config.setInitParmeter("contextConfigLocation",
             "net/sf/acegisecurity/intercept/web/securityfiltertest-valid.xml");
         config.setInitParmeter("loginFormUrl", "/login.jsp");
 

core/src/test/java/org/acegisecurity/ui/webapp/AuthenticationProcessingFilterTests.java

@@ -102,7 +102,7 @@ public class AuthenticationProcessingFilterTests extends TestCase {
 
         // Setup our filter configuration
         MockFilterConfig config = new MockFilterConfig();
-        config.setInitParmeter("appContextLocation",
+        config.setInitParmeter("contextConfigLocation",
             "net/sf/acegisecurity/ui/webapp/filtertest-valid.xml");
         config.setInitParmeter("defaultTargetUrl", "/");
         config.setInitParmeter("authenticationFailureUrl", "/failed.jsp");
@@ -133,7 +133,7 @@ public class AuthenticationProcessingFilterTests extends TestCase {
 
         // Setup our filter configuration
         MockFilterConfig config = new MockFilterConfig();
-        config.setInitParmeter("appContextLocation",
+        config.setInitParmeter("contextConfigLocation",
             "net/sf/acegisecurity/ui/webapp/filtertest-valid.xml");
         config.setInitParmeter("defaultTargetUrl", "/");
         config.setInitParmeter("authenticationFailureUrl", "/failed.jsp");
@@ -163,7 +163,7 @@ public class AuthenticationProcessingFilterTests extends TestCase {
 
         // Setup our filter configuration
         MockFilterConfig config = new MockFilterConfig();
-        config.setInitParmeter("appContextLocation",
+        config.setInitParmeter("contextConfigLocation",
             "net/sf/acegisecurity/ui/webapp/filtertest-valid.xml");
         config.setInitParmeter("defaultTargetUrl", "/");
         config.setInitParmeter("authenticationFailureUrl", "/failed.jsp");
@@ -190,7 +190,7 @@ public class AuthenticationProcessingFilterTests extends TestCase {
 
         // Setup our filter configuration
         MockFilterConfig config = new MockFilterConfig();
-        config.setInitParmeter("appContextLocation",
+        config.setInitParmeter("contextConfigLocation",
             "net/sf/acegisecurity/ui/webapp/filtertest-valid.xml");
         config.setInitParmeter("defaultTargetUrl", "/");
         config.setInitParmeter("authenticationFailureUrl", "/failed.jsp");
@@ -222,7 +222,7 @@ public class AuthenticationProcessingFilterTests extends TestCase {
 
         // Setup our filter configuration
         MockFilterConfig config = new MockFilterConfig();
-        config.setInitParmeter("appContextLocation",
+        config.setInitParmeter("contextConfigLocation",
             "net/sf/acegisecurity/ui/webapp/filtertest-valid.xml");
         config.setInitParmeter("defaultTargetUrl", "/");
         config.setInitParmeter("authenticationFailureUrl", "/failed.jsp");
@@ -251,7 +251,7 @@ public class AuthenticationProcessingFilterTests extends TestCase {
 
         // Setup our filter configuration
         MockFilterConfig config = new MockFilterConfig();
-        config.setInitParmeter("appContextLocation",
+        config.setInitParmeter("contextConfigLocation",
             "net/sf/acegisecurity/ui/webapp/filtertest-valid.xml");
         config.setInitParmeter("defaultTargetUrl", "/");
         config.setInitParmeter("authenticationFailureUrl", "/failed.jsp");
@@ -268,12 +268,12 @@ public class AuthenticationProcessingFilterTests extends TestCase {
         assertTrue(request.getSession().getAttribute(HttpSessionIntegrationFilter.ACEGI_SECURITY_AUTHENTICATION_KEY) == null);
     }
 
-    public void testStartupDetectsInvalidAppContextLocation()
+    public void testStartupDetectsInvalidcontextConfigLocation()
         throws Exception {
         MockFilterConfig config = new MockFilterConfig();
         config.setInitParmeter("defaultTargetUrl", "/");
         config.setInitParmeter("authenticationFailureUrl", "/failed.jsp");
-        config.setInitParmeter("appContextLocation",
+        config.setInitParmeter("contextConfigLocation",
             "net/sf/acegisecurity/ui/webapp/filtertest-invalid.xml");
 
         AuthenticationProcessingFilter filter = new AuthenticationProcessingFilter();
@@ -301,7 +301,7 @@ public class AuthenticationProcessingFilterTests extends TestCase {
             assertTrue(expected.getMessage().startsWith("Error obtaining/creating ApplicationContext for config."));
         }
 
-        config.setInitParmeter("appContextLocation", "");
+        config.setInitParmeter("contextConfigLocation", "");
 
         try {
             filter.init(config);
@@ -314,7 +314,7 @@ public class AuthenticationProcessingFilterTests extends TestCase {
     public void testStartupDetectsMissingAuthenticationFailureUrl()
         throws Exception {
         MockFilterConfig config = new MockFilterConfig();
-        config.setInitParmeter("appContextLocation",
+        config.setInitParmeter("contextConfigLocation",
             "net/sf/acegisecurity/ui/webapp/filtertest-valid.xml");
         config.setInitParmeter("defaultTargetUrl", "/");
 
@@ -343,7 +343,7 @@ public class AuthenticationProcessingFilterTests extends TestCase {
         throws Exception {
         MockFilterConfig config = new MockFilterConfig();
         config.setInitParmeter("authenticationFailureUrl", "/failed.jsp");
-        config.setInitParmeter("appContextLocation",
+        config.setInitParmeter("contextConfigLocation",
             "net/sf/acegisecurity/ui/webapp/filtertest-valid.xml");
 
         AuthenticationProcessingFilter filter = new AuthenticationProcessingFilter();
@@ -367,12 +367,12 @@ public class AuthenticationProcessingFilterTests extends TestCase {
         }
     }
 
-    public void testStartupDetectsMissingInvalidAppContextLocation()
+    public void testStartupDetectsMissingInvalidcontextConfigLocation()
         throws Exception {
         MockFilterConfig config = new MockFilterConfig();
         config.setInitParmeter("defaultTargetUrl", "/");
         config.setInitParmeter("authenticationFailureUrl", "/failed.jsp");
-        config.setInitParmeter("appContextLocation", "DOES_NOT_EXIST");
+        config.setInitParmeter("contextConfigLocation", "DOES_NOT_EXIST");
 
         AuthenticationProcessingFilter filter = new AuthenticationProcessingFilter();
 
@@ -397,7 +397,7 @@ public class AuthenticationProcessingFilterTests extends TestCase {
 
         // Setup our filter configuration
         MockFilterConfig config = new MockFilterConfig();
-        config.setInitParmeter("appContextLocation",
+        config.setInitParmeter("contextConfigLocation",
             "net/sf/acegisecurity/ui/webapp/filtertest-valid.xml");
         config.setInitParmeter("defaultTargetUrl", "/");
         config.setInitParmeter("authenticationFailureUrl", "/failed.jsp");
@@ -442,7 +442,7 @@ public class AuthenticationProcessingFilterTests extends TestCase {
 
         // Setup our filter configuration
         MockFilterConfig config = new MockFilterConfig();
-        config.setInitParmeter("appContextLocation",
+        config.setInitParmeter("contextConfigLocation",
             "net/sf/acegisecurity/ui/webapp/filtertest-valid.xml");
         config.setInitParmeter("defaultTargetUrl", "/");
         config.setInitParmeter("authenticationFailureUrl", "/failed.jsp");

docs/reference/src/index.xml

@@ -7,7 +7,7 @@
 
     <subtitle>Reference Documentation</subtitle>
 
-    <releaseinfo>0.4</releaseinfo>
+    <releaseinfo>0.5</releaseinfo>
 
     <authorgroup>
       <author>
@@ -368,7 +368,7 @@
         <para>Whilst this may seem quite involved, don't worry. Developers
         interact with the security process by simply implementing basic
         interfaces (such as <literal>AccessDecisionManager</literal>), which
-        are fully documented below. </para>
+        are fully documented below.</para>
 
         <para>The <literal>AbstractSecurityInterceptor</literal> handles the
         majority of the flow listed above. Each secure object has its own
@@ -517,10 +517,6 @@
         provided below: <programlisting>&lt;filter&gt;
   &lt;filter-name&gt;Acegi HTTP Request Security Filter&lt;/filter-name&gt;
   &lt;filter-class&gt;net.sf.acegisecurity.intercept.web.SecurityEnforcementFilter&lt;/filter-class&gt;
-  &lt;init-param&gt;
-    &lt;param-name&gt;appContextLocation&lt;/param-name&gt;
-    &lt;param-value&gt;web-filters-acegisecurity.xml&lt;/param-value&gt;
-  &lt;/init-param&gt;
   &lt;init-param&gt;
     &lt;param-name&gt;loginFormUrl&lt;/param-name&gt;
     &lt;param-value&gt;/acegilogin.jsp&lt;/param-value&gt;
@@ -532,22 +528,31 @@
   &lt;url-pattern&gt;/*&lt;/url-pattern&gt;
 &lt;/filter-mapping&gt;</programlisting></para>
 
-        <para>As shown above, an <literal>appContextLocation</literal>
-        indicates the location of a Spring XML application context. In the
-        example above, this file should be placed at the root of the web
-        application's classpath (in the <literal>WEB-INF/classes</literal>
-        directory). The <literal>loginFormUrl</literal> is where the filter
-        will redirect the user's browser if they request a secure HTTP
-        resource but they are not authenticated. If the user is authenticated,
-        a "403 Forbidden" response will be returned to the browser. All paths
-        are relative to the web application root.</para>
-
-        <para>The <literal>SecurityEnforcementFilter</literal> will load the
-        Spring XML application context expressed in the
-        <literal>appContextLocation</literal>. It will expect to find in this
-        application context a properly configured
-        <literal>FilterSecurityInterceptor</literal>. The configuration of the
-        <literal>FilterSecurityInterceptor</literal> is very similar to the
+        <para>The <literal>loginFormUrl</literal> is where the filter will
+        redirect the user's browser if they request a secure HTTP resource but
+        they are not authenticated. If the user is authenticated, a "403
+        Forbidden" response will be returned to the browser. All paths are
+        relative to the web application root.</para>
+
+        <para>To perform its function, the
+        <literal>SecurityEnforcementFilter</literal> will need to delegate to
+        a properly configured <literal>FilterSecurityInterceptor</literal>. To
+        do this it requires access to a Spring application context, which is
+        usually obtained from
+        <literal>WebApplicationContextUtils.getWebApplicationContext(ServletContext)</literal>.
+        This is usually made available by using Spring's
+        <literal>ContextLoaderListener</literal> in
+        <literal>web.xml</literal>. Alternatively, the
+        <literal>web.xml</literal> can be used to define a filter
+        <literal>&lt;init-param&gt;</literal> named
+        <literal>contextConfigLocation</literal>. This initialization
+        parameter will represent a path to a Spring XML application context
+        that the <literal>SecurityEnforcementFilter</literal> will load during
+        startup.</para>
+
+        <para>The configuration of the
+        <literal>FilterSecurityInterceptor</literal> in the Spring application
+        context is very similar to the
         <literal>MethodSecurityInterceptor</literal>:</para>
 
         <para><programlisting>&lt;bean id="filterInvocationInterceptor" class="net.sf.acegisecurity.intercept.web.FilterSecurityInterceptor"&gt;
@@ -1470,10 +1475,6 @@ public boolean supports(Class clazz);</programlisting></para>
         <para><programlisting>&lt;filter&gt;
   &lt;filter-name&gt;Acegi Authentication Processing Filter&lt;/filter-name&gt;
   &lt;filter-class&gt;net.sf.acegisecurity.ui.webapp.AuthenticationProcessingFilter&lt;/filter-class&gt;
-  &lt;init-param&gt;
-    &lt;param-name&gt;appContextLocation&lt;/param-name&gt;
-    &lt;param-value&gt;web-filters-acegisecurity.xml&lt;/param-value&gt;
-  &lt;/init-param&gt;
   &lt;init-param&gt;
     &lt;param-name&gt;authenticationFailureUrl&lt;/param-name&gt;
     &lt;param-value&gt;/acegilogin.jsp?login_error=1&lt;/param-value&gt;
@@ -1493,14 +1494,23 @@ public boolean supports(Class clazz);</programlisting></para>
   &lt;url-pattern&gt;/*&lt;/url-pattern&gt;
 &lt;/filter-mapping&gt;</programlisting></para>
 
-        <para>The <literal>appContextLocation</literal> specifies the location
-        of a Spring XML application context. In the example above the root of
-        the classpath is used, so the XML file should be placed in
-        <literal>WEB-INF/classes</literal>. The
-        <literal>AuthenticationProcessingFilter</literal> will load this
-        application context, expecting to find a properly configured
-        <literal>AuthenticationManager</literal>. It will use this
-        <literal>AuthenticationManager</literal> to process each
+        <para>To perform its function, the
+        <literal>AuthenticationProcessingFilter</literal> will need to
+        delegate to a properly configured
+        <literal>AuthenticationManager</literal>. To do this it requires
+        access to a Spring application context, which is usually obtained from
+        <literal>WebApplicationContextUtils.getWebApplicationContext(ServletContext)</literal>.
+        This is usually made available by using Spring's
+        <literal>ContextLoaderListener</literal> in
+        <literal>web.xml</literal>. Alternatively, the
+        <literal>web.xml</literal> can be used to define a filter
+        <literal>&lt;init-param&gt;</literal> named
+        <literal>contextConfigLocation</literal>. This initialization
+        parameter will represent a path to a Spring XML application context
+        that the <literal>AuthenticationProcessingFilter</literal> will load
+        during startup.</para>
+
+        <para>The <literal>AuthenticationManager</literal> processes each
         authentication request. If authentication fails, the browser will be
         redirected to the <literal>authenticationFailureUrl</literal>. The
         <literal>AuthenticationException</literal> will be placed into the
@@ -1515,9 +1525,10 @@ public boolean supports(Class clazz);</programlisting></para>
         This becomes the "well-known location" from which the
         <literal>Authentication</literal> object is later extracted.</para>
 
-        <para>Once the HttpSession has been updated, the browser will need to
-        be redirected to the target URL. The target URL is usually indicated
-        by the <literal>HttpSession</literal> attribute specified by
+        <para>Once the <literal>HttpSession</literal> has been updated, the
+        browser will need to be redirected to the target URL. The target URL
+        is usually indicated by the <literal>HttpSession</literal> attribute
+        specified by
         <literal>AuthenticationProcessingFilter.ACEGI_SECURITY_TARGET_URL_KEY</literal>.
         This attribute is automatically set by the
         <literal>SecurityEnforcementFilter</literal> when an