Moved to doc subproject

docs/.cvsignore

@@ -1,2 +0,0 @@
-api
-

docs/reference/.cvsignore

@@ -1,5 +0,0 @@
-lib
-html
-html_single
-pdf
-

docs/reference/README

@@ -1,25 +0,0 @@
-We're using the DocBook XSL distribution for HTML and PDF
-generation. The best results can be achieved with the
-Saxon XSLT processor (don't use Xalan!) and the Apache
-FOP library.
-
-The documentation is generated by the build.xml file of
-Spring and Ant. Targets included are:
-
-- docpdf        - generates the PDF documentation
-- dochtml       - generates the HTML documentation
-- dochtmlsingle - generates single page HTML documenation
-- docclean      - clean any output directories for docs
-
-To generate documentation, you need to include a lot
-of libraries, which haven't been added to CVS because
-they're simply too big. The libraries can be found at:
-http://www.jteam.nl/spring/reference-libraries.zip.
-Download them, create a lib directory in the
-docs/reference directory and unzip the zip there.
-Then, the targets should work.
-
-Thanks to Hibernate, for providing the skeleton for
-DocBook documentation!
-
-alef@jteam.nl

docs/reference/src/index.xml

@@ -1,4015 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
-"../lib/docbook-dtd/docbookx.dtd">
-<book>
-  <bookinfo>
-    <title>Acegi Security System for Spring</title>
-
-    <subtitle>Reference Documentation</subtitle>
-
-    <releaseinfo>0.7</releaseinfo>
-
-    <authorgroup>
-      <author>
-        <firstname>Ben</firstname>
-
-        <surname>Alex</surname>
-      </author>
-    </authorgroup>
-  </bookinfo>
-
-  <toc></toc>
-
-  <preface id="preface">
-    <title>Preface</title>
-
-    <para>This document provides a reference guide to the Acegi Security
-    System for Spring, which is a series of classes that deliver
-    authentication and authorization services within the Spring
-    Framework.</para>
-
-    <para>I would like to acknowledge this reference was prepared using the
-    DocBook configuration included with the Spring Framework. The Spring team
-    in turn acknowledge Chris Bauer (Hibernate) for his assistance with their
-    DocBook.</para>
-  </preface>
-
-  <chapter id="security">
-    <title>Security</title>
-
-    <sect1 id="security-before-you-begin">
-      <title>Before You Begin</title>
-
-      <para>For your security, each official release JAR of Acegi Security has
-      been signed by the project leader. This does not in any way alter the
-      liability disclaimer contained in the License, but it does ensure you
-      are using a properly reviewed, official build of Acegi Security. Please
-      refer to the <literal>readme.txt</literal> file in the root of the
-      release distribution for instructions on how to validate the JARs are
-      correctly signed, and which certificate has been used to sign
-      them.</para>
-    </sect1>
-
-    <sect1 id="security-introduction">
-      <title>Introduction</title>
-
-      <para>The Acegi Security System for Spring provides authentication and
-      authorization capabilities for Spring-powered projects, with full
-      integration with popular web containers. The security architecture was
-      designed from the ground up using "The Spring Way" of development, which
-      includes using bean contexts, interceptors and interface-driven
-      programming. As a consequence, the Acegi Security System for Spring is
-      useful out-of-the-box for those seeking to secure their Spring-based
-      applications, and can be easily adapted to complex customized
-      requirements.</para>
-
-      <para>Security involves two distinct operations, authentication and
-      authorization. The former relates to resolving whether or not a caller
-      is who they claim to be. Authorization on the other hand relates to
-      determining whether or not an authenticated caller is permitted to
-      perform a given operation.</para>
-
-      <para>Throughout the Acegi Security System for Spring, the user, system
-      or agent that needs to be authenticated is referred to as a "principal".
-      The security architecture does not have a notion of roles or groups,
-      which you may be familiar with from other security
-      implementations.</para>
-
-      <sect2 id="security-introduction-status">
-        <title>Current Status</title>
-
-        <para>The Acegi Security System for Spring is widely used by members
-        of the Spring Community. The APIs are considered stable and only minor
-        changes are expected. Having said that, like many other projects we
-        need to strike a balance between backward compatibility and
-        improvement. Effective version 0.6.1, Acegi Security uses the Apache
-        Portable Runtime Project versioning guidelines, available from
-        <literal>http://apr.apache.org/versioning.html</literal>.</para>
-
-        <para>Some improvements are currently intended prior to the 1.0.0
-        release. These are:</para>
-
-        <itemizedlist spacing="compact">
-          <listitem>
-            <para>Replacing the Ant build with a Maven build. When this
-            happens the <literal>lib</literal> directory will no longer be
-            distributed in ZIP releases or hosted in CVS.</para>
-          </listitem>
-
-          <listitem>
-            <para>"Remember me" functionality. Some discussion on this can be
-            found at
-            <literal>http://sourceforge.net/mailarchive/forum.php?thread_id=5177499&amp;forum_id=40659</literal>.</para>
-          </listitem>
-
-          <listitem>
-            <para>A sample web application which demonstrates the access
-            control list package.</para>
-          </listitem>
-
-          <listitem>
-            <para>Implementation of an
-            <literal>ObjectDefinitionSource</literal> that retrieves its
-            details from a database.</para>
-          </listitem>
-
-          <listitem>
-            <para>Deprecation of Acegi Security's various EH-CACHE-based cache
-            implementations. Instead Acegi Security will provide new cache
-            implementations which use Spring Framework's new (currently in
-            CVS) <literal>EhCacheManagerFactoryBean</literal> factory. The
-            deprecated classes may be removed from the 1.0.0 release.</para>
-          </listitem>
-        </itemizedlist>
-
-        <para>Whilst this list is subject to change and not in any particular
-        order, none of the above improvements are likely to result in changes
-        to the API. The improvements are also relatively minor to implement.
-        Users of Acegi Security System for Spring should therefore be
-        comfortable depending on the current version of the project in their
-        applications.</para>
-      </sect2>
-    </sect1>
-
-    <sect1 id="security-high-level-design">
-      <title>High Level Design</title>
-
-      <sect2 id="security-high-level-design-key-components">
-        <title>Key Components</title>
-
-        <para>The Acegi Security System for Spring essentially comprises seven
-        key functional parts:</para>
-
-        <itemizedlist spacing="compact">
-          <listitem>
-            <para>An <literal>Authentication</literal> object which holds the
-            principal, credentials and the authorities granted to the
-            principal. The object can also store additional information
-            associated with an authentication request, such as the source
-            TCP/IP address.</para>
-          </listitem>
-
-          <listitem>
-            <para>A <literal>ContextHolder</literal> which holds the
-            <literal>Authentication</literal> object in a
-            <literal>ThreadLocal</literal>-bound object.</para>
-          </listitem>
-
-          <listitem>
-            <para>An <literal>AuthenticationManager</literal> to authenticate
-            the <literal>Authentication</literal> object presented via the
-            <literal>ContextHolder</literal>.</para>
-          </listitem>
-
-          <listitem>
-            <para>An <literal>AccessDecisionManager</literal> to authorize a
-            given operation.</para>
-          </listitem>
-
-          <listitem>
-            <para>A <literal>RunAsManager</literal> to optionally replace the
-            <literal>Authentication</literal> object whilst a given operation
-            is being executed.</para>
-          </listitem>
-
-          <listitem>
-            <para>A "secure object" interceptor, which coordinates the
-            authentication, authorization, run-as replacement and execution of
-            a given operation.</para>
-          </listitem>
-
-          <listitem>
-            <para>An acess control list (ACL) management package, which can be
-            used to obtain ACLs for domain object instances.</para>
-          </listitem>
-        </itemizedlist>
-
-        <para>Secure objects refer to any type of object that can have
-        security applied to it. A secure object must provide some form of
-        callback, so that the security interceptor can transparently do its
-        work as required, and callback the object when it is time for it to
-        proceed with the requested operation. If secure objects cannot provide
-        a native callback approach, a wrapper needs to be written so this
-        becomes possible.</para>
-
-        <para>Each secure object has its own package under
-        <literal>net.sf.acegisecurity.intercept</literal>. Every other package
-        in the security system is secure object independent, in that it can
-        support any type of secure object presented.</para>
-
-        <para>Only developers contemplating an entirely new way of
-        intercepting and authorizing requests would need to use secure objects
-        directly. For example, it would be possible to build a new secure
-        object to secure calls to a messaging system that does not use
-        <literal>MethodInvocation</literal>s. Most Spring applications will
-        simply use the three currently supported secure object types
-        (<literal>MethodInvocation</literal>, <literal>JoinPoint</literal> and
-        <literal>FilterInterceptor</literal>) with complete
-        transparency.</para>
-
-        <para>Each of the seven key parts is discussed in detail throughout
-        this document.</para>
-      </sect2>
-
-      <sect2 id="security-high-level-design-supported-secure-objects">
-        <title>Supported Secure Objects</title>
-
-        <para>The Acegi Security System for Spring currently supports three
-        secure objects.</para>
-
-        <para>The first handles an AOP Alliance
-        <literal>MethodInvocation</literal>. This is the secure object type
-        used to protect Spring beans. Developers will generally use this
-        secure object type to secure their business objects. To make a
-        standard Spring-hosted bean available as a
-        <literal>MethodInvocation</literal>, the bean is simply published
-        through a <literal>ProxyFactoryBean</literal> or
-        <literal>BeanNameAutoProxyCreator</literal> or
-        <literal>DefaultAdvisorAutoProxyCreator</literal>. Most Spring
-        developers would already be familiar with these due to their use in
-        transactions and other areas of Spring.</para>
-
-        <para>The second type is an AspectJ <literal>JoinPoint</literal>.
-        AspectJ has a particular use in securing domain object instances, as
-        these are most often managed outside the Spring bean container. By
-        using AspectJ, standard constructs such as <literal>new
-        Person();</literal> can be used and full security will be applied to
-        them by Acegi Security. The
-        <literal>AspectJSecurityInterceptor</literal> is still managed by
-        Spring, which creates the aspect singleton and wires it with the
-        appropriate authentication managers, access decision managers and so
-        on.</para>
-
-        <para>The third type is a <literal>FilterInvocation</literal>. This is
-        an object included with the Acegi Security System for Spring. It is
-        created by an included filter and simply wraps the HTTP
-        <literal>ServletRequest</literal>, <literal>ServletResponse</literal>
-        and <literal>FilterChain</literal>. The
-        <literal>FilterInvocation</literal> enables HTTP resources to be
-        secured. Developers do not usually need to understand the mechanics of
-        how this works, because they just add the filters to their
-        <literal>web.xml</literal> and let the security system do its
-        work.</para>
-      </sect2>
-
-      <sect2 id="security-high-level-design-configuration-attributes">
-        <title>Configuration Attributes</title>
-
-        <para>Every secure object can represent an infinite number of
-        individual requests. For example, a
-        <literal>MethodInvocation</literal> can represent the invocation of
-        any method with any arguments, whilst a
-        <literal>FilterInvocation</literal> can represent any HTTP URL.</para>
-
-        <para>The Acegi Security System for Spring needs to record the
-        configuration that applies to each of these possible requests. The
-        security configuration of a request to
-        <literal>BankManager.getBalance(int accountNumber)</literal> needs to
-        be very different from the security configuration of a request to
-        <literal>BankManager.approveLoan(int applicationNumber)</literal>.
-        Similarly, the security configuration of a request to
-        <literal>http://some.bank.com/index.htm</literal> needs to be very
-        different from the security configuration of
-        <literal>http://some.bank.com/manage/timesheet.jsp</literal>.</para>
-
-        <para>To store the various security configurations associated with
-        different requests, a configuration attribute is used. At an
-        implementation level a configuration attribute is represented by the
-        <literal>ConfigAttribute</literal> interface. One concrete
-        implementation of <literal>ConfigAttribute</literal> is provided,
-        <literal>SecurityConfig</literal>, which simply stores a configuration
-        attribute as a <literal>String</literal>.</para>
-
-        <para>The collection of <literal>ConfigAttribute</literal>s associated
-        with a particular request is held in a
-        <literal>ConfigAttributeDefinition</literal>. This concrete class is
-        simply a holder of <literal>ConfigAttribute</literal>s and does
-        nothing special.</para>
-
-        <para>When a request is received by the security interceptor, it needs
-        to determine which configuration attributes apply. In other words, it
-        needs to find the <literal>ConfigAttributeDefinition</literal> which
-        applies to the request. This decision is handled by the
-        <literal>ObjectDefinitionSource</literal> interface. The main method
-        provided by this interface is <literal>public
-        ConfigAttributeDefinition getAttributes(Object object)</literal>, with
-        the <literal>Object</literal> being the secure object. Recall the
-        secure object contains details of the request, so the
-        <literal>ObjectDefinitionSource</literal> implementation will be able
-        to extract the details it requires to lookup the relevant
-        <literal>ConfigAttributeDefinition</literal>.</para>
-      </sect2>
-    </sect1>
-
-    <sect1 id="security-request-contexts">
-      <title>Request Contexts</title>
-
-      <sect2 id="security-contexts">
-        <title>Contexts</title>
-
-        <para>Many applications require a way of sharing objects between
-        classes, but without resorting to passing them in method signatures.
-        This is commonly achieved by using a <literal>ThreadLocal</literal>.
-        The Acegi Security System for Spring uses
-        <literal>ThreadLocal</literal> functionality and introduces the
-        concept of "request contexts".</para>
-
-        <para>By placing an object into a request context, that object becomes
-        available to any other object on the current thread of execution. The
-        request context is not passed around as a method parameter, but is
-        held in a <literal>ThreadLocal</literal>. The Acegi Security System
-        for Spring uses the request context to pass around the authentication
-        request and response.</para>
-
-        <para>A request context is a concrete implementation of the
-        <literal>Context</literal> interface, which exposes a single
-        method:</para>
-
-        <programlisting>public void validate() throws ContextInvalidException;</programlisting>
-
-        <para>This <literal>validate()</literal> method is called to confirm
-        the <literal>Context</literal> is properly setup. An implementation
-        will typically use this method to check that the objects it holds are
-        properly setup.</para>
-
-        <para>The <literal>ContextHolder</literal> class makes the
-        <literal>Context</literal> available to the current thread of
-        execution using a <literal>ThreadLocal</literal>. A
-        <literal>ContextInterceptor</literal> is also provided, which is
-        intended to be chained into the bean context using
-        <literal>ProxyFactoryBean</literal>. The
-        <literal>ContextInterceptor</literal> simply calls
-        <literal>Context.validate()</literal>, which guarantees to business
-        methods that a valid <literal>Context</literal> is available from the
-        <literal>ContextHolder</literal>.</para>
-      </sect2>
-
-      <sect2 id="security-contexts-secure-contexts">
-        <title>Secure Contexts</title>
-
-        <para>The Acegi Security System for Spring requires the
-        <literal>ContextHolder</literal> to contain a request context that
-        implements the <literal>SecureContext</literal> interface. An
-        implementation is provided named <literal>SecureContextImpl</literal>.
-        The <literal>SecureContext</literal> simply extends the
-        <literal>Context</literal> discussed above and adds a holder and
-        validation for an <literal>Authentication</literal> object.</para>
-      </sect2>
-
-      <sect2 id="security-contexts-custom-contexts">
-        <title>Custom Contexts</title>
-
-        <para>Developers can create their own request context classes to store
-        application-specific objects. Such request context classes will need
-        to implement the <literal>Context</literal> interface. If the Acegi
-        Security System for Spring is to be used, developers must ensure any
-        custom request contexts implement the <literal>SecureContext</literal>
-        interface.</para>
-      </sect2>
-    </sect1>
-
-    <sect1 id="security-interception">
-      <title>Security Interception</title>
-
-      <sect2 id="security-interception-all-secure-objects">
-        <title>All Secure Objects</title>
-
-        <para>As described in the High Level Design section, each secure
-        object has its own security interceptor which is responsible for
-        handling each request. Handling involves a number of
-        operations:</para>
-
-        <orderedlist>
-          <listitem>
-            <para>Store the configuration attributes that are associated with
-            each secure request.</para>
-          </listitem>
-
-          <listitem>
-            <para>Extract the <literal>ConfigAttributeDefinition</literal>
-            that applies to the request from the relevant
-            <literal>ObjectDefinitionSource</literal>.</para>
-          </listitem>
-
-          <listitem>
-            <para>Obtain the <literal>Authentication</literal> object from the
-            <literal>SecureContext</literal>, which is held in the
-            <literal>ContextHolder</literal>.</para>
-          </listitem>
-
-          <listitem>
-            <para>Pass the <literal>Authentication</literal> object to the
-            <literal>AuthenticationManager</literal>, update the
-            <literal>ContextHolder</literal> with the response.</para>
-          </listitem>
-
-          <listitem>
-            <para>Pass the <literal>Authentication</literal> object, the
-            <literal>ConfigAttributeDefinition</literal>, and the secure
-            object to the <literal>AccessDecisionManager</literal>.</para>
-          </listitem>
-
-          <listitem>
-            <para>Pass the <literal>Authentication</literal> object, the
-            <literal>ConfigAttributeDefinition</literal>, and the secure
-            object to the <literal>RunAsManager</literal>.</para>
-          </listitem>
-
-          <listitem>
-            <para>If the <literal>RunAsManager</literal> returns a new
-            <literal>Authentication</literal> object, update the
-            <literal>ContextHolder</literal> with it.</para>
-          </listitem>
-
-          <listitem>
-            <para>Proceed with the request execution of the secure
-            object.</para>
-          </listitem>
-
-          <listitem>
-            <para>If the <literal>RunAsManager</literal> earlier returned a
-            new <literal>Authentication</literal> object, update the
-            <literal>ContextHolder</literal> with the
-            <literal>Authentication</literal> object that was previously
-            returned by the <literal>AuthenticationManager</literal>.</para>
-          </listitem>
-
-          <listitem>
-            <para>Return any result received from the secure object
-            execution.</para>
-          </listitem>
-        </orderedlist>
-
-        <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>
-
-        <para>The <literal>AbstractSecurityInterceptor</literal> handles the
-        majority of the flow listed above. Each secure object has its own
-        security interceptor which subclasses
-        <literal>AbstractSecurityInterceptor</literal>. Each of these secure
-        object-specific security interceptors are discussed below.</para>
-      </sect2>
-
-      <sect2 id="security-interception-aopalliance">
-        <title>AOP Alliance (MethodInvocation) Security Interceptor</title>
-
-        <para>To secure <literal>MethodInvocation</literal>s, developers
-        simply add a properly configured
-        <literal>MethodSecurityInterceptor</literal> into the application
-        context. Next the beans requiring security are chained into the
-        interceptor. This chaining is accomplished using Spring’s
-        <literal>ProxyFactoryBean</literal> or
-        <literal>BeanNameAutoProxyCreator</literal>, as commonly used by many
-        other parts of Spring (refer to the sample application for examples).
-        Alternatively, Acegi Security provides a
-        <literal>MethodDefinitionSourceAdvisor</literal> which may be used
-        with Spring's <literal>DefaultAdvisorAutoProxyCreator</literal> to
-        automatically chain the security interceptor in front of any beans
-        defined against the <literal>MethodSecurityInterceptor</literal>. The
-        <literal>MethodSecurityInterceptor</literal> itself is configured as
-        follows:</para>
-
-        <para><programlisting>&lt;bean id="bankManagerSecurity" class="net.sf.acegisecurity.intercept.method.aopalliance.MethodSecurityInterceptor"&gt;
-  &lt;property name="validateConfigAttributes"&gt;&lt;value&gt;true&lt;/value&gt;&lt;/property&gt;
-  &lt;property name="authenticationManager"&gt;&lt;ref bean="authenticationManager"/&gt;&lt;/property&gt;
-  &lt;property name="accessDecisionManager"&gt;&lt;ref bean="accessDecisionManager"/&gt;&lt;/property&gt;
-  &lt;property name="runAsManager"&gt;&lt;ref bean="runAsManager"/&gt;&lt;/property&gt;
-  &lt;property name="objectDefinitionSource"&gt;
-    &lt;value&gt;
-      net.sf.acegisecurity.context.BankManager.delete*=ROLE_SUPERVISOR,RUN_AS_SERVER
-      net.sf.acegisecurity.context.BankManager.getBalance=ROLE_TELLER,ROLE_SUPERVISOR,BANKSECURITY_CUSTOMER,RUN_AS_SERVER
-    &lt;/value&gt;
-  &lt;/property&gt;
-&lt;/bean&gt;</programlisting></para>
-
-        <para>As shown above, the <literal>MethodSecurityInterceptor</literal>
-        is configured with a reference to an
-        <literal>AuthenticationManager</literal>,
-        <literal>AccessDecisionManager</literal> and
-        <literal>RunAsManager</literal>, which are each discussed in separate
-        sections below. The <literal>MethodSecurityInterceptor</literal> is
-        also configured with configuration attributes that apply to different
-        method signatures. A full discussion of configuration attributes is
-        provided in the High Level Design section of this document.</para>
-
-        <para>The <literal>MethodSecurityInterceptor</literal> can be
-        configured with configuration attributes in three ways. The first is
-        via a property editor and the application context, which is shown
-        above. The second is via defining the configuration attributes in your
-        source code using Jakarta Commons Attributes. The third is via writing
-        your own <literal>ObjectDefinitionSource</literal>, although this is
-        beyond the scope of this document. Irrespective of the approach used,
-        the <literal>ObjectDefinitionSource</literal> is responsible for
-        returning a <literal>ConfigAttributeDefinition</literal> object that
-        contains all of the configuration attributes associated with a single
-        secure method.</para>
-
-        <para>It should be noted that the
-        <literal>MethodSecurityInterceptor.setObjectDefinitionSource()</literal>
-        method actually expects an instance of
-        <literal>MethodDefinitionSource</literal>. This is a marker interface
-        which subclasses <literal>ObjectDefinitionSource</literal>. It simply
-        denotes the <literal>ObjectDefinitionSource</literal> understands
-        <literal>MethodInvocation</literal>s. In the interests of simplicity
-        we'll continue to refer to the
-        <literal>MethodDefinitionSource</literal> as an
-        <literal>ObjectDefinitionSource</literal>, as the distinction is of
-        little relevance to most users of the
-        <literal>MethodSecurityInterceptor</literal>.</para>
-
-        <para>If using the application context property editor approach (as
-        shown above), commas are used to delimit the different configuration
-        attributes that apply to a given method pattern. Each configuration
-        attribute is assigned into its own <literal>SecurityConfig</literal>
-        object. The <literal>SecurityConfig</literal> object is discussed in
-        the High Level Design section.</para>
-
-        <para>If using the Jakarta Commons Attributes approach, your bean
-        context will be configured differently:</para>
-
-        <para><programlisting>&lt;bean id="attributes" class="org.springframework.metadata.commons.CommonsAttributes"/&gt;
-&lt;bean id="objectDefinitionSource" class="net.sf.acegisecurity.intercept.method.MethodDefinitionAttributes"&gt;
-  &lt;property name="attributes"&gt;&lt;ref local="attributes"/&gt;&lt;/property&gt;
-&lt;/bean&gt;
-
-&lt;bean id="bankManagerSecurity" class="net.sf.acegisecurity.intercept.method.MethodSecurityInterceptor"&gt;
-  &lt;property name="validateConfigAttributes"&gt;&lt;value&gt;false&lt;/value&gt;&lt;/property&gt;
-  &lt;property name="authenticationManager"&gt;&lt;ref bean="authenticationManager"/&gt;&lt;/property&gt;
-  &lt;property name="accessDecisionManager"&gt;&lt;ref bean="accessDecisionManager"/&gt;&lt;/property&gt;
-  &lt;property name="runAsManager"&gt;&lt;ref bean="runAsManager"/&gt;&lt;/property&gt;
-  &lt;property name="objectDefinitionSource"&gt;&lt;ref bean="objectDefinitionSource"/&gt;&lt;/property&gt;
-&lt;/bean&gt;</programlisting></para>
-
-        <para>In addition, your source code will contain Jakarta Commons
-        Attributes tags that refer to a concrete implementation of
-        <literal>ConfigAttribute</literal>. The following example uses the
-        <literal>SecurityConfig</literal> implementation to represent the
-        configuration attributes, and results in the same security
-        configuration as provided by the property editor approach
-        above:</para>
-
-        <para><programlisting>public interface BankManager {
-
-    /**
-     * @@SecurityConfig("ROLE_SUPERVISOR")
-     * @@SecurityConfig("RUN_AS_SERVER")
-     */
-    public void deleteSomething(int id);
-
-    /**
-     * @@SecurityConfig("ROLE_SUPERVISOR")
-     * @@SecurityConfig("RUN_AS_SERVER")
-     */
-    public void deleteAnother(int id);
-
-    /**
-     * @@SecurityConfig("ROLE_TELLER")
-     * @@SecurityConfig("ROLE_SUPERVISOR")
-     * @@SecurityConfig("BANKSECURITY_CUSTOMER")
-     * @@SecurityConfig("RUN_AS_SERVER")
-     */
-    public float getBalance(int id);
-}</programlisting></para>
-
-        <para>You might have noticed the
-        <literal>validateConfigAttributes</literal> property in the above
-        <literal>MethodSecurityInterceptor</literal> examples. When set to
-        <literal>true</literal> (the default), at startup time the
-        <literal>MethodSecurityInterceptor</literal> will evaluate if the
-        provided configuration attributes are valid. It does this by checking
-        each configuration attribute can be processed by either the
-        <literal>AccessDecisionManager</literal> or the
-        <literal>RunAsManager</literal>. If neither of these can process a
-        given configuration attribute, an exception is thrown. If using the
-        Jakarta Commons Attributes method of configuration, you should set
-        <literal>validateConfigAttributes</literal> to
-        <literal>false</literal>.</para>
-      </sect2>
-
-      <sect2 id="security-interception-aspectj">
-        <title>AspectJ (JoinPoint) Security Interceptor</title>
-
-        <para>The AspectJ security interceptor is very similar to the AOP
-        Alliance security interceptor discussed in the previous section.
-        Indeed we will only discuss the differences in this section.</para>
-
-        <para>The AspectJ interceptor is named
-        <literal>AspectJSecurityInterceptor</literal>. Unlike the AOP Alliance
-        security interceptor, which relies on the Spring application context
-        to weave in the security interceptor via proxying, the
-        <literal>AspectJSecurityInterceptor</literal> is weaved in via the
-        AspectJ compiler. It would not be uncommon to use both types of
-        security interceptors in the same application, with
-        <literal>AspectJSecurityInterceptor</literal> being used for domain
-        object instance security and the AOP Alliance
-        <literal>MethodSecurityInterceptor</literal> being used for services
-        layer security.</para>
-
-        <para>Let's first consider how the
-        <literal>AspectJSecurityInterceptor</literal> is configured in the
-        Spring application context:</para>
-
-        <para><programlisting>&lt;bean id="bankManagerSecurity" class="net.sf.acegisecurity.intercept.method.aspectj.AspectJSecurityInterceptor"&gt;
-  &lt;property name="validateConfigAttributes"&gt;&lt;value&gt;true&lt;/value&gt;&lt;/property&gt;
-  &lt;property name="authenticationManager"&gt;&lt;ref bean="authenticationManager"/&gt;&lt;/property&gt;
-  &lt;property name="accessDecisionManager"&gt;&lt;ref bean="accessDecisionManager"/&gt;&lt;/property&gt;
-  &lt;property name="runAsManager"&gt;&lt;ref bean="runAsManager"/&gt;&lt;/property&gt;
-  &lt;property name="objectDefinitionSource"&gt;
-    &lt;value&gt;
-      net.sf.acegisecurity.context.BankManager.delete*=ROLE_SUPERVISOR,RUN_AS_SERVER
-      net.sf.acegisecurity.context.BankManager.getBalance=ROLE_TELLER,ROLE_SUPERVISOR,BANKSECURITY_CUSTOMER,RUN_AS_SERVER
-    &lt;/value&gt;
-  &lt;/property&gt;
-&lt;/bean&gt;</programlisting></para>
-
-        <para>As you can see, aside from the class name, the
-        <literal>AspectJSecurityInterceptor</literal> is exactly the same as
-        the AOP Alliance security interceptor. Indeed the two interceptors can
-        share the same <literal>objectDefinitionSource</literal>, as the
-        <literal>ObjectDefinitionSource</literal> works with
-        <literal>java.lang.reflect.Method</literal>s rather than an AOP
-        library-specific class. Of course, your access decisions have access
-        to the relevant AOP library-specific invocation (ie
-        <literal>MethodInvocation</literal> or <literal>JoinPoint</literal>)
-        and as such can consider a range of addition criteria when making
-        access decisions (such as method arguments).</para>
-
-        <para>Next you'll need to define an AspectJ <literal>aspect</literal>.
-        For example:</para>
-
-        <para><programlisting>package net.sf.acegisecurity.samples.aspectj;
-
-import net.sf.acegisecurity.intercept.method.aspectj.AspectJSecurityInterceptor;
-import net.sf.acegisecurity.intercept.method.aspectj.AspectJCallback;
-import org.springframework.beans.factory.InitializingBean;
-
-public aspect DomainObjectInstanceSecurityAspect implements InitializingBean {
-
-  private AspectJSecurityInterceptor securityInterceptor;
-
-  pointcut domainObjectInstanceExecution(): target(PersistableEntity) 
-             &amp;&amp; execution(public * *(..)) &amp;&amp; !within(DomainObjectInstanceSecurityAspect);
-
-  Object around(): domainObjectInstanceExecution() {
-    if (this.securityInterceptor != null) {
-      AspectJCallback callback = new AspectJCallback() {
-        public Object proceedWithObject() {
-        return proceed();
-      }
-    };
-    return this.securityInterceptor.invoke(thisJoinPoint, callback);
-    } else {
-      return proceed();
-    }
-  }
-
-  public AspectJSecurityInterceptor getSecurityInterceptor() {
-    return securityInterceptor;
-  }
-
-  public void setSecurityInterceptor(AspectJSecurityInterceptor securityInterceptor) {
-    this.securityInterceptor = securityInterceptor;
-  }
-
-  public void afterPropertiesSet() throws Exception {
-    if (this.securityInterceptor == null)
-      throw new IllegalArgumentException("securityInterceptor required");
-  }
-}</programlisting></para>
-
-        <para>In the above example, the security interceptor will be applied
-        to every instance of <literal>PersistableEntity</literal>, which is an
-        abstract class not shown (you can use any other class or
-        <literal>pointcut</literal> expression you like). For those curious,
-        <literal>AspectJCallback</literal> is needed because the
-        <literal>proceed();</literal> statement has special meaning only
-        within an <literal>around()</literal> body. The
-        <literal>AspectJSecurityInterceptor</literal> calls this anonymous
-        <literal>AspectJCallback</literal> class when it wants the target
-        object to continue.</para>
-
-        <para>You will need to configure Spring to load the aspect and wire it
-        with the <literal>AspectJSecurityInterceptor</literal>. A bean
-        declaration which achieves this is shown below:</para>
-
-        <para><programlisting>&lt;bean id="domainObjectInstanceSecurityAspect" 
-    class="net.sf.acegisecurity.samples.aspectj.DomainObjectInstanceSecurityAspect"
-    factory-method="aspectOf"&gt;
-  &lt;property name="securityInterceptor"&gt;&lt;ref bean="aspectJSecurityInterceptor"/&gt;&lt;/property&gt;
-&lt;/bean&gt;</programlisting></para>
-
-        <para>That's it! Now you can create your beans from anywhere within
-        your application, using whatever means you think fit (eg <literal>new
-        Person();</literal>) and they will have the security interceptor
-        applied.</para>
-      </sect2>
-
-      <sect2 id="security-interception-filterinvocation">
-        <title>FilterInvocation Security Interceptor</title>
-
-        <para>To secure <literal>FilterInvocation</literal>s, developers need
-        to add a filter to their <literal>web.xml</literal> that delegates to
-        the <literal>SecurityEnforcementFilter</literal>. A typical
-        configuration example is 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.util.FilterToBeanProxy&lt;/filter-class&gt;
-  &lt;init-param&gt;
-    &lt;param-name&gt;targetClass&lt;/param-name&gt;
-    &lt;param-value&gt;net.sf.acegisecurity.intercept.web.SecurityEnforcementFilter&lt;/param-value&gt;
-  &lt;/init-param&gt;
-&lt;/filter&gt;
-
-&lt;filter-mapping&gt;
-  &lt;filter-name&gt;Acegi HTTP Request Security Filter&lt;/filter-name&gt;
-  &lt;url-pattern&gt;/*&lt;/url-pattern&gt;
-&lt;/filter-mapping&gt;</programlisting></para>
-
-        <para>Notice that the filter is actually a
-        <literal>FilterToBeanProxy</literal>. Most of the filters used by the
-        Acegi Security System for Spring use this class. Refer to the Filters
-        section to learn more about this bean.</para>
-
-        <para>In the application context you will need to configure three
-        beans:</para>
-
-        <programlisting>&lt;bean id="securityEnforcementFilter" class="net.sf.acegisecurity.intercept.web.SecurityEnforcementFilter"&gt;
-  &lt;property name="filterSecurityInterceptor"&gt;&lt;ref bean="filterInvocationInterceptor"/&gt;&lt;/property&gt;
-  &lt;property name="authenticationEntryPoint"&gt;&lt;ref bean="authenticationEntryPoint"/&gt;&lt;/property&gt;
-&lt;/bean&gt;
-
-&lt;bean id="authenticationEntryPoint" class="net.sf.acegisecurity.ui.webapp.AuthenticationProcessingFilterEntryPoint"&gt;
-  &lt;property name="loginFormUrl"&gt;&lt;value&gt;/acegilogin.jsp&lt;/value&gt;&lt;/property&gt;
-  &lt;property name="forceHttps"&gt;&lt;value&gt;false&lt;/value&gt;&lt;/property&gt;
-&lt;/bean&gt;
-
-&lt;bean id="filterInvocationInterceptor" class="net.sf.acegisecurity.intercept.web.FilterSecurityInterceptor"&gt;
-  &lt;property name="authenticationManager"&gt;&lt;ref bean="authenticationManager"/&gt;&lt;/property&gt;
-  &lt;property name="accessDecisionManager"&gt;&lt;ref bean="accessDecisionManager"/&gt;&lt;/property&gt;
-  &lt;property name="runAsManager"&gt;&lt;ref bean="runAsManager"/&gt;&lt;/property&gt;
-  &lt;property name="objectDefinitionSource"&gt;
-    &lt;value&gt;
-      CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON
-      \A/secure/super/.*\Z=ROLE_WE_DONT_HAVE
-      \A/secure/.*\Z=ROLE_SUPERVISOR,ROLE_TELLER
-    &lt;/value&gt;
-  &lt;/property&gt;
-&lt;/bean&gt;</programlisting>
-
-        <para>The <literal>AuthenticationEntryPoint</literal> will be called
-        if the user requests a secure HTTP resource but they are not
-        authenticated. The class handles presenting the appropriate response
-        to the user so that authentication can begin. Three concrete
-        implementations are provided with the Acegi Security System for
-        Spring: <literal>AuthenticationProcessingFilterEntryPoint</literal>
-        for commencing a form-based authentication,
-        <literal>BasicProcessingFilterEntryPoint</literal> for commencing a
-        Http Basic authentication process, and
-        <literal>CasProcessingFilterEntryPoint</literal> for commencing a Yale
-        Central Authentication Service (CAS) login. The
-        <literal>AuthenticationProcessingFilterEntryPoint</literal> and
-        <literal>CasProcessingFilterEntryPoint</literal> have optional
-        properties related to forcing the use of HTTPS, so please refer to the
-        JavaDocs if you require this.</para>
-
-        <para>The <literal>PortMapper</literal> provides information on which
-        HTTPS ports correspond to which HTTP ports. This is used by the
-        <literal>AuthenticationProcessingFilterEntryPoint</literal> and
-        several other beans. The default implementation,
-        <literal>PortMapperImpl</literal>, knows the common HTTP ports 80 and
-        8080 map to HTTPS ports 443 and 8443 respectively. You can customise
-        this mapping if desired.</para>
-
-        <para>The <literal>SecurityEnforcementFilter</literal> primarily
-        provides session management support and initiates authentication when
-        required. It delegates actual <literal>FilterInvocation</literal>
-        security decisions to the configured
-        <literal>FilterSecurityInterceptor</literal>.</para>
-
-        <para>Like any other security interceptor, the
-        <literal>FilterSecurityInterceptor</literal> requires a reference to
-        an <literal>AuthenticationManager</literal>,
-        <literal>AccessDecisionManager</literal> and
-        <literal>RunAsManager</literal>, which are each discussed in separate
-        sections below. The <literal>FilterSecurityInterceptor</literal> is
-        also configured with configuration attributes that apply to different
-        HTTP URL requests. A full discussion of configuration attributes is
-        provided in the High Level Design section of this document.</para>
-
-        <para>The <literal>FilterSecurityInterceptor</literal> can be
-        configured with configuration attributes in two ways. The first is via
-        a property editor and the application context, which is shown above.
-        The second is via writing your own
-        <literal>ObjectDefinitionSource</literal>, although this is beyond the
-        scope of this document. Irrespective of the approach used, the
-        <literal>ObjectDefinitionSource</literal> is responsible for returning
-        a <literal>ConfigAttributeDefinition</literal> object that contains
-        all of the configuration attributes associated with a single secure
-        HTTP URL.</para>
-
-        <para>It should be noted that the
-        <literal>FilterSecurityInterceptor.setObjectDefinitionSource()</literal>
-        method actually expects an instance of
-        <literal>FilterInvocationDefinitionSource</literal>. This is a marker
-        interface which subclasses <literal>ObjectDefinitionSource</literal>.
-        It simply denotes the <literal>ObjectDefinitionSource</literal>
-        understands <literal>FilterInvocation</literal>s. In the interests of
-        simplicity we'll continue to refer to the
-        <literal>FilterInvocationDefinitionSource</literal> as an
-        <literal>ObjectDefinitionSource</literal>, as the distinction is of
-        little relevance to most users of the
-        <literal>FilterSecurityInterceptor</literal>.</para>
-
-        <para>If using the application context property editor approach (as
-        shown above), commas are used to delimit the different configuration
-        attributes that apply to each HTTP URL. Each configuration attribute
-        is assigned into its own <literal>SecurityConfig</literal> object. The
-        <literal>SecurityConfig</literal> object is discussed in the High
-        Level Design section. The <literal>ObjectDefinitionSource</literal>
-        created by the property editor,
-        <literal>FilterInvocationDefinitionSource</literal>, matches
-        configuration attributes against <literal>FilterInvocations</literal>
-        based on expression evaluation of the request URL. Two standard
-        expression syntaxes are supported. The default is to treat all
-        expressions as regular expressions. Alternatively, the presence of a
-        <literal>PATTERN_TYPE_APACHE_ANT</literal> directive will cause all
-        expressions to be treated as Apache Ant paths. It is not possible to
-        mix expression syntaxes within the same definition. For example, the
-        earlier configuration could be generated using Apache Ant paths as
-        follows:</para>
-
-        <para><programlisting>&lt;bean id="filterInvocationInterceptor" class="net.sf.acegisecurity.intercept.web.FilterSecurityInterceptor"&gt;
-  &lt;property name="authenticationManager"&gt;&lt;ref bean="authenticationManager"/&gt;&lt;/property&gt;
-  &lt;property name="accessDecisionManager"&gt;&lt;ref bean="accessDecisionManager"/&gt;&lt;/property&gt;
-  &lt;property name="runAsManager"&gt;&lt;ref bean="runAsManager"/&gt;&lt;/property&gt;
-  &lt;property name="objectDefinitionSource"&gt;
-    &lt;value&gt;
-      CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON
-      PATTERN_TYPE_APACHE_ANT
-      /secure/super/**=ROLE_WE_DONT_HAVE
-      /secure/**=ROLE_SUPERVISOR,ROLE_TELLER
-    &lt;/value&gt;
-  &lt;/property&gt;
-&lt;/bean&gt;</programlisting></para>
-
-        <para>Irrespective of the type of expression syntax used, expressions
-        are always evaluated in the order they are defined. Thus it is
-        important that more specific expressions are defined higher in the
-        list than less specific expressions. This is reflected in our example
-        above, where the more specific <literal>/secure/super/</literal>
-        pattern appears higher than the less specific
-        <literal>/secure/</literal> pattern. If they were reversed, the
-        <literal>/secure/</literal> pattern would always match and the
-        <literal>/secure/super/</literal> pattern would never be
-        evaluated.</para>
-
-        <para>The special keyword
-        <literal>CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON</literal> causes
-        the <literal>FilterInvocationDefinitionSource</literal> to
-        automatically convert a request URL to lowercase before comparison
-        against the expressions. Whilst by default the case of the request URL
-        is not converted, it is generally recommended to use
-        <literal>CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON</literal> and
-        write each expression assuming lowercase.</para>
-
-        <para>As with other security interceptors, the
-        <literal>validateConfigAttributes</literal> property is observed. When
-        set to <literal>true</literal> (the default), at startup time the
-        <literal>FilterSecurityInterceptor</literal> will evaluate if the
-        provided configuration attributes are valid. It does this by checking
-        each configuration attribute can be processed by either the
-        <literal>AccessDecisionManager</literal> or the
-        <literal>RunAsManager</literal>. If neither of these can process a
-        given configuration attribute, an exception is thrown.</para>
-      </sect2>
-    </sect1>
-
-    <sect1 id="security-authentication">
-      <title>Authentication</title>
-
-      <sect2 id="security-authentication-requests">
-        <title>Authentication Requests</title>
-
-        <para>Authentication requires a way for client code to present its
-        security identification to the Acegi Security System for Spring. This
-        is the role of the <literal>Authentication</literal> interface. The
-        <literal>Authentication</literal> interface holds three important
-        objects: the principal (the identity of the caller), the credentials
-        (the proof of the identity of the caller, such as a password), and the
-        authorities that have been granted to the principal. The principal and
-        its credentials are populated by the client code, whilst the granted
-        authorities are populated by the
-        <literal>AuthenticationManager</literal>. The Acegi Security System
-        for Spring includes several concrete <literal>Authentication</literal>
-        implementations:</para>
-
-        <itemizedlist spacing="compact">
-          <listitem>
-            <para><literal>UsernamePasswordAuthenticationToken</literal>
-            allows a username and password to be presented as the principal
-            and credentials respectively. It is also what is created by the
-            HTTP Session Authentication system.</para>
-          </listitem>
-
-          <listitem>
-            <para><literal>TestingAuthenticationToken</literal> facilitates
-            unit testing by automatically being considered an authenticated
-            object by its associated
-            <literal>AuthenticationProvider</literal>.</para>
-          </listitem>
-
-          <listitem>
-            <para><literal>RunAsUserToken</literal> is used by the default
-            run-as authentication replacement implementation. This is
-            discussed further in the Run-As Authentication Replacement
-            section.</para>
-          </listitem>
-
-          <listitem>
-            <para><literal>CasAuthenticationToken</literal> is used to
-            represent a successful Yale Central Authentication Service (CAS)
-            authentication. This is discussed further in the CAS
-            section.</para>
-          </listitem>
-
-          <listitem>
-            <para><literal>PrincipalAcegiUserToken</literal> and
-            <literal>JettyAcegiUserToken</literal> implement
-            <literal>AuthByAdapter</literal> (a subclass of
-            <literal>Authentication</literal>) and are used whenever
-            authentication is completed by Acegi Security System for Spring
-            container adapters. This is discussed further in the Container
-            Adapters section.</para>
-          </listitem>
-        </itemizedlist>
-
-        <para>The authorities granted to a principal are represented by the
-        <literal>GrantedAuthority</literal> interface. The
-        <literal>GrantedAuthority</literal> interface is discussed at length
-        in the Authorization section.</para>
-      </sect2>
-
-      <sect2 id="security-authentication-manager">
-        <title>Authentication Manager</title>
-
-        <para>As discussed in the Security Interception section, the
-        <literal>AbstractSecurityInterceptor</literal> extracts the
-        <literal>Authentication</literal> object from the
-        <literal>SecureContext</literal> in the
-        <literal>ContextHolder</literal>. This is then passed to an
-        <literal>AuthenticationManager</literal>. The
-        <literal>AuthenticationManager</literal> interface is very
-        simple:</para>
-
-        <programlisting>public Authentication authenticate(Authentication authentication) throws AuthenticationException;</programlisting>
-
-        <para>Implementations of <literal>AuthenticationManager</literal> are
-        required to throw an <literal>AuthenticationException</literal> should
-        authentication fail, or return a fully populated
-        <literal>Authentication</literal> object. In particular, the returned
-        <literal>Authentication</literal> object should contain an array of
-        <literal>GrantedAuthority</literal> objects. The
-        <literal>SecurityInterceptor</literal> places the populated
-        <literal>Authentication</literal> object back in the
-        <literal>SecureContext</literal> in the
-        <literal>ContextHolder</literal>, overwriting the original
-        <literal>Authentication</literal> object.</para>
-
-        <para>The <literal>AuthenticationException</literal> has a number of
-        subclasses. The most important are
-        <literal>BadCredentialsException</literal> (an incorrect principal or
-        credentials), <literal>DisabledException</literal> and
-        <literal>LockedException</literal>. The latter two exceptions indicate
-        the principal was found, but the credentials were not checked and
-        authentication is denied. An
-        <literal>AuthenticationServiceException</literal> is also provided,
-        which indicates the authentication system could not process the
-        request (eg a database was unavailable).</para>
-      </sect2>
-
-      <sect2 id="security-authentication-provider">
-        <title>Provider-Based Authentication</title>
-
-        <para>Whilst the basic <literal>Authentication</literal> and
-        <literal>AuthenticationManager</literal> interfaces enable users to
-        develop their own authentication systems, users should consider using
-        the provider-based authentication packages provided by the Acegi
-        Security System for Spring. The key class,
-        <literal>ProviderManager</literal>, is configured via the bean context
-        with a list of <literal>AuthenticationProvider</literal>s:</para>
-
-        <para><programlisting>&lt;bean id="authenticationManager" class="net.sf.acegisecurity.providers.ProviderManager"&gt;
-  &lt;property name="providers"&gt;
-    &lt;list&gt;
-      &lt;ref bean="daoAuthenticationProvider"/&gt;
-      &lt;ref bean="someOtherAuthenticationProvider"/&gt;
-    &lt;/list&gt;
-  &lt;/property&gt;
-&lt;/bean&gt;</programlisting></para>
-
-        <para><literal>ProviderManager</literal> calls a series of registered
-        <literal>AuthenticationProvider</literal> implementations, until one
-        is found that indicates it is able to authenticate a given
-        <literal>Authentication</literal> class. When the first compatible
-        <literal>AuthenticationProvider</literal> is located, it is passed the
-        authentication request. The <literal>AuthenticationProvider</literal>
-        will then either throw an <literal>AuthenticationException</literal>
-        or return a fully populated <literal>Authentication</literal>
-        object.</para>
-
-        <para>Note the <literal>ProviderManager</literal> may throw a
-        <literal>ProviderNotFoundException</literal> (a subclass of
-        <literal>AuthenticationException</literal>) if it none of the
-        registered <literal>AuthenticationProviders</literal> can validate the
-        <literal>Authentication</literal> object.</para>
-
-        <para>Several <literal>AuthenticationProvider</literal>
-        implementations are provided with the Acegi Security System for
-        Spring:</para>
-
-        <para><itemizedlist spacing="compact">
-            <listitem>
-              <para><literal>TestingAuthenticationProvider</literal> is able
-              to authenticate a <literal>TestingAuthenticationToken</literal>.
-              The limit of its authentication is simply to treat whatever is
-              contained in the <literal>TestingAuthenticationToken</literal>
-              as valid. This makes it ideal for use during unit testing, as
-              you can create an <literal>Authentication</literal> object with
-              precisely the <literal>GrantedAuthority</literal> objects
-              required for calling a given method. You definitely would not
-              register this <literal>AuthenticationProvider</literal> on a
-              production system.</para>
-            </listitem>
-
-            <listitem>
-              <para><literal>DaoAuthenticationProvider</literal> is able to
-              authenticate a
-              <literal>UsernamePasswordAuthenticationToken</literal> by
-              accessing an authentication respository via a data access
-              object. This is discussed further below, as it is the main way
-              authentication is initially handled.</para>
-            </listitem>
-
-            <listitem>
-              <para><literal>RunAsImplAuthenticationToken</literal> is able to
-              authenticate a <literal>RunAsUserToken</literal>. This is
-              discussed further in the Run-As Authentication Replacement
-              section. You would not register this
-              <literal>AuthenticationProvider</literal> if you were not using
-              run-as replacement.</para>
-            </listitem>
-
-            <listitem>
-              <para><literal>AuthByAdapterProvider</literal> is able to
-              authenticate any <literal>AuthByAdapter</literal> (a subclass of
-              <literal>Authentication</literal> used with container adapters).
-              This is discussed further in the Container Adapters section. You
-              would not register this
-              <literal>AuthenticationProvider</literal> if you were not using
-              container adapters.</para>
-            </listitem>
-
-            <listitem>
-              <para><literal>CasAuthenticationProvider</literal> is able to
-              authenticate Yale Central Authentication Service (CAS) tickets.
-              This is discussed further in the CAS Single Sign On
-              section.</para>
-            </listitem>
-
-            <listitem>
-              <para><literal>JaasAuthenticationProvider</literal> is able to
-              delegate authentication requests to a JAAS
-              <literal>LoginModule</literal>. This is discussed further
-              below.</para>
-            </listitem>
-          </itemizedlist></para>
-      </sect2>
-
-      <sect2 id="security-authentication-provider-dao">
-        <title>Data Access Object Authentication Provider</title>
-
-        <para>The Acegi Security System for Spring includes a
-        production-quality <literal>AuthenticationProvider</literal>
-        implementation called <literal>DaoAuthenticationProvider</literal>.
-        This authentication provider is able to authenticate a
-        <literal>UsernamePasswordAuthenticationToken</literal> by obtaining
-        authentication details from a data access object configured at bean
-        creation time:</para>
-
-        <para><programlisting>&lt;bean id="daoAuthenticationProvider" class="net.sf.acegisecurity.providers.dao.DaoAuthenticationProvider"&gt;
-  &lt;property name="authenticationDao"&gt;&lt;ref bean="inMemoryDaoImpl"/&gt;&lt;/property&gt;
-  &lt;property name="saltSource"&gt;&lt;ref bean="saltSource"/&gt;&lt;/property&gt;
-  &lt;property name="passwordEncoder"&gt;&lt;ref bean="passwordEncoder"/&gt;&lt;/property&gt;
-&lt;/bean&gt;</programlisting></para>
-
-        <para>The <literal>PasswordEncoder</literal> and
-        <literal>SaltSource</literal> are optional. A
-        <literal>PasswordEncoder</literal> provides encoding and decoding of
-        passwords obtained from the authentication repository. A
-        <literal>SaltSource</literal> enables the passwords to be populated
-        with a "salt", which enhances the security of the passwords in the
-        authentication repository. <literal>PasswordEncoder</literal>
-        implementations are provided with the Acegi Security System for Spring
-        covering MD5, SHA and cleartext encodings. Two
-        <literal>SaltSource</literal> implementations are also provided:
-        <literal>SystemWideSaltSource</literal> which encodes all passwords
-        with the same salt, and <literal>ReflectionSaltSource</literal>, which
-        inspects a given property of the returned
-        <literal>UserDetails</literal> object to obtain the salt. Please refer
-        to the JavaDocs for further details on these optional features.</para>
-
-        <para>In addition to the properties above, the
-        <literal>DaoAuthenticationProvider</literal> supports optional caching
-        of <literal>UserDetails</literal> objects. The
-        <literal>UserCache</literal> interface enables the
-        <literal>DaoAuthenticationProvider</literal> to place a
-        <literal>UserDetails</literal> object into the cache, and retrieve it
-        from the cache upon subsequent authentication attempts for the same
-        username. By default the <literal>DaoAuthenticationProvider</literal>
-        uses the <literal>NullUserCache</literal>, which performs no caching.
-        A usable caching implementation is also provided,
-        <literal>EhCacheBasedUserCache</literal>, which is configured as
-        follows:</para>
-
-        <para><programlisting>&lt;bean id="daoAuthenticationProvider" class="net.sf.acegisecurity.providers.dao.DaoAuthenticationProvider"&gt;
-  &lt;property name="authenticationDao"&gt;&lt;ref bean="authenticationDao"/&gt;&lt;/property&gt;
-  &lt;property name="userCache"&gt;&lt;ref bean="userCache"/&gt;&lt;/property&gt;
-&lt;/bean&gt;
-
-&lt;bean id="userCache" class="net.sf.acegisecurity.providers.dao.cache.EhCacheBasedUserCache"&gt;
-  &lt;property name="minutesToIdle"&gt;&lt;value&gt;5&lt;/value&gt;&lt;/property&gt;
-&lt;/bean&gt;</programlisting></para>
-
-        <para>For a class to be able to provide the
-        <literal>DaoAuthenticationProvider</literal> with access to an
-        authentication repository, it must implement the
-        <literal>AuthenticationDao</literal> interface:</para>
-
-        <para><programlisting>public UserDetails loadUserByUsername(String username) throws UsernameNotFoundException, DataAccessException;</programlisting></para>
-
-        <para>The <literal>UserDetails</literal> is an interface that provides
-        getters that guarantee non-null provision of basic authentication
-        information such as the username, password, granted authorities and
-        whether the user is enabled or disabled. A concrete implementation,
-        <literal>User</literal>, is also provided. Acegi Security users will
-        need to decide when writing their <literal>AuthenticationDao</literal>
-        what type of <literal>UserDetails</literal> to return. In most cases
-        <literal>User</literal> will be used directly or subclassed, although
-        special circumstances (such as object relational mappers) may require
-        users to write their own <literal>UserDetails</literal> implementation
-        from scratch.</para>
-
-        <para>Given <literal>AuthenticationDao</literal> is so simple to
-        implement, it should be easy for users to retrieve authentication
-        information using a persistence strategy of their choice.</para>
-
-        <para>A design decision was made not to support account locking in the
-        <literal>DaoAuthenticationProvider</literal>, as doing so would have
-        increased the complexity of the <literal>AuthenticationDao</literal>
-        interface. For instance, a method would be required to increase the
-        count of unsuccessful authentication attempts. Such functionality
-        could be easily provided by leveraging the application event
-        publishing features discussed below.</para>
-
-        <para><literal>DaoAuthenticationProvider</literal> returns an
-        <literal>Authentication</literal> object which in turn has its
-        <literal>principal</literal> property set. The principal will be
-        either a <literal>String</literal> (which is essentially the username)
-        or a <literal>UserDetails</literal> object (which was looked up from
-        the <literal>AuthenticationDao</literal>). By default the
-        <literal>UserDetails</literal> is returned, as this enables
-        applications to add extra properties potentially of use in
-        applications, such as the user's full name, email address etc. If
-        using container adapters, or if your applications were written to
-        operate with <literal>String</literal>s (as was the case for releases
-        prior to Acegi Security 0.6), you should set the
-        <literal>DaoAuthenticationProvider.forcePrincipalAsString</literal>
-        property to <literal>true</literal> in your application
-        context.</para>
-      </sect2>
-
-      <sect2 id="security-authentication-provider-events">
-        <title>Event Publishing</title>
-
-        <para>The <literal>DaoAuthenticationProvider</literal> automatically
-        obtains the <literal>ApplicationContext</literal> it is running in at
-        startup time. This allows the provider to publish events through the
-        standard Spring event framework. Three types of event messages are
-        published:</para>
-
-        <itemizedlist spacing="compact">
-          <listitem>
-            <para><literal>AuthenticationSuccessEvent</literal> is published
-            when an authentication request is successful.</para>
-          </listitem>
-
-          <listitem>
-            <para><literal>AuthenticationFailureDisabledEvent</literal> is
-            published when an authentication request is unsuccessful because
-            the returned <literal>UserDetails</literal> is disabled. This is
-            normally the case when an account is locked.</para>
-          </listitem>
-
-          <listitem>
-            <para><literal>AuthenticationFailureUsernameNotFoundEvent</literal>
-            is published when an authentication request is unsuccessful
-            because the <literal>AuthenticationDao</literal> could not locate
-            the <literal>UserDetails</literal>.</para>
-          </listitem>
-
-          <listitem>
-            <para><literal>AuthenticationFailurePasswordEvent</literal> is
-            published when an authentication request is unsuccessful because
-            the presented password did not match that in the
-            <literal>UserDetails</literal>.</para>
-          </listitem>
-        </itemizedlist>
-
-        <para>Each event contains two objects: the
-        <literal>Authentication</literal> object that represented the
-        authentication request, and the <literal>UserDetails</literal> object
-        that was found in response to the authentication request (clearly the
-        latter will be a dummy object in the case of
-        <literal>AuthenticationFailureUsernameNotFoundEvent</literal>). The
-        <literal>Authentication</literal> interface provides a
-        <literal>getDetails()</literal> method which often includes
-        information that event consumers may find useful (eg the TCP/IP
-        address that the authentication request originated from).</para>
-
-        <para>As per standard Spring event handling, you can receive these
-        events by adding a bean to the application context which implements
-        the <literal>ApplicationListener</literal> interface. Included with
-        Acegi Security is a <literal>LoggerListener</literal> class which
-        receives these events and publishes their details to Commons Logging.
-        Refer to the JavaDocs for <literal>LoggerListener</literal> for
-        details on the logging priorities used for different message
-        types.</para>
-
-        <para>This event publishing system enables you to implement account
-        locking and record authentication event history. This might be of
-        interest to application users, who can be advised of the times and
-        source IP address of all unsuccessful password attempts (and account
-        lockouts) since their last successful login. Such capabilities are
-        simple to implement and greatly improve the security of your
-        application.</para>
-      </sect2>
-
-      <sect2 id="security-authentication-provider-in-memory">
-        <title>In-Memory Authentication</title>
-
-        <para>Whilst it is easy to use the
-        <literal>DaoAuthenticationProvider</literal> and create a custom
-        <literal>AuthenticationDao</literal> implementation that extracts
-        information from a persistence engine of choice, many applications do
-        not require such complexity. One alternative is to configure an
-        authentication repository in the application context itself using the
-        <literal>InMemoryDaoImpl</literal>:</para>
-
-        <para><programlisting>&lt;bean id="inMemoryDaoImpl" class="net.sf.acegisecurity.providers.dao.memory.InMemoryDaoImpl"&gt;
-  &lt;property name="userMap"&gt;
-    &lt;value&gt;
-      marissa=koala,ROLE_TELLER,ROLE_SUPERVISOR
-      dianne=emu,ROLE_TELLER
-      scott=wombat,ROLE_TELLER
-      peter=opal,disabled,ROLE_TELLER
-    &lt;/value&gt;
-  &lt;/property&gt;
-&lt;/bean&gt;</programlisting></para>
-
-        <para>The <literal>userMap</literal> property contains each of the
-        usernames, passwords, a list of granted authorities and an optional
-        enabled/disabled keyword. Commas delimit each token. The username must
-        appear to the left of the equals sign, and the password must be the
-        first token to the right of the equals sign. The
-        <literal>enabled</literal> and <literal>disabled</literal> keywords
-        (case insensitive) may appear in the second or any subsequent token.
-        Any remaining tokens are treated as granted authorities, which are
-        created as <literal>GrantedAuthorityImpl</literal> objects (refer to
-        the Authorization section for further discussion on granted
-        authorities). Note that if a user has no password and/or no granted
-        authorities, the user will not be created in the in-memory
-        authentication repository.</para>
-      </sect2>
-
-      <sect2 id="security-authentication-provider-jdbc">
-        <title>JDBC Authentication</title>
-
-        <para>The Acegi Security System for Spring also includes an
-        authentication provider that can obtain authentication information
-        from a JDBC data source. The typical configuration for the
-        <literal>JdbcDaoImpl</literal> is shown below:</para>
-
-        <para><programlisting>&lt;bean id="dataSource" class="org.springframework.jdbc.datasource.DriverManagerDataSource"&gt;
-  &lt;property name="driverClassName"&gt;&lt;value&gt;org.hsqldb.jdbcDriver&lt;/value&gt;&lt;/property&gt;
-  &lt;property name="url"&gt;&lt;value&gt;jdbc:hsqldb:hsql://localhost:9001&lt;/value&gt;&lt;/property&gt;
-  &lt;property name="username"&gt;&lt;value&gt;sa&lt;/value&gt;&lt;/property&gt;
-  &lt;property name="password"&gt;&lt;value&gt;&lt;/value&gt;&lt;/property&gt;
-&lt;/bean&gt;
-
-&lt;bean id="jdbcDaoImpl" class="net.sf.acegisecurity.providers.dao.jdbc.JdbcDaoImpl"&gt;
-  &lt;property name="dataSource"&gt;&lt;ref bean="dataSource"/&gt;&lt;/property&gt;
-&lt;/bean&gt;</programlisting></para>
-
-        <para>You can use different relational database management systems by
-        modifying the <literal>DriverManagerDataSource</literal> shown above.
-        Irrespective of the database used, a standard schema must be used as
-        indicated in <literal>dbinit.txt</literal>.</para>
-
-        <para>If you default schema is unsuitable for your needs,
-        <literal>JdbcDaoImpl</literal> provides two properties that allow
-        customisation of the SQL statements. You may also subclass the
-        <literal>JdbcDaoImpl</literal> if further customisation is necessary.
-        Please refer to the JavaDocs for details.</para>
-
-        <para>The Acegi Security System for Spring ships with a Hypersonic SQL
-        instance that has the required authentication information and sample
-        data already populated. To use this server, simply execute the
-        <literal>server.bat</literal> or <literal>server.sh</literal> script
-        included in the distribution. This will load a new database server
-        instance that will service requests made to the URL indicated in the
-        bean context configuration shown above.</para>
-      </sect2>
-
-      <sect2 id="security-authentication-provider-jaas">
-        <title>JAAS Authentication</title>
-
-        <para>Acegi Security provides a package able to delegate
-        authentication requests to the Java Authentication and Authorization
-        Service (JAAS). This package is discussed in detail below.</para>
-
-        <para>Central to JAAS operation are login configuration files. To
-        learn more about JAAS login configuration files, consult the JAAS
-        reference documentation available from Sun Microsystems. We expect you
-        to have a basic understanding of JAAS and its login configuration file
-        syntax in order to understand this section.</para>
-
-        <sect3>
-          <title>JaasAuthenticationProvider</title>
-
-          <para>The <literal>JaasAuthenticationProvider</literal> attempts to
-          authenticate a user’s principal and credentials through JAAS.</para>
-
-          <para>Let’s assume we have a JAAS login configuration file,
-          <literal>/WEB-INF/login.conf</literal>, with the following
-          contents:</para>
-
-          <para><programlisting>JAASTest {
-  sample.SampleLoginModule required;
-};</programlisting></para>
-
-          <para>Like all Acegi Security beans, the
-          <literal>JaasAuthenticationProvider</literal> is configured via the
-          application context. The following definitions would correspond to
-          the above JAAS login configuration file:</para>
-
-          <para><programlisting>&lt;bean id="jaasAuthenticationProvider" class="net.sf.acegisecurity.providers.jaas.JaasAuthenticationProvider"&gt;
-  &lt;property name="loginConfig"&gt;
-    &lt;value&gt;/WEB-INF/login.conf&lt;/value&gt;
-  &lt;/property&gt;
-  &lt;property name="loginContextName"&gt;
-    &lt;value&gt;JAASTest&lt;/value&gt;
-  &lt;/property&gt;
-  &lt;property name="callbackHandlers"&gt;
-    &lt;list&gt;
-      &lt;bean class="net.sf.acegisecurity.providers.jaas.JaasNameCallbackHandler"/&gt;
-      &lt;bean class="net.sf.acegisecurity.providers.jaas.JaasPasswordCallbackHandler"/&gt;
-    &lt;/list&gt;
-  &lt;/property&gt;
-  &lt;property name="authorityGranters"&gt;
-    &lt;list&gt;
-      &lt;bean class="net.sf.acegisecurity.providers.jaas.TestAuthorityGranter"/&gt;
-    &lt;/list&gt;
-  &lt;/property&gt;
-&lt;/bean&gt;</programlisting></para>
-
-          <para>The <literal>CallbackHandler</literal>s and
-          <literal>AuthorityGranter</literal>s are discussed below.</para>
-        </sect3>
-
-        <sect3>
-          <title>Callbacks</title>
-
-          <para>Most JAAS <literal>LoginModule</literal>s require a callback
-          of some sort. These callbacks are usually used to obtain the
-          username and password from the user. In an Acegi Security
-          deployment, Acegi Security is responsible for this user interaction
-          (typically via a reference to a
-          <literal>ContextHolder</literal>-managed
-          <literal>Authentication</literal> object). The JAAS package for
-          Acegi Security provides two default callback handlers,
-          <literal>JaasNameCallbackHandler</literal> and
-          <literal>JaasPasswordCallbackHandler</literal>. Each of these
-          callback handlers implement
-          <literal>JaasAuthenticationCallbackHandler</literal>. In most cases
-          these callback handlers can simply be used without understanding the
-          internal mechanics. For those needing full control over the callback
-          behavior, internally <literal>JaasAutheticationProvider</literal>
-          wraps these <literal>JaasAuthenticationCallbackHandler</literal>s
-          with an <literal>InternalCallbackHandler</literal>. The
-          <literal>InternalCallbackHandler</literal> is the class that
-          actually implements JAAS’ normal <literal>CallbackHandler</literal>
-          interface. Any time that the JAAS <literal>LoginModule</literal> is
-          used, it is passed a list of application context configured
-          <literal>InternalCallbackHandler</literal>s. If the
-          <literal>LoginModule</literal> requests a callback against the
-          <literal>InternalCallbackHandler</literal>s, the callback is in-turn
-          passed to the <literal>JaasAuthenticationCallbackHandler</literal>s
-          being wrapped.</para>
-        </sect3>
-
-        <sect3>
-          <title>AuthorityGranters</title>
-
-          <para>JAAS works with principals. Even “roles” are represented as
-          principals in JAAS. Acegi Security, on the other hand, works with
-          <literal>Authentication</literal> objects. Each
-          <literal>Authentication</literal> object contains a single
-          principal, and multiple <literal>GrantedAuthority</literal>[]s. To
-          facilitate mapping between these different concepts, the Acegi
-          Security JAAS package includes an
-          <literal>AuthorityGranter</literal> interface. An
-          <literal>AuthorityGranter</literal> is responsible for inspecting a
-          JAAS principal and returning a <literal>String</literal>. The
-          <literal>JaasAuthenticationProvider</literal> then creates a
-          <literal>JaasGrantedAuthority</literal> (which implements Acegi
-          Security’s <literal>GrantedAuthority</literal> interface) containing
-          both the <literal>AuthorityGranter</literal>-returned
-          <literal>String</literal> and the JAAS principal that the
-          <literal>AuthorityGranter</literal> was passed. The
-          <literal>JaasAuthenticationProvider</literal> obtains the JAAS
-          principals by firstly successfully authenticating the user’s
-          credentials using the JAAS <literal>LoginModule</literal>, and then
-          accessing the <literal>LoginContext</literal> it returns. A call to
-          <literal>LoginContext.getSubject().getPrincipals()</literal> is
-          made, with each resulting principal passed to each
-          <literal>AuthorityGranter</literal> defined against the
-          <literal>JaasAuthenticationProvider.setAuthorityGranters(List)</literal>
-          property. Acegi Security does not include any production
-          <literal>AuthorityGranter</literal>s given every JAAS principal has
-          an implementation-specific meaning. However, there is a
-          <literal>TestAuthorityGranter</literal> in the unit tests that
-          demonstrates a simple <literal>AuthorityGranter</literal>
-          implementation.</para>
-        </sect3>
-      </sect2>
-
-      <sect2 id="security-authentication-recommendations">
-        <title>Authentication Recommendations</title>
-
-        <para>With the heavy use of interfaces throughout the authentication
-        system (<literal>Authentication</literal>,
-        <literal>AuthenticationManager</literal>,
-        <literal>AuthenticationProvider</literal> and
-        <literal>AuthenticationDao</literal>) it might be confusing to a new
-        user to know which part of the authentication system to customize. In
-        general, the following is recommended:</para>
-
-        <itemizedlist>
-          <listitem>
-            <para>Use the
-            <literal>UsernamePasswordAuthenticationToken</literal>
-            implementation where possible.</para>
-          </listitem>
-
-          <listitem>
-            <para>If you simply need to implement a new authentication
-            repository (eg to obtain user details from your application’s
-            existing database), use the
-            <literal>DaoAuthenticationProvider</literal> along with the
-            <literal>AuthenticationDao</literal>. It is the fastest and safest
-            way to integrate an external database.</para>
-          </listitem>
-
-          <listitem>
-            <para>If you're using Container Adapters or a
-            <literal>RunAsManager</literal> that replaces the
-            <literal>Authentication</literal> object, ensure you have
-            registered the <literal>AuthByAdapterProvider</literal> and
-            <literal>RunAsManagerImplProvider</literal> respectively with your
-            <literal>ProviderManager</literal>.</para>
-          </listitem>
-
-          <listitem>
-            <para>Never enable the
-            <literal>TestingAuthenticationProvider</literal> on a production
-            system. Doing so will allow any client to simply present a
-            <literal>TestingAuthenticationToken</literal> and obtain whatever
-            access they request.</para>
-          </listitem>
-
-          <listitem>
-            <para>Adding a new <literal>AuthenticationProvider</literal> is
-            sufficient to support most custom authentication requirements.
-            Only unusual requirements would require the
-            <literal>ProviderManager</literal> to be replaced with a different
-            <literal>AuthenticationManager</literal>.</para>
-          </listitem>
-        </itemizedlist>
-      </sect2>
-    </sect1>
-
-    <sect1 id="security-authorization">
-      <title>Authorization</title>
-
-      <sect2 id="security-authorization-granted-authorities">
-        <title>Granted Authorities</title>
-
-        <para>As briefly mentioned in the Authentication section, all
-        <literal>Authentication</literal> implementations are required to
-        store an array of <literal>GrantedAuthority</literal> objects. These
-        represent the authorities that have been granted to the principal. The
-        <literal>GrantedAuthority</literal> objects are inserted into the
-        <literal>Authentication</literal> object by the
-        <literal>AuthenticationManager</literal> and are later read by
-        <literal>AccessDecisionManager</literal>s when making authorization
-        decisions.</para>
-
-        <para><literal>GrantedAuthority</literal> is an interface with only
-        one method:</para>
-
-        <para><programlisting>public String getAuthority();</programlisting></para>
-
-        <para>This method allows <literal>AccessDecisionManager</literal>s to
-        obtain a precise <literal>String</literal> representation of the
-        <literal>GrantedAuthority</literal>. By returning a representation as
-        a <literal>String</literal>, a <literal>GrantedAuthority</literal> can
-        be easily "read" by most <literal>AccessDecisionManager</literal>s. If
-        a <literal>GrantedAuthority</literal> cannot be precisely represented
-        as a <literal>String</literal>, the
-        <literal>GrantedAuthority</literal> is considered "complex" and
-        <literal>getAuthority()</literal> must return
-        <literal>null</literal>.</para>
-
-        <para>An example of a "complex" <literal>GrantedAuthority</literal>
-        would be an implementation that stores a list of operations and
-        authority thresholds that apply to different customer account numbers.
-        Representing this complex <literal>GrantedAuthority</literal> as a
-        <literal>String</literal> would be quite complex, and as a result the
-        <literal>getAuthority()</literal> method should return
-        <literal>null</literal>. This will indicate to any
-        <literal>AccessDecisionManager</literal> that it will need to
-        specifically support the <literal>GrantedAuthority</literal>
-        implementation in order to understand its contents.</para>
-
-        <para>The Acegi Security System for Spring includes one concrete
-        <literal>GrantedAuthority</literal> implementation,
-        <literal>GrantedAuthorityImpl</literal>. This allows any
-        user-specified <literal>String</literal> to be converted into a
-        <literal>GrantedAuthority</literal>. All
-        <literal>AuthenticationProvider</literal>s included with the security
-        architecture use <literal>GrantedAuthorityImpl</literal> to populate
-        the <literal>Authentication</literal> object.</para>
-      </sect2>
-
-      <sect2 id="security-authorization-access-decision-managers">
-        <title>Access Decision Managers</title>
-
-        <para>The <literal>AccessDecisionManager</literal> is called by the
-        <literal>AbstractSecurityInterceptor</literal> and is responsible for
-        making final access control decisions. The
-        <literal>AccessDecisionManager</literal> interface contains three
-        methods:</para>
-
-        <para><programlisting>public void decide(Authentication authentication, Object object, ConfigAttributeDefinition config) throws AccessDeniedException;
-public boolean supports(ConfigAttribute attribute);
-public boolean supports(Class clazz);</programlisting></para>
-
-        <para>As can be seen from the first method, the
-        <literal>AccessDecisionManager</literal> is passed via method
-        parameters all information that is likely to be of value in assessing
-        an authorization decision. In particular, passing the secure
-        <literal>Object</literal> enables those arguments contained in the
-        actual secure object invocation to be inspected. For example, let's
-        assume the secure object was a <literal>MethodInvocation</literal>. It
-        would be easy to query the <literal>MethodInvocation</literal> for any
-        <literal>Customer</literal> argument, and then implement some sort of
-        security logic in the <literal>AccessDecisionManager</literal> to
-        ensure the principal is permitted to operate on that customer.
-        Implementations are expected to throw an
-        <literal>AccessDeniedException</literal> if access is denied.</para>
-
-        <para>The <literal>supports(ConfigAttribute)</literal> method is
-        called by the <literal>AbstractSecurityInterceptor</literal> at
-        startup time to determine if the
-        <literal>AccessDecisionManager</literal> can process the passed
-        <literal>ConfigAttribute</literal>. The
-        <literal>supports(Class)</literal> method is called by a security
-        interceptor implementation to ensure the configured
-        <literal>AccessDecisionManager</literal> supports the type of secure
-        object that the security interceptor will present.</para>
-      </sect2>
-
-      <sect2 id="security-authorization-voting-decision-manager">
-        <title>Voting Decision Manager</title>
-
-        <para>Whilst users can implement their own
-        <literal>AccessDecisionManager</literal> to control all aspects of
-        authorization, the Acegi Security System for Spring includes several
-        <literal>AccessDecisionManager</literal> implementations that are
-        based on voting. Using this approach, a series of
-        <literal>AccessDecisionVoter</literal> implementations are polled on
-        an authorization decision. The
-        <literal>AccessDecisionManager</literal> then decides whether or not
-        to throw an <literal>AccessDeniedException</literal> based on its
-        assessment of the votes.</para>
-
-        <para>The <literal>AccessDecisionVoter</literal> interface has three
-        methods:</para>
-
-        <para><programlisting>public int vote(Authentication authentication, Object object, ConfigAttributeDefinition config);
-public boolean supports(ConfigAttribute attribute);
-public boolean supports(Class clazz);</programlisting></para>
-
-        <para>Concrete implementations return an <literal>int</literal>, with
-        possible values being reflected in the
-        <literal>AccessDecisionVoter</literal> static fields
-        <literal>ACCESS_ABSTAIN</literal>, <literal>ACCESS_DENIED</literal>
-        and <literal>ACCESS_GRANTED</literal>. A voting implementation will
-        return <literal>ACCESS_ABSTAIN</literal> if it has no opinion on an
-        authorization decision. If it does have an opinion, it must return
-        either <literal>ACCESS_DENIED</literal> or
-        <literal>ACCESS_GRANTED</literal>.</para>
-
-        <para>There are three concrete
-        <literal>AccessDecisionManager</literal>s provided with the Acegi
-        Security System for Spring that tally the votes. The
-        <literal>ConsensusBased</literal> implementation will grant or deny
-        access based on the consensus of non-abstain votes. Properties are
-        provided to control behavior in the event of an equality of votes or
-        if all votes are abstain. The <literal>AffirmativeBased</literal>
-        implementation will grant access if one or more
-        <literal>ACCESS_GRANTED</literal> votes were received (ie a deny vote
-        will be ignored, provided there was at least one grant vote). Like the
-        <literal>ConsensusBased</literal> implementation, there is a parameter
-        that controls the behavior if all voters abstain. The
-        <literal>UnanimousBased</literal> provider expects unanimous
-        <literal>ACCESS_GRANTED</literal> votes in order to grant access,
-        ignoring abstains. It will deny access if there is any
-        <literal>ACCESS_DENIED</literal> vote. Like the other implementations,
-        there is a parameter that controls the behaviour if all voters
-        abstain.</para>
-
-        <para>It is possible to implement a custom
-        <literal>AccessDecisionManager</literal> that tallies votes
-        differently. For example, votes from a particular
-        <literal>AccessDecisionVoter</literal> might receive additional
-        weighting, whilst a deny vote from a particular voter may have a veto
-        effect.</para>
-
-        <para>There is one concrete <literal>AccessDecisionVoter</literal>
-        implementation provided with the Acegi Security System for Spring. The
-        <literal>RoleVoter</literal> class will vote if any ConfigAttribute
-        begins with <literal>ROLE_</literal>. It will vote to grant access if
-        there is a <literal>GrantedAuthority</literal> which returns a
-        <literal>String</literal> representation (via the
-        <literal>getAuthority()</literal> method) exactly equal to one or more
-        <literal>ConfigAttributes</literal> starting with
-        <literal>ROLE_</literal>. If there is no exact match of any
-        <literal>ConfigAttribute</literal> starting with
-        <literal>ROLE_</literal>, the <literal>RoleVoter</literal> will vote
-        to deny access. If no <literal>ConfigAttribute</literal> begins with
-        <literal>ROLE_</literal>, the voter will abstain.
-        <literal>RoleVoter</literal> is case sensitive on comparisons as well
-        as the <literal>ROLE_</literal> prefix.</para>
-
-        <para>It is possible to implement a custom
-        <literal>AccessDecisionVoter</literal>. Several examples are provided
-        in the Acegi Security System for Spring unit tests, including
-        <literal>ContactSecurityVoter</literal> and
-        <literal>DenyVoter</literal>. The
-        <literal>ContactSecurityVoter</literal> abstains from voting decisions
-        where a <literal>CONTACT_OWNED_BY_CURRENT_USER</literal>
-        <literal>ConfigAttribute</literal> is not found. If voting, it queries
-        the <literal>MethodInvocation</literal> to extract the owner of the
-        <literal>Contact</literal> object that is subject of the method call.
-        It votes to grant access if the <literal>Contact</literal> owner
-        matches the principal presented in the
-        <literal>Authentication</literal> object. It could have just as easily
-        compared the <literal>Contact</literal> owner with some
-        <literal>GrantedAuthority</literal> the
-        <literal>Authentication</literal> object presented. All of this is
-        achieved with relatively few lines of code and demonstrates the
-        flexibility of the authorization model.</para>
-      </sect2>
-
-      <sect2 id="security-authorization-taglib">
-        <title>Authorization Tag Library</title>
-
-        <para>The Acegi Security System for Spring comes bundled with a JSP
-        tag library that eases JSP writing. The tag library is known as
-        <literal>authz</literal>.</para>
-
-        <para>This library allows you to easy develop JSP pages which
-        reference the security environment. For example,
-        <literal>authz</literal> allows you to determine if a principal holds
-        a particular granted authority, holds a group of granted authorities,
-        or does not hold a given granted authority.</para>
-
-        <sect3>
-          <title>Usage</title>
-
-          <para>The following JSP fragment illustrates how to use the
-          <literal>authz</literal> taglib:</para>
-
-          <para><programlisting>&lt;authz:authorize ifAllGranted="ROLE_SUPERVISOR"&gt;
-  &lt;td&gt;
-    &lt;A HREF="del.htm?id=&lt;c:out value="${contact.id}"/&gt;"&gt;Del&lt;/A&gt;
-  &lt;/td&gt;
-&lt;/authz:authorize&gt;</programlisting></para>
-
-          <para>This code was copied from the Contacts sample
-          application.</para>
-
-          <para>What this code says is: if the principal has been granted
-          ROLE_SUPERVISOR, allow the tag's body to be output.</para>
-        </sect3>
-
-        <sect3>
-          <title>Installation</title>
-
-          <para>Installation is a simple matter. Simply copy the
-          <literal>acegi-security-taglib.jar</literal> file into your
-          application's <literal>WEB-INF/lib</literal> folder. The tag library
-          includes it's TLD, which makes it easier to work with JSP 1.2+
-          containers.</para>
-
-          <para>If you are using a JSP 1.1 container, you will need to declare
-          the JSP tag library in your application's <literal>web.xml</literal>
-          file, with code such as this:</para>
-
-          <para><programlisting>&lt;taglib&gt;
-       &lt;taglib-uri&gt;http://acegisecurity.sf.net/authz&lt;/taglib-uri&gt;
-       &lt;taglib-location&gt;/WEB-INF/authz.tld&lt;/taglib-location&gt;
-&lt;/taglib&gt;</programlisting></para>
-
-          <para>For JSP 1.1 containers you will also need to extract the
-          <literal>authz.tld</literal> file from the
-          <literal>acegi-security-taglib.jar</literal> file and put it into
-          your application's <literal>WEB-INF/lib</literal> folder. Use a
-          regular Zip tool, or Java's JAR utility.</para>
-        </sect3>
-
-        <sect3>
-          <title>Reference</title>
-
-          <para>The <literal>authz:authorize</literal> tag declares the
-          following attributes:</para>
-
-          <para><itemizedlist spacing="compact">
-              <listitem>
-                <para><literal>ifAllGranted</literal>: All the listed roles
-                must be granted for the tag to output its body.</para>
-              </listitem>
-
-              <listitem>
-                <para><literal>ifAnyGranted</literal>: Any of the listed roles
-                must be granted for the tag to output its body.</para>
-              </listitem>
-
-              <listitem>
-                <para><literal>ifNotGranted</literal>: None of the listed
-                roles must be granted for the tag to output its body.</para>
-              </listitem>
-            </itemizedlist></para>
-
-          <para>You'll note that in each attribute you can list multiple
-          roles. Simply separate the roles using a comma. The
-          <literal>authorize</literal> tag ignores whitespace in
-          attributes.</para>
-
-          <para>The tag library logically ANDs all of it's parameters
-          together. This means that if you combine two or more attributes, all
-          attributes must be true for the tag to output it's body. Don't add
-          an <literal>ifAllGranted="ROLE_SUPERVISOR"</literal>, followed by an
-          <literal>ifNotGranted="ROLE_SUPERVISOR"</literal>, or you'll be
-          surprised to never see the tag's body.</para>
-
-          <para>By requiring all attributes to return true, the authorize tag
-          allows you to create more complex authorization scenarios. For
-          example, you could declare an
-          <literal>ifAllGranted="ROLE_SUPERVISOR"</literal> and an
-          <literal>ifNotGranted="ROLE_NEWBIE_SUPERVISOR"</literal> in the same
-          tag, in order to prevent new supervisors from seeing the tag body.
-          However it would no doubt be simpler to use
-          <literal>ifAllGranted="ROLE_EXPERIENCED_SUPERVISOR"</literal> rather
-          than inserting NOT conditions into your design.</para>
-
-          <para>One last item: the tag verifies the authorizations in a
-          specific order: first <literal>ifNotGranted</literal>, then
-          <literal>ifAllGranted</literal>, and finally,
-          <literal>ifAnyGranted</literal>.</para>
-        </sect3>
-      </sect2>
-
-      <sect2 id="security-authorization-recommendations">
-        <title>Authorization Recommendations</title>
-
-        <para>Given there are several ways to achieve similar authorization
-        outcomes in the Acegi Security System for Spring, the following
-        general recommendations are made:</para>
-
-        <itemizedlist>
-          <listitem>
-            <para>Grant authorities using
-            <literal>GrantedAuthorityImpl</literal> where possible. Because it
-            is already supported by the Acegi Security System for Spring, you
-            avoid the need to create custom
-            <literal>AuthenticationManager</literal> or
-            <literal>AuthenticationProvider</literal> implementations simply
-            to populate the <literal>Authentication</literal> object with a
-            custom <literal>GrantedAuthority</literal>.</para>
-          </listitem>
-
-          <listitem>
-            <para>Writing an <literal>AccessDecisionVoter</literal>
-            implementation and using either <literal>ConsensusBased</literal>,
-            <literal>AffirmativeBased</literal> or
-            <literal>UnanimousBased</literal> as the
-            <literal>AccessDecisionManager</literal> may be the best approach
-            to implementing your custom access decision rules.</para>
-          </listitem>
-        </itemizedlist>
-      </sect2>
-    </sect1>
-
-    <sect1 id="security-run-as">
-      <title>Run-As Authentication Replacement</title>
-
-      <sect2 id="security-run-as-purpose">
-        <title>Purpose</title>
-
-        <para>The <literal>AbstractSecurityInterceptor</literal> is able to
-        temporarily replace the <literal>Authentication</literal> object in
-        the <literal>SecureContext</literal> and
-        <literal>ContextHolder</literal> during the
-        <literal>SecurityInterceptorCallback</literal>. This only occurs if
-        the original <literal>Authentication</literal> object was successfully
-        processed by the <literal>AuthenticationManager</literal> and
-        <literal>AccessDecisionManager</literal>. The
-        <literal>RunAsManager</literal> will indicate the replacement
-        <literal>Authentication</literal> object, if any, that should be used
-        during the <literal>SecurityInterceptorCallback</literal>.</para>
-
-        <para>By temporarily replacing the <literal>Authentication</literal>
-        object during a <literal>SecurityInterceptorCallback</literal>, the
-        secured invocation will be able to call other objects which require
-        different authentication and authorization credentials. It will also
-        be able to perform any internal security checks for specific
-        <literal>GrantedAuthority</literal> objects.</para>
-      </sect2>
-
-      <sect2 id="security-run-as-usage">
-        <title>Usage</title>
-
-        <para>A <literal>RunAsManager</literal> interface is provided by the
-        Acegi Security System for Spring:</para>
-
-        <para><programlisting>public Authentication buildRunAs(Authentication authentication, Object object, ConfigAttributeDefinition config);
-public boolean supports(ConfigAttribute attribute);
-public boolean supports(Class clazz);</programlisting></para>
-
-        <para>The first method returns the <literal>Authentication</literal>
-        object that should replace the existing
-        <literal>Authentication</literal> object for the duration of the
-        method invocation. If the method returns <literal>null</literal>, it
-        indicates no replacement should be made. The second method is used by
-        the <literal>AbstractSecurityInterceptor</literal> as part of its
-        startup validation of configuration attributes. The
-        <literal>supports(Class)</literal> method is called by a security
-        interceptor implementation to ensure the configured
-        <literal>RunAsManager</literal> supports the type of secure object
-        that the security interceptor will present.</para>
-
-        <para>One concrete implementation of a <literal>RunAsManager</literal>
-        is provided with the Acegi Security System for Spring. The
-        <literal>RunAsManagerImpl</literal> class returns a replacement
-        <literal>RunAsUserToken</literal> if any
-        <literal>ConfigAttribute</literal> starts with
-        <literal>RUN_AS_</literal>. If any such
-        <literal>ConfigAttribute</literal> is found, the replacement
-        <literal>RunAsUserToken</literal> will contain the same principal,
-        credentials and granted authorities as the original
-        <literal>Authentication</literal> object, along with a new
-        <literal>GrantedAuthorityImpl</literal> for each
-        <literal>RUN_AS_</literal> <literal>ConfigAttribute</literal>. Each
-        new <literal>GrantedAuthorityImpl</literal> will be prefixed with
-        <literal>ROLE_</literal>, followed by the <literal>RUN_AS</literal>
-        <literal>ConfigAttribute</literal>. For example, a
-        <literal>RUN_AS_SERVER</literal> will result in the replacement
-        <literal>RunAsUserToken</literal> containing a
-        <literal>ROLE_RUN_AS_SERVER</literal> granted authority.</para>
-
-        <para>The replacement <literal>RunAsUserToken</literal> is just like
-        any other <literal>Authentication</literal> object. It needs to be
-        authenticated by the <literal>AuthenticationManager</literal>,
-        probably via delegation to a suitable
-        <literal>AuthenticationProvider</literal>. The
-        <literal>RunAsImplAuthenticationProvider</literal> performs such
-        authentication. It simply accepts as valid any
-        <literal>RunAsUserToken</literal> presented.</para>
-
-        <para>To ensure malicious code does not create a
-        <literal>RunAsUserToken</literal> and present it for guaranteed
-        acceptance by the <literal>RunAsImplAuthenticationProvider</literal>,
-        the hash of a key is stored in all generated tokens. The
-        <literal>RunAsManagerImpl</literal> and
-        <literal>RunAsImplAuthenticationProvider</literal> is created in the
-        bean context with the same key:</para>
-
-        <para><programlisting>&lt;bean id="runAsManager" class="net.sf.acegisecurity.runas.RunAsManagerImpl"&gt;
-  &lt;property name="key"&gt;&lt;value&gt;my_run_as_password&lt;/value&gt;&lt;/property&gt;
-&lt;/bean&gt;</programlisting><programlisting>&lt;bean id="runAsAuthenticationProvider" class="net.sf.acegisecurity.runas.RunAsImplAuthenticationProvider"&gt;
-  &lt;property name="key"&gt;&lt;value&gt;my_run_as_password&lt;/value&gt;&lt;/property&gt;
-&lt;/bean&gt;</programlisting></para>
-
-        <para>By using the same key, each <literal>RunAsUserToken</literal>
-        can be validated it was created by an approved
-        <literal>RunAsManagerImpl</literal>. The
-        <literal>RunAsUserToken</literal> is immutable after creation for
-        security reasons.</para>
-      </sect2>
-    </sect1>
-
-    <sect1 id="security-ui">
-      <title>User Interfacing with the ContextHolder</title>
-
-      <sect2 id="security-ui-purpose">
-        <title>Purpose</title>
-
-        <para>Everything presented so far assumes one thing: the
-        <literal>ContextHolder</literal> is populated with a valid
-        <literal>SecureContext</literal>, which in turn contains a valid
-        <literal>Authentication</literal> object. Developers are free to do
-        this in whichever way they like, such as directly calling the relevant
-        objects at runtime. However, several classes have been provided to
-        make this process transparent in many situations.</para>
-
-        <para>The <literal>net.sf.acegisecurity.ui</literal> package is
-        designed to make interfacing web application user interfaces with the
-        <literal>ContextHolder</literal> as simple as possible. There are two
-        major steps in doing this:</para>
-
-        <para><itemizedlist spacing="compact">
-            <listitem>
-              <para>Actually authenticate the user and place the resulting
-              <literal>Authentication</literal> object in a "well-known
-              location".</para>
-            </listitem>
-
-            <listitem>
-              <para>Extract the <literal>Authentication</literal> object from
-              the "well-known location" and place in into the
-              <literal>ContextHolder</literal> for the duration of the secure
-              object invocation.</para>
-            </listitem>
-          </itemizedlist></para>
-
-        <para>There are several alternatives are available for the first step,
-        which will be briefly discussed in this chapter. The most popular
-        approach is HTTP Session Authentication, which uses the
-        <literal>HttpSession</literal> object and filters to authenticate the
-        user. Another approach is HTTP Basic Authentication, which allows
-        clients to use HTTP headers to present authentication information to
-        the Acegi Security System for Spring. Alternatively, you can also use
-        Yale Central Authentication Service (CAS) for enterprise-wide single
-        sign on. The final approach is via Container Adapters, which allow
-        supported web containers to perform the authentication themselves.
-        HTTP Session and Basic Authentication is discussed below, whilst CAS
-        and Container Adapters are discussed in separate sections of this
-        document.</para>
-      </sect2>
-
-      <sect2 id="security-ui-http-session">
-        <title>HTTP Session Authentication</title>
-
-        <para>HTTP Session Authentication involves using the
-        <literal>AuthenticationProcessingFilter</literal> to process a login
-        form. The login form simply contains <literal>j_username</literal> and
-        <literal>j_password</literal> input fields, and posts to a URL that is
-        monitored by the filter (by default
-        <literal>j_acegi_security_check</literal>). The filter is defined in
-        <literal>web.xml</literal> behind a
-        <literal>FilterToBeanProxy</literal> as follows:</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.util.FilterToBeanProxy&lt;/filter-class&gt;
-  &lt;init-param&gt;
-    &lt;param-name&gt;targetClass&lt;/param-name&gt;
-    &lt;param-value&gt;net.sf.acegisecurity.ui.webapp.AuthenticationProcessingFilter&lt;/param-value&gt;
-  &lt;/init-param&gt;
-&lt;/filter&gt;
-
-&lt;filter-mapping&gt;
-  &lt;filter-name&gt;Acegi Authentication Processing Filter&lt;/filter-name&gt;
-  &lt;url-pattern&gt;/*&lt;/url-pattern&gt;
-&lt;/filter-mapping&gt;</programlisting></para>
-
-        <para>For a discussion of <literal>FilterToBeanProxy</literal>, please
-        refer to the Filters section. The application context will need to
-        define the <literal>AuthenticationProcessingFilter</literal>:</para>
-
-        <para><programlisting>&lt;bean id="authenticationProcessingFilter" class="net.sf.acegisecurity.ui.webapp.AuthenticationProcessingFilter"&gt;
-  &lt;property name="authenticationManager"&gt;&lt;ref bean="authenticationManager"/&gt;&lt;/property&gt;
-  &lt;property name="authenticationFailureUrl"&gt;&lt;value&gt;/acegilogin.jsp?login_error=1&lt;/value&gt;&lt;/property&gt;
-  &lt;property name="defaultTargetUrl"&gt;&lt;value&gt;/&lt;/value&gt;&lt;/property&gt;
-  &lt;property name="filterProcessesUrl"&gt;&lt;value&gt;/j_acegi_security_check&lt;/value&gt;&lt;/property&gt;
-&lt;/bean&gt;</programlisting></para>
-
-        <para>The configured <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
-        <literal>HttpSession</literal> attribute indicated by
-        <literal>AbstractProcessingFilter.ACEGI_SECURITY_LAST_EXCEPTION_KEY</literal>,
-        enabling a reason to be provided to the user on the error page.</para>
-
-        <para>If authentication is successful, the resulting
-        <literal>Authentication</literal> object will be placed into the
-        <literal>HttpSession</literal> attribute indicated by
-        <literal>HttpSessionIntegrationFilter.ACEGI_SECURITY_AUTHENTICATION_KEY</literal>.
-        This becomes the "well-known location" from which the
-        <literal>Authentication</literal> object is later extracted.</para>
-
-        <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>AbstractProcessingFilter.ACEGI_SECURITY_TARGET_URL_KEY</literal>.
-        This attribute is automatically set by the
-        <literal>SecurityEnforcementFilter</literal> when an
-        <literal>AuthenticationException</literal> occurs, so that after login
-        is completed the user can return to what they were trying to access.
-        If for some reason the <literal>HttpSession</literal> does not
-        indicate the target URL, the browser will be redirected to the
-        <literal>defaultTargetUrl</literal> property.</para>
-
-        <para>Because this authentication approach is fully contained within a
-        single web application, HTTP Session Authentication is recommended to
-        be used instead of Container Adapters.</para>
-      </sect2>
-
-      <sect2 id="security-ui-http-basic">
-        <title>HTTP Basic Authentication</title>
-
-        <para>The Acegi Security System for Spring provides a
-        <literal>BasicProcessingFilter</literal> which is capable of
-        processing authentication credentials presented in HTTP headers. This
-        can be used for authenticating calls made by Spring remoting protocols
-        (such as Hessian and Burlap), as well as normal user agents (such as
-        Internet Explorer and Navigator). The standard governing HTTP Basic
-        Authentication is defined by RFC 1945, Section 11, and the
-        <literal>BasicProcessingFilter</literal> conforms with this
-        RFC.</para>
-
-        <para>To implement HTTP Basic Authentication, it is necessary to add
-        the following filter to <literal>web.xml</literal>:</para>
-
-        <para><programlisting>&lt;filter&gt;
-  &lt;filter-name&gt;Acegi HTTP BASIC Authorization Filter&lt;/filter-name&gt;
-  &lt;filter-class&gt;net.sf.acegisecurity.util.FilterToBeanProxy&lt;/filter-class&gt;
-  &lt;init-param&gt;
-    &lt;param-name&gt;targetClass&lt;/param-name&gt;
-    &lt;param-value&gt;net.sf.acegisecurity.ui.basicauth.BasicProcessingFilter&lt;/param-value&gt;
-  &lt;/init-param&gt;
-&lt;/filter&gt;
-
-&lt;filter-mapping&gt;
-  &lt;filter-name&gt;Acegi HTTP BASIC Authorization Filter&lt;/filter-name&gt;
-  &lt;url-pattern&gt;/*&lt;/url-pattern&gt;
-&lt;/filter-mapping&gt;</programlisting></para>
-
-        <para>For a discussion of <literal>FilterToBeanProxy</literal>, please
-        refer to the Filters section. The application context will need to
-        define the <literal>BasicProcessingFilter</literal> and its required
-        collaborator:</para>
-
-        <para><programlisting>&lt;bean id="basicProcessingFilter" class="net.sf.acegisecurity.ui.basicauth.BasicProcessingFilter"&gt;
-  &lt;property name="authenticationManager"&gt;&lt;ref bean="authenticationManager"/&gt;&lt;/property&gt;
-  &lt;property name="authenticationEntryPoint"&gt;&lt;ref bean="authenticationEntryPoint"/&gt;&lt;/property&gt;
-&lt;/bean&gt;
-
-&lt;bean id="authenticationEntryPoint" class="net.sf.acegisecurity.ui.basicauth.BasicProcessingFilterEntryPoint"&gt;
-  &lt;property name="realmName"&gt;&lt;value&gt;Name Of Your Realm&lt;/value&gt;&lt;/property&gt;
-&lt;/bean&gt;</programlisting></para>
-
-        <para>The configured <literal>AuthenticationManager</literal>
-        processes each authentication request. If authentication fails, the
-        configured <literal>AuthenticationEntryPoint</literal> will be used to
-        retry the authentication process. Usually you will use the
-        <literal>BasicProcessingFilterEntryPoint</literal>, which returns a
-        401 response with a suitable header to retry HTTP Basic
-        authentication. If authentication is successful, the resulting
-        <literal>Authentication</literal> object will be placed into the
-        <literal>HttpSession</literal> attribute indicated by
-        <literal>HttpSessionIntegrationFilter.ACEGI_SECURITY_AUTHENTICATION_KEY</literal>.
-        This becomes the "well-known location" from which the
-        <literal>Authentication</literal> object is later extracted.</para>
-
-        <para>If the authentication event was successful, or authentication
-        was not attempted because the HTTP header did not contain a supported
-        authentication request, the filter chain will continue as normal. The
-        only time the filter chain will be interrupted is if authentication
-        fails and the <literal>AuthenticationEntryPoint</literal> is called,
-        as discussed in the previous paragraph.</para>
-
-        <para>HTTP Basic Authentication is recommended to be used instead of
-        Container Adapters. It can be used in conjunction with HTTP Session
-        Authentication, as demonstrated in the Contacts sample application.
-        You can also use it instead of HTTP Session Authentication if you
-        wish.</para>
-      </sect2>
-
-      <sect2 id="security-ui-well-known">
-        <title>Well-Known Location Integration</title>
-
-        <para>Once a web application has used either HTTP Session
-        Authentication, HTTP Basic Authentication, or a Container Adapter, an
-        <literal>Authentication</literal> object will exist in a well-known
-        location. The final step in automatically integrating the user
-        interface with the backend security interceptor is to extract this
-        <literal>Authentication</literal> object from the well-known location
-        and place it into a <literal>SecureContext</literal> in the
-        <literal>ContextHolder</literal>.</para>
-
-        <para>The <literal>AbstractIntegrationFilter</literal> and its
-        subclasses provide this well-known location integration. These classes
-        are standard filters, and at the start of each request they will
-        attempt to extract the <literal>Authentication</literal> object from a
-        well-known location. The <literal>Authentication</literal> object will
-        then be added to a <literal>SecureContext</literal>, the
-        <literal>SecureContext</literal> associated with the
-        <literal>ContextHolder</literal> for the duration of the request, and
-        the <literal>ContextHolder</literal> be cleared when the request is
-        finished. Four concrete subclasses of
-        <literal>AbstractIntegrationFilter</literal> are provided with the
-        Acegi Security System for Spring:</para>
-
-        <para><itemizedlist>
-            <listitem>
-              <para><literal>HttpSessionIntegrationFilter</literal> is used
-              with HTTP Session Authentication, HTTP Basic Authentication, or
-              any other approach that populates the
-              <literal>HttpSession</literal> accordingly. It extracts the
-              <literal>Authentication</literal> object from the
-              <literal>HttpSession</literal> attribute indicated by
-              <literal>HttpSessionIntegrationFilter.ACEGI_SECURITY_AUTHENTICATION_KEY</literal>.</para>
-            </listitem>
-
-            <listitem>
-              <para><literal>HttpRequestIntegrationFilter</literal> is used
-              with Catalina, Jetty and Resin Container Adapters. It extracts
-              the authentication information from
-              <literal>HttpServletRequest.getUserPrincipal()</literal>.</para>
-            </listitem>
-
-            <listitem>
-              <para><literal>JbossIntegrationFilter</literal> is used with the
-              JBoss Container Adapter. It extracts the authentication from
-              <literal>java:comp/env/security/subject</literal>.</para>
-            </listitem>
-
-            <listitem>
-              <para><literal>AutoIntegrationFilter</literal> automatically
-              determines which filter to use. This makes a web application WAR
-              file more portable, as the <literal>web.xml</literal> is not
-              hard-coded to a specific
-              <literal>AbstractIntegrationFilter</literal>.</para>
-            </listitem>
-          </itemizedlist></para>
-
-        <para>To define the <literal>AutoIntegrationFilter</literal>
-        (recommended), simply add the following to your web.xml:</para>
-
-        <para><programlisting>&lt;filter&gt;
-  &lt;filter-name&gt;Acegi Security System for Spring Auto Integration Filter&lt;/filter-name&gt;
-  &lt;filter-class&gt;net.sf.acegisecurity.util.FilterToBeanProxy&lt;/filter-class&gt;
-  &lt;init-param&gt;
-    &lt;param-name&gt;targetClass&lt;/param-name&gt;
-    &lt;param-value&gt;net.sf.acegisecurity.ui.AutoIntegrationFilter&lt;/param-value&gt;
-  &lt;/init-param&gt;
-&lt;/filter&gt;
-
-&lt;filter-mapping&gt;
-  &lt;filter-name&gt;Acegi Security System for Spring Auto Integration Filter&lt;/filter-name&gt;
-  &lt;url-pattern&gt;/*&lt;/url-pattern&gt;
-&lt;/filter-mapping&gt;</programlisting></para>
-
-        <para>You will also need to add the following line to your application
-        context:</para>
-
-        <para><programlisting>&lt;bean id="autoIntegrationFilter" class="net.sf.acegisecurity.ui.AutoIntegrationFilter" /&gt;</programlisting></para>
-
-        <para>Once in the <literal>ContextHolder</literal>, the standard Acegi
-        Security System for Spring classes can be used. Because
-        <literal>ContextHolder</literal> is a standard object which is
-        populated using a filter at the container level, JSPs and Servlets do
-        not need to use Spring's MVC packages. This enables those applications
-        that use other MVC frameworks to still leverage Spring's other
-        capabilities, with full authentication and authorization support. The
-        <literal>debug.jsp</literal> page provided with the sample application
-        demonstrates accessing the <literal>ContextHolder</literal>
-        independent of Spring's MVC packages.</para>
-      </sect2>
-    </sect1>
-
-    <sect1 id="security-container-adapters">
-      <title>Container Adapters</title>
-
-      <sect2 id="security-container-adapters-overview">
-        <title>Overview</title>
-
-        <para>Early versions of the Acegi Security System for Spring
-        exclusively used Container Adapters for interfacing authentication
-        with end users. Whilst this worked well, it required considerable time
-        to support multiple container versions and the configuration itself
-        was relatively time-consuming for developers. For this reason the HTTP
-        Session Authentication and HTTP Basic Authentication approaches were
-        developed, and are today recommended for most applications.</para>
-
-        <para>Container Adapters enable the Acegi Security System for Spring
-        to integrate directly with the containers used to host end user
-        applications. This integration means that applications can continue to
-        leverage the authentication and authorization capabilities built into
-        containers (such as <literal>isUserInRole()</literal> and form-based
-        or basic authentication), whilst benefiting from the enhanced security
-        interception capabilities provided by the Acegi Security System for
-        Spring.</para>
-
-        <para>The integration between a container and the Acegi Security
-        System for Spring is achieved through an adapter. The adapter provides
-        a container-compatible user authentication provider, and needs to
-        return a container-compatible user object.</para>
-
-        <para>The adapter is instantiated by the container and is defined in a
-        container-specific configuration file. The adapter then loads a Spring
-        application context which defines the normal authentication manager
-        settings, such as the authentication providers that can be used to
-        authenticate the request. The application context is usually named
-        <literal>acegisecurity.xml</literal> and is placed in a
-        container-specific location.</para>
-
-        <para>The Acegi Security System for Spring currently supports Jetty,
-        Catalina (Tomcat), JBoss and Resin. Additional container adapters can
-        easily be written.</para>
-      </sect2>
-
-      <sect2 id="security-container-adapters-adapter-provider">
-        <title>Adapter Authentication Provider</title>
-
-        <para>As is always the case, the container adapter generated
-        <literal>Authentication</literal> object still needs to be
-        authenticated by an <literal>AuthenticationManager</literal> when
-        requested to do so by the
-        <literal>AbstractSecurityInterceptor</literal>. The
-        <literal>AuthenticationManager</literal> needs to be certain the
-        adapter-provided <literal>Authentication</literal> object is valid and
-        was actually authenticated by a trusted adapter.</para>
-
-        <para>Adapters create <literal>Authentication</literal> objects which
-        are immutable and implement the <literal>AuthByAdapter</literal>
-        interface. These objects store the hash of a key that is defined by
-        the adapter. This allows the <literal>Authentication</literal> object
-        to be validated by the <literal>AuthByAdapterProvider</literal>. This
-        authentication provider is defined as follows:</para>
-
-        <para><programlisting>&lt;bean id="authByAdapterProvider" class="net.sf.acegisecurity.adapters.AuthByAdapterProvider"&gt;
-  &lt;property name="key"&gt;&lt;value&gt;my_password&lt;/value&gt;&lt;/property&gt;
-&lt;/bean&gt;</programlisting></para>
-
-        <para>The key must match the key that is defined in the
-        container-specific configuration file that starts the adapter. The
-        <literal>AuthByAdapterProvider</literal> automatically accepts as
-        valid any <literal>AuthByAdapter</literal> implementation that returns
-        the expected hash of the key.</para>
-
-        <para>To reiterate, this means the adapter will perform the initial
-        authentication using providers such as
-        <literal>DaoAuthenticationProvider</literal>, returning an
-        <literal>AuthByAdapter</literal> instance that contains a hash code of
-        the key. Later, when an application calls a security interceptor
-        managed resource, the <literal>AuthByAdapter</literal> instance in the
-        <literal>SecureContext</literal> in the
-        <literal>ContextHolder</literal> will be tested by the application's
-        <literal>AuthByAdapterProvider</literal>. There is no requirement for
-        additional authentication providers such as
-        <literal>DaoAuthenticationProvider</literal> within the
-        application-specific application context, as the only type of
-        <literal>Authentication</literal> instance that will be presented by
-        the application is from the container adapter.</para>
-
-        <para>Classloader issues are frequent with containers and the use of
-        container adapters illustrates this further. Each container requires a
-        very specific configuration. The installation instructions are
-        provided below. Once installed, please take the time to try the sample
-        application to ensure your container adapter is properly
-        configured.</para>
-
-        <para>When using container adapters with the
-        <literal>DaoAuthenticationProvider</literal>, ensure you set its
-        <literal>forcePrincipalAsString</literal> property to
-        <literal>true</literal>.</para>
-      </sect2>
-
-      <sect2 id="security-container-adapters-catalina">
-        <title>Catalina (Tomcat) Installation</title>
-
-        <para>The following was tested with Jakarta Tomcat 4.1.30 and 5.0.19.
-        We automatically test the following directions using our container
-        integration test system and these versions of Catalina
-        (Tomcat).</para>
-
-        <para><literal>$CATALINA_HOME</literal> refers to the root of your
-        Catalina (Tomcat) installation.</para>
-
-        <para>Edit your <literal>$CATALINA_HOME/conf/server.xml</literal> file
-        so the <literal>&lt;Engine&gt;</literal> section contains only one
-        active <literal>&lt;Realm&gt;</literal> entry. An example realm
-        entry:</para>
-
-        <para><programlisting>      &lt;Realm className="net.sf.acegisecurity.adapters.catalina.CatalinaAcegiUserRealm"
-             appContextLocation="conf/acegisecurity.xml"
-             key="my_password" /&gt;</programlisting></para>
-
-        <para>Be sure to remove any other <literal>&lt;Realm&gt;</literal>
-        entry from your <literal>&lt;Engine&gt;</literal> section.</para>
-
-        <para>Copy <literal>acegisecurity.xml</literal> into
-        <literal>$CATALINA_HOME/conf</literal>.</para>
-
-        <para>Copy <literal>acegi-security-catalina-server.jar</literal> into
-        <literal>$CATALINA_HOME/server/lib</literal>.</para>
-
-        <para>Copy the following files into
-        <literal>$CATALINA_HOME/common/lib</literal>:</para>
-
-        <itemizedlist>
-          <listitem>
-            <para><literal>aopalliance.jar</literal></para>
-          </listitem>
-
-          <listitem>
-            <para><literal>spring.jar</literal></para>
-          </listitem>
-
-          <listitem>
-            <para><literal>acegi-security-catalina-common.jar</literal></para>
-          </listitem>
-
-          <listitem>
-            <para><literal>commons-codec.jar</literal></para>
-          </listitem>
-
-          <listitem>
-            <para><literal>burlap.jar</literal></para>
-          </listitem>
-
-          <listitem>
-            <para><literal>hessian.jar</literal></para>
-          </listitem>
-        </itemizedlist>
-
-        <para>None of the above JAR files (or
-        <literal>acegi-security.jar</literal>) should be in your application's
-        <literal>WEB-INF/lib</literal>. The realm name indicated in your
-        <literal>web.xml</literal> does not matter with Catalina.</para>
-
-        <para>We have received reports of problems using this Container
-        Adapter with Mac OS X. A work-around is to use a script such as
-        follows:</para>
-
-        <para><programlisting>#!/bin/sh
-export CATALINA_HOME="/Library/Tomcat"
-export JAVA_HOME="/Library/Java/Home"
-cd /
-$CATALINA_HOME/bin/startup.sh</programlisting></para>
-      </sect2>
-
-      <sect2 id="security-container-adapters-jetty">
-        <title>Jetty Installation</title>
-
-        <para>The following was tested with Jetty 4.2.18. We automatically
-        test the following directions using our container integration test
-        system and this version of Jetty.</para>
-
-        <para><literal>$JETTY_HOME</literal> refers to the root of your Jetty
-        installation.</para>
-
-        <para>Edit your <literal>$JETTY_HOME/etc/jetty.xml</literal> file so
-        the <literal>&lt;Configure class&gt;</literal> section has a new
-        addRealm call:</para>
-
-        <para><programlisting>  &lt;Call name="addRealm"&gt;
-    &lt;Arg&gt;
-      &lt;New class="net.sf.acegisecurity.adapters.jetty.JettyAcegiUserRealm"&gt;
-        &lt;Arg&gt;Spring Powered Realm&lt;/Arg&gt;
-        &lt;Arg&gt;my_password&lt;/Arg&gt;
-        &lt;Arg&gt;etc/acegisecurity.xml&lt;/Arg&gt;
-      &lt;/New&gt;
-    &lt;/Arg&gt;
-  &lt;/Call&gt;</programlisting></para>
-
-        <para>Copy <literal>acegisecurity.xml</literal> into
-        <literal>$JETTY_HOME/etc</literal>.</para>
-
-        <para>Copy the following files into
-        <literal>$JETTY_HOME/ext</literal>:<itemizedlist>
-            <listitem>
-              <para><literal>aopalliance.jar</literal></para>
-            </listitem>
-
-            <listitem>
-              <para><literal>commons-logging.jar</literal></para>
-            </listitem>
-
-            <listitem>
-              <para><literal>spring.jar</literal></para>
-            </listitem>
-
-            <listitem>
-              <para><literal>acegi-security-jetty-ext.jar</literal></para>
-            </listitem>
-
-            <listitem>
-              <para><literal>commons-codec.jar</literal></para>
-            </listitem>
-
-            <listitem>
-              <para><literal>burlap.jar</literal></para>
-            </listitem>
-
-            <listitem>
-              <para><literal>hessian.jar</literal></para>
-            </listitem>
-          </itemizedlist></para>
-
-        <para>None of the above JAR files (or
-        <literal>acegi-security.jar</literal>) should be in your application's
-        <literal>WEB-INF/lib</literal>. The realm name indicated in your
-        <literal>web.xml</literal> does matter with Jetty. The
-        <literal>web.xml</literal> must express the same
-        <literal>&lt;realm-name&gt;</literal> as your
-        <literal>jetty.xml</literal> (in the example above, "Spring Powered
-        Realm").</para>
-      </sect2>
-
-      <sect2 id="security-container-adapters-joss">
-        <title>JBoss Installation</title>
-
-        <para>The following was tested with JBoss 3.2.3. We automatically test
-        the following directions using our container integration test system
-        and this version of JBoss.</para>
-
-        <para><literal>$JBOSS_HOME</literal> refers to the root of your JBoss
-        installation.</para>
-
-        <para>Edit your
-        <literal>$JBOSS_HOME/server/your_config/conf/login-config.xml</literal>
-        file so that it contains a new entry under the
-        <literal>&lt;Policy&gt;</literal> section:</para>
-
-        <para><programlisting>    &lt;application-policy name = "SpringPoweredRealm"&gt;
-       &lt;authentication&gt;
-          &lt;login-module code = "net.sf.acegisecurity.adapters.jboss.JbossSpringLoginModule"
-            flag = "required"&gt;
-            &lt;module-option name = "appContextLocation"&gt;acegisecurity.xml&lt;/module-option&gt;
-            &lt;module-option name = "key"&gt;my_password&lt;/module-option&gt;
-         &lt;/login-module&gt;
-       &lt;/authentication&gt;
-    &lt;/application-policy&gt;</programlisting></para>
-
-        <para>Copy <literal>acegisecurity.xml</literal> into
-        <literal>$JBOSS_HOME/server/your_config/conf</literal>.</para>
-
-        <para>Copy the following files into
-        <literal>$JBOSS_HOME/server/your_config/lib</literal>:<itemizedlist>
-            <listitem>
-              <para><literal>aopalliance.jar</literal></para>
-            </listitem>
-
-            <listitem>
-              <para><literal>spring.jar</literal></para>
-            </listitem>
-
-            <listitem>
-              <para><literal>acegi-security-jboss-lib.jar</literal></para>
-            </listitem>
-
-            <listitem>
-              <para><literal>commons-codec.jar</literal></para>
-            </listitem>
-
-            <listitem>
-              <para><literal>burlap.jar</literal></para>
-            </listitem>
-
-            <listitem>
-              <para><literal>hessian.jar</literal></para>
-            </listitem>
-          </itemizedlist></para>
-
-        <para>None of the above JAR files (or
-        <literal>acegi-security.jar</literal>) should be in your application's
-        <literal>WEB-INF/lib</literal>. The realm name indicated in your
-        <literal>web.xml</literal> does not matter with JBoss. However, your
-        web application's <literal>WEB-INF/jboss-web.xml</literal> must
-        express the same <literal>&lt;security-domain&gt;</literal> as your
-        <literal>login-config.xml</literal>. For example, to match the above
-        example, your <literal>jboss-web.xml</literal> would look like
-        this:</para>
-
-        <para><programlisting>&lt;jboss-web&gt;
-  &lt;security-domain&gt;java:/jaas/SpringPoweredRealm&lt;/security-domain&gt;
-&lt;/jboss-web&gt;</programlisting></para>
-      </sect2>
-
-      <sect2 id="security-container-adapters-resin">
-        <title>Resin Installation</title>
-
-        <para>The following was tested with Resin 3.0.6.</para>
-
-        <para><literal>$RESIN_HOME</literal> refers to the root of your Resin
-        installation.</para>
-
-        <para>Resin provides several ways to support the container adapter. In
-        the instructions below we have elected to maximise consistency with
-        other container adapter configurations. This will allow Resin users to
-        simply deploy the sample application and confirm correct
-        configuration. Developers comfortable with Resin are naturally able to
-        use its capabilities to package the JARs with the web application
-        itself, and/or support single sign-on.</para>
-
-        <para>Copy the following files into
-        <literal>$RESIN_HOME/lib</literal>:<itemizedlist>
-            <listitem>
-              <para><literal>aopalliance.jar</literal></para>
-            </listitem>
-
-            <listitem>
-              <para><literal>commons-logging.jar</literal></para>
-            </listitem>
-
-            <listitem>
-              <para><literal>spring.jar</literal></para>
-            </listitem>
-
-            <listitem>
-              <para><literal>acegi-security-resin-lib.jar</literal></para>
-            </listitem>
-
-            <listitem>
-              <para><literal>commons-codec.jar</literal></para>
-            </listitem>
-
-            <listitem>
-              <para><literal>burlap.jar</literal></para>
-            </listitem>
-
-            <listitem>
-              <para><literal>hessian.jar</literal></para>
-            </listitem>
-          </itemizedlist></para>
-
-        <para>Unlike the container-wide <literal>acegisecurity.xml</literal>
-        files used by other container adapters, each Resin web application
-        will contain its own
-        <literal>WEB-INF/resin-acegisecurity.xml</literal> file. Each web
-        application will also contain a <literal>resin-web.xml</literal> file
-        which Resin uses to start the container adapter:</para>
-
-        <para><programlisting>&lt;web-app&gt;
-  &lt;authenticator&gt;
-    &lt;type&gt;net.sf.acegisecurity.adapters.resin.ResinAcegiAuthenticator&lt;/type&gt;
-    &lt;init&gt;
-      &lt;app-context-location&gt;WEB-INF/resin-acegisecurity.xml&lt;/app-context-location&gt;
-      &lt;key&gt;my_password&lt;/key&gt;
-    &lt;/init&gt;
-  &lt;/authenticator&gt;
-&lt;/web-app&gt;</programlisting></para>
-
-        <para>With the basic configuration provided above, none of the JAR
-        files listed (or <literal>acegi-security.jar</literal>) should be in
-        your application's <literal>WEB-INF/lib</literal>. The realm name
-        indicated in your <literal>web.xml</literal> does not matter with
-        Resin, as the relevant authentication class is indicated by the
-        <literal>&lt;authenticator&gt;</literal> setting.</para>
-      </sect2>
-    </sect1>
-
-    <sect1 id="security-cas">
-      <title>Yale Central Authentication Service (CAS) Single Sign On</title>
-
-      <sect2 id="security-cas-overview">
-        <title>Overview</title>
-
-        <para>Yale University produces an enterprise-wide single sign on
-        system known as CAS. Unlike other initiatives, Yale's Central
-        Authentication Service is open source, widely used, simple to
-        understand, platform independent, and supports proxy capabilities. The
-        Acegi Security System for Spring fully supports CAS, and provides an
-        easy migration path from single-application deployments of Acegi
-        Security through to multiple-application deployments secured by an
-        enterprise-wide CAS server.</para>
-
-        <para>You can learn more about CAS at
-        <literal>http://www.yale.edu/tp/auth/</literal>. You will need to
-        visit this URL to download the CAS Server files. Whilst the Acegi
-        Security System for Spring includes two CAS libraries in the
-        "-with-dependencies" ZIP file, you will still need the CAS Java Server
-        Pages and <literal>web.xml</literal> to customise and deploy your CAS
-        server.</para>
-      </sect2>
-
-      <sect2 id="security-cas-how-cas-works">
-        <title>How CAS Works</title>
-
-        <para>Whilst the CAS web site above contains two documents that detail
-        the architecture of CAS, we present the general overview again here
-        within the context of the Acegi Security System for Spring. The
-        following refers to CAS 2.0, being the version of CAS that Acegi
-        Security System for Spring supports.</para>
-
-        <para>Somewhere in your enterprise you will need to setup a CAS
-        server. The CAS server is simply a standard WAR file, so there isn't
-        anything difficult about setting up your server. Inside the WAR file
-        you will customise the login and other single sign on pages displayed
-        to users. You will also need to specify in the web.xml a
-        <literal>PasswordHandler</literal>. The
-        <literal>PasswordHandler</literal> has a simple method that returns a
-        boolean as to whether a given username and password is valid. Your
-        <literal>PasswordHandler</literal> implementation will need to link
-        into some type of backend authentication repository, such as an LDAP
-        server or database.</para>
-
-        <para>If you are already running an existing CAS server instance, you
-        will have already established a <literal>PasswordHandler</literal>. If
-        you do not already have a <literal>PasswordHandler</literal>, you
-        might prefer to use the Acegi Security System for Spring
-        <literal>CasPasswordHandler</literal> class. This class delegates
-        through to the standard Acegi Security
-        <literal>AuthenticationManager</literal>, enabling you to use a
-        security configuration you might already have in place. You do not
-        need to use the <literal>CasPasswordHandler</literal> class on your
-        CAS server if you do not wish. The Acegi Security System for Spring
-        will function as a CAS client successfully irrespective of the
-        <literal>PasswordHandler</literal> you've chosen for your CAS
-        server.</para>
-
-        <para>Apart from the CAS server itself, the other key player is of
-        course the secure web applications deployed throughout your
-        enterprise. These web applications are known as "services". There are
-        two types of services: standard services and proxy services. A proxy
-        service is able to request resources from other services on behalf of
-        the user. This will be explained more fully later.</para>
-
-        <para>Services can be developed in a large variety of languages, due
-        to CAS 2.0's very light XML-based protocol. The Yale CAS home page
-        contains a clients archive which demonstrates CAS clients in Java,
-        Active Server Pages, Perl, Python and others. Naturally, Java support
-        is very strong given the CAS server is written in Java. You do not
-        need to use any of CAS' client classes in applications secured by the
-        Acegi Security System for Spring. This is handled transparently for
-        you.</para>
-
-        <para>The basic interaction between a web browser, CAS server and an
-        Acegi Security for System Spring secured service is as follows:</para>
-
-        <orderedlist>
-          <listitem>
-            <para>The web user is browsing the service's public pages. CAS or
-            Acegi Security is not involved.</para>
-          </listitem>
-
-          <listitem>
-            <para>The user eventually requests a page that is either secure or
-            one of the beans it uses is secure. Acegi Security's
-            <literal>SecurityEnforcementFilter</literal> will detect the
-            <literal>AuthenticationException</literal>.</para>
-          </listitem>
-
-          <listitem>
-            <para>Because the user's <literal>Authentication</literal> object
-            (or lack thereof) caused an
-            <literal>AuthenticationException</literal>, the
-            <literal>SecurityEnforcementFilter</literal> will call the
-            configured <literal>AuthenticationEntryPoint</literal>. If using
-            CAS, this will be the
-            <literal>CasProcessingFilterEntryPoint</literal> class.</para>
-          </listitem>
-
-          <listitem>
-            <para>The <literal>CasProcessingFilterEntry</literal> point will
-            redirect the user's browser to the CAS server. It will also
-            indicate a <literal>service</literal> parameter, which is the
-            callback URL for the Acegi Security service. For example, the URL
-            to which the browser is redirected might be
-            <literal>https://my.company.com/cas/login?service=https%3A%2F%2Fserver3.company.com%2Fwebapp%2Fj_acegi_cas_security_check</literal>.</para>
-          </listitem>
-
-          <listitem>
-            <para>After the user's browser redirects to CAS, they will be
-            prompted for their username and password. If the user presents a
-            session cookie which indicates they've previously logged on, they
-            will not be prompted to login again (there is an exception to this
-            procedure, which we'll cover later). CAS will use the
-            <literal>PasswordHandler</literal> discussed above to decide
-            whether the username and password is valid.</para>
-          </listitem>
-
-          <listitem>
-            <para>Upon successful login, CAS will redirect the user's browser
-            back to the original service. It will also include a
-            <literal>ticket</literal> parameter, which is an opaque string
-            representing the "service ticket". Continuing our earlier example,
-            the URL the browser is redirected to might be
-            <literal>https://server3.company.com/webapp/j_acegi_cas_security_check?ticket=ST-0-ER94xMJmn6pha35CQRoZ</literal>.</para>
-          </listitem>
-
-          <listitem>
-            <para>Back in the service web application, the
-            <literal>CasProcessingFilter</literal> is always listening for
-            requests to <literal>/j_acegi_cas_security_check</literal> (this
-            is configurable, but we'll use the defaults in this introduction).
-            The processing filter will construct a
-            <literal>UsernamePasswordAuthenticationToken</literal>
-            representing the service ticket. The principal will be equal to
-            <literal>CasProcessingFilter.CAS_STATEFUL_IDENTIFIER</literal>,
-            whilst the credentials will be the service ticket opaque value.
-            This authentication request will then be handed to the configured
-            <literal>AuthenticationManager</literal>.</para>
-          </listitem>
-
-          <listitem>
-            <para>The <literal>AuthenticationManager</literal> implementation
-            will be the <literal>ProviderManager</literal>, which is in turn
-            configured with the <literal>CasAuthenticationProvider</literal>.
-            The <literal>CasAuthenticationProvider</literal> only responds to
-            <literal>UsernamePasswordAuthenticationToken</literal>s containing
-            the CAS-specific principal (such as
-            <literal>CasProcessingFilter.CAS_STATEFUL_IDENTIFIER</literal>)
-            and <literal>CasAuthenticationToken</literal>s (discussed
-            later).</para>
-          </listitem>
-
-          <listitem>
-            <para><literal>CasAuthenticationProvider</literal> will validate
-            the service ticket using a <literal>TicketValidator</literal>
-            implementation. Acegi Security includes one implementation, the
-            <literal>CasProxyTicketValidator</literal>. This implementation a
-            ticket validation class included in the CAS client library. The
-            <literal>CasProxyTicketValidator</literal> makes a HTTPS request
-            to the CAS server in order to validate the service ticket. The
-            <literal>CasProxyTicketValidator</literal> may also include a
-            proxy callback URL, which is included in this example:
-            <literal>https://my.company.com/cas/proxyValidate?service=https%3A%2F%2Fserver3.company.com%2Fwebapp%2Fj_acegi_cas_security_check&amp;ticket=ST-0-ER94xMJmn6pha35CQRoZ&amp;pgtUrl=https://server3.company.com/webapp/casProxy/receptor</literal>.</para>
-          </listitem>
-
-          <listitem>
-            <para>Back on the CAS server, the proxy validation request will be
-            received. If the presented service ticket matches the service URL
-            the ticket was issued to, CAS will provide an affirmative response
-            in XML indicating the username. If any proxy was involved in the
-            authentication (discussed below), the list of proxies is also
-            included in the XML response.</para>
-          </listitem>
-
-          <listitem>
-            <para>[OPTIONAL] If the request to the CAS validation service
-            included the proxy callback URL (in the <literal>pgtUrl</literal>
-            parameter), CAS will include a <literal>pgtIou</literal> string in
-            the XML response. This <literal>pgtIou</literal> represents a
-            proxy-granting ticket IOU. The CAS server will then create its own
-            HTTPS connection back to the <literal>pgtUrl</literal>. This is to
-            mutually authenticate the CAS server and the claimed service URL.
-            The HTTPS connection will be used to send a proxy granting ticket
-            to the original web application. For example,
-            <literal>https://server3.company.com/webapp/casProxy/receptor?pgtIou=PGTIOU-0-R0zlgrl4pdAQwBvJWO3vnNpevwqStbSGcq3vKB2SqSFFRnjPHt&amp;pgtId=PGT-1-si9YkkHLrtACBo64rmsi3v2nf7cpCResXg5MpESZFArbaZiOKH</literal>.
-            We suggest you use CAS' <literal>ProxyTicketReceptor</literal>
-            servlet to receive these proxy-granting tickets, if they are
-            required.</para>
-          </listitem>
-
-          <listitem>
-            <para>The <literal>CasProxyTicketValidator</literal> will parse
-            the XML received from the CAS server. It will return to the
-            <literal>CasAuthenticationProvider</literal> a
-            <literal>TicketResponse</literal>, which includes the username
-            (mandatory), proxy list (if any were involved), and proxy-granting
-            ticket IOU (if the proxy callback was requested).</para>
-          </listitem>
-
-          <listitem>
-            <para>Next <literal>CasAuthenticationProvider</literal> will call
-            a configured <literal>CasProxyDecider</literal>. The
-            <literal>CasProxyDecider</literal> indicates whether the proxy
-            list in the <literal>TicketResponse</literal> is acceptable to the
-            service. Several implementations are provided with the Acegi
-            Security System: <literal>RejectProxyTickets</literal>,
-            <literal>AcceptAnyCasProxy</literal> and
-            <literal>NamedCasProxyDecider</literal>. These names are largely
-            self-explanatory, except <literal>NamedCasProxyDecider</literal>
-            which allows a <literal>List</literal> of trusted proxies to be
-            provided.</para>
-          </listitem>
-
-          <listitem>
-            <para><literal>CasAuthenticationProvider</literal> will next
-            request a <literal>CasAuthoritiesPopulator</literal> to advise the
-            <literal>GrantedAuthority</literal> objects that apply to the user
-            contained in the <literal>TicketResponse</literal>. Acegi Security
-            includes a <literal>DaoCasAuthoritiesPopulator</literal> which
-            simply uses the <literal>AuthenticationDao</literal>
-            infrastructure to find the <literal>UserDetails</literal> and
-            their associated <literal>GrantedAuthority</literal>s. Note that
-            the password and enabled/disabled status of
-            <literal>UserDetails</literal> returned by the
-            <literal>AuthenticationDao</literal> are ignored, as the CAS
-            server is responsible for authentication decisions.
-            <literal>DaoCasAuthoritiesPopulator</literal> is only concerned
-            with retrieving the <literal>GrantedAuthority</literal>s.</para>
-          </listitem>
-
-          <listitem>
-            <para>If there were no problems,
-            <literal>CasAuthenticationProvider</literal> constructs a
-            <literal>CasAuthenticationToken</literal> including the details
-            contained in the <literal>TicketResponse</literal> and the
-            <literal>GrantedAuthority</literal>s. The
-            <literal>CasAuthenticationToken</literal> contains the hash of a
-            key, so that the <literal>CasAuthenticationProvider</literal>
-            knows it created it.</para>
-          </listitem>
-
-          <listitem>
-            <para>Control then returns to
-            <literal>CasProcessingFilter</literal>, which places the created
-            <literal>CasAuthenticationToken</literal> into the
-            <literal>HttpSession</literal> attribute named
-            <literal>HttpSessionIntegrationFilter.ACEGI_SECURITY_AUTHENTICATION_KEY</literal>.</para>
-          </listitem>
-
-          <listitem>
-            <para>The user's browser is redirected to the original page that
-            caused the <literal>AuthenticationException</literal>.</para>
-          </listitem>
-
-          <listitem>
-            <para>As the <literal>Authentication</literal> object is now in
-            the well-known location, it is handled like any other
-            authentication approach. Usually the
-            <literal>AutoIntegrationFilter</literal> will be used to associate
-            the <literal>Authentication</literal> object with the
-            <literal>ContextHolder</literal> for the duration of each
-            request.</para>
-          </listitem>
-        </orderedlist>
-
-        <para>It's good that you're still here! It might sound involved, but
-        you can relax as the Acegi Security System for Spring classes hide
-        much of the complexity. Let's now look at how this is
-        configured.</para>
-      </sect2>
-
-      <sect2 id="security-cas-install-server">
-        <title>CAS Server Installation (Optional)</title>
-
-        <para>As mentioned above, the Acegi Security System for Spring
-        includes a <literal>PasswordHandler</literal> that bridges your
-        existing <literal>AuthenticationManager</literal> into CAS. You do not
-        need to use this <literal>PasswordHandler</literal> to use Acegi
-        Security on the client side (any CAS
-        <literal>PasswordHandler</literal> will do).</para>
-
-        <para>To install, you will need to download and extract the CAS server
-        archive. We used version 2.0.12. There will be a
-        <literal>/web</literal> directory in the root of the deployment. Copy
-        an <literal>applicationContext.xml</literal> containing your
-        <literal>AuthenticationManager</literal> as well as the
-        <literal>CasPasswordHandler</literal> into the
-        <literal>/web/WEB-INF</literal> directory. A sample
-        <literal>applicationContext.xml</literal> is included below:</para>
-
-        <programlisting>&lt;bean id="inMemoryDaoImpl" class="net.sf.acegisecurity.providers.dao.memory.InMemoryDaoImpl"&gt;
-  &lt;property name="userMap"&gt;
-    &lt;value&gt;
-      marissa=koala,ROLES_IGNORED_BY_CAS
-      dianne=emu,ROLES_IGNORED_BY_CAS
-      scott=wombat,ROLES_IGNORED_BY_CAS
-      peter=opal,disabled,ROLES_IGNORED_BY_CAS
-    &lt;/value&gt;
-  &lt;/property&gt;
-&lt;/bean&gt;
-
-&lt;bean id="daoAuthenticationProvider" class="net.sf.acegisecurity.providers.dao.DaoAuthenticationProvider"&gt;
-  &lt;property name="authenticationDao"&gt;&lt;ref bean="inMemoryDaoImpl"/&gt;&lt;/property&gt;
-&lt;/bean&gt;
-
-&lt;bean id="authenticationManager" class="net.sf.acegisecurity.providers.ProviderManager"&gt;
-  &lt;property name="providers"&gt;
-    &lt;list&gt;
-      &lt;ref bean="daoAuthenticationProvider"/&gt;
-    &lt;/list&gt;
-  &lt;/property&gt;
-&lt;/bean&gt;
-
-&lt;bean id="casPasswordHandler" class="net.sf.acegisecurity.adapters.cas.CasPasswordHandler"&gt;
-  &lt;property name="authenticationManager"&gt;&lt;ref bean="authenticationManager"/&gt;&lt;/property&gt;
-&lt;/bean&gt;</programlisting>
-
-        <para>Note the granted authorities are ignored by CAS because it has
-        no way of communicating the granted authorities to calling
-        applications. CAS is only concerned with username and passwords (and
-        the enabled/disabled status).</para>
-
-        <para>Next you will need to edit the existing
-        <literal>/web/WEB-INF/web.xml</literal> file. Add (or edit in the case
-        of the <literal>authHandler</literal> property) the following
-        lines:</para>
-
-        <para><programlisting>&lt;context-param&gt;
-  &lt;param-name&gt;edu.yale.its.tp.cas.authHandler&lt;/param-name&gt;
-  &lt;param-value&gt;net.sf.acegisecurity.adapters.cas.CasPasswordHandlerProxy&lt;/param-value&gt;
-&lt;/context-param&gt;
-
-&lt;context-param&gt;
-  &lt;param-name&gt;contextConfigLocation&lt;/param-name&gt;
-  &lt;param-value&gt;/WEB-INF/applicationContext.xml&lt;/param-value&gt;
-&lt;/context-param&gt;
-
-&lt;listener&gt;
-  &lt;listener-class&gt;org.springframework.web.context.ContextLoaderListener&lt;/listener-class&gt;
-&lt;/listener&gt;</programlisting></para>
-
-        <para>Copy the <literal>spring.jar</literal> and
-        <literal>acegi-security.jar</literal> files into
-        <literal>/web/WEB-INF/lib</literal>. Now use the <literal>ant
-        dist</literal> task in the <literal>build.xml</literal> in the root of
-        the directory structure. This will create
-        <literal>/lib/cas.war</literal>, which is ready for deployment to your
-        servlet container.</para>
-
-        <para>Note CAS heavily relies on HTTPS. You can't even test the system
-        without a HTTPS certificate. Whilst you should refer to your web
-        container's documentation on setting up HTTPS, if you need some
-        additional help or a test certificate you might like to check the
-        <literal>samples/contacts/etc/ssl</literal> directory.</para>
-      </sect2>
-
-      <sect2 id="security-cas-install-client">
-        <title>CAS Acegi Security System Client Installation</title>
-
-        <para>The web application side of CAS is made easy due to the Acegi
-        Security System for Spring. It is assumed you already know the basics
-        of using the Acegi Security System for Spring, so these are not
-        covered again below. Only the CAS-specific beans are mentioned.</para>
-
-        <para>You will need to add a <literal>ServiceProperties</literal> bean
-        to your application context. This represents your service:</para>
-
-        <para><programlisting>&lt;bean id="serviceProperties" class="net.sf.acegisecurity.ui.cas.ServiceProperties"&gt;
-  &lt;property name="service"&gt;&lt;value&gt;https://localhost:8443/contacts-cas/j_acegi_cas_security_check&lt;/value&gt;&lt;/property&gt;
-  &lt;property name="sendRenew"&gt;&lt;value&gt;false&lt;/value&gt;&lt;/property&gt;
-&lt;/bean&gt;</programlisting></para>
-
-        <para>The <literal>service</literal> must equal a URL that will be
-        monitored by the <literal>CasProcessingFilter</literal>. The
-        <literal>sendRenew</literal> defaults to false, but should be set to
-        true if your application is particularly sensitive. What this
-        parameter does is tell the CAS login service that a single sign on
-        login is unacceptable. Instead, the user will need to re-enter their
-        username and password in order to gain access to the service.</para>
-
-        <para>The following beans should be configured to commence the CAS
-        authentication process:</para>
-
-        <para><programlisting>&lt;bean id="casProcessingFilter" class="net.sf.acegisecurity.ui.cas.CasProcessingFilter"&gt;
-  &lt;property name="authenticationManager"&gt;&lt;ref bean="authenticationManager"/&gt;&lt;/property&gt;
-  &lt;property name="authenticationFailureUrl"&gt;&lt;value&gt;/casfailed.jsp&lt;/value&gt;&lt;/property&gt;
-  &lt;property name="defaultTargetUrl"&gt;&lt;value&gt;/&lt;/value&gt;&lt;/property&gt;
-  &lt;property name="filterProcessesUrl"&gt;&lt;value&gt;/j_acegi_cas_security_check&lt;/value&gt;&lt;/property&gt;
-&lt;/bean&gt;
-
-&lt;bean id="securityEnforcementFilter" class="net.sf.acegisecurity.intercept.web.SecurityEnforcementFilter"&gt;
-  &lt;property name="filterSecurityInterceptor"&gt;&lt;ref bean="filterInvocationInterceptor"/&gt;&lt;/property&gt;
-  &lt;property name="authenticationEntryPoint"&gt;&lt;ref bean="casProcessingFilterEntryPoint"/&gt;&lt;/property&gt;
-&lt;/bean&gt;
-
-&lt;bean id="casProcessingFilterEntryPoint" class="net.sf.acegisecurity.ui.cas.CasProcessingFilterEntryPoint"&gt;
-  &lt;property name="loginUrl"&gt;&lt;value&gt;https://localhost:8443/cas/login&lt;/value&gt;&lt;/property&gt;
-  &lt;property name="serviceProperties"&gt;&lt;ref bean="serviceProperties"/&gt;&lt;/property&gt;
-&lt;/bean&gt;</programlisting></para>
-
-        <para>You will also need to add the
-        <literal>CasProcessingFilter</literal> to web.xml:</para>
-
-        <para><programlisting>&lt;filter&gt;
-  &lt;filter-name&gt;Acegi CAS Processing Filter&lt;/filter-name&gt;
-  &lt;filter-class&gt;net.sf.acegisecurity.util.FilterToBeanProxy&lt;/filter-class&gt;
-  &lt;init-param&gt;
-    &lt;param-name&gt;targetClass&lt;/param-name&gt;
-    &lt;param-value&gt;net.sf.acegisecurity.ui.cas.CasProcessingFilter&lt;/param-value&gt;
-  &lt;/init-param&gt;
-&lt;/filter&gt;
-
-&lt;filter-mapping&gt;
-  &lt;filter-name&gt;Acegi CAS Processing Filter&lt;/filter-name&gt;
-  &lt;url-pattern&gt;/*&lt;/url-pattern&gt;
-&lt;/filter-mapping&gt;</programlisting></para>
-
-        <para>The <literal>CasProcessingFilter</literal> has very similar
-        properties to the <literal>AuthenticationProcessingFilter</literal>
-        (used for form-based logins). Each property is
-        self-explanatory.</para>
-
-        <para>For CAS to operate, the
-        <literal>SecurityEnforcementFilter</literal> must have its
-        <literal>authenticationEntryPoint</literal> property set to the
-        <literal>CasProcessingFilterEntryPoint</literal> bean.</para>
-
-        <para>The <literal>CasProcessingFilterEntryPoint</literal> must refer
-        to the <literal>ServiceProperties</literal> bean (discussed above),
-        which provides the URL to the enterprise's CAS login server. This is
-        where the user's browser will be redirected.</para>
-
-        <para>Next you need to add an <literal>AuthenticationManager</literal>
-        that uses <literal>CasAuthenticationProvider</literal> and its
-        collaborators:</para>
-
-        <para><programlisting>&lt;bean id="authenticationManager" class="net.sf.acegisecurity.providers.ProviderManager"&gt;
-  &lt;property name="providers"&gt;
-    &lt;list&gt;
-      &lt;ref bean="casAuthenticationProvider"/&gt;
-    &lt;/list&gt;
-  &lt;/property&gt;
-&lt;/bean&gt;
-
-&lt;bean id="casAuthenticationProvider" class="net.sf.acegisecurity.providers.cas.CasAuthenticationProvider"&gt;
-  &lt;property name="casAuthoritiesPopulator"&gt;&lt;ref bean="casAuthoritiesPopulator"/&gt;&lt;/property&gt;
-  &lt;property name="casProxyDecider"&gt;&lt;ref bean="casProxyDecider"/&gt;&lt;/property&gt;
-  &lt;property name="ticketValidator"&gt;&lt;ref bean="casProxyTicketValidator"/&gt;&lt;/property&gt;
-  &lt;property name="statelessTicketCache"&gt;&lt;ref bean="statelessTicketCache"/&gt;&lt;/property&gt;
-  &lt;property name="key"&gt;&lt;value&gt;my_password_for_this_auth_provider_only&lt;/value&gt;&lt;/property&gt;
-&lt;/bean&gt;
-
-&lt;bean id="casProxyTicketValidator" class="net.sf.acegisecurity.providers.cas.ticketvalidator.CasProxyTicketValidator"&gt;
-  &lt;property name="casValidate"&gt;&lt;value&gt;https://localhost:8443/cas/proxyValidate&lt;/value&gt;&lt;/property&gt;
-  &lt;property name="proxyCallbackUrl"&gt;&lt;value&gt;https://localhost:8443/contacts-cas/casProxy/receptor&lt;/value&gt;&lt;/property&gt;
-  &lt;property name="serviceProperties"&gt;&lt;ref bean="serviceProperties"/&gt;&lt;/property&gt;
-  &lt;!-- &lt;property name="trustStore"&gt;&lt;value&gt;/some/path/to/your/lib/security/cacerts&lt;/value&gt;&lt;/property&gt; --&gt;
-&lt;/bean&gt;
-
-&lt;bean id="statelessTicketCache" class="net.sf.acegisecurity.providers.cas.cache.EhCacheBasedTicketCache"&gt;
-  &lt;property name="minutesToIdle"&gt;&lt;value&gt;20&lt;/value&gt;&lt;/property&gt;
-&lt;/bean&gt;
-
-&lt;bean id="casAuthoritiesPopulator" class="net.sf.acegisecurity.providers.cas.populator.DaoCasAuthoritiesPopulator"&gt;
-  &lt;property name="authenticationDao"&gt;&lt;ref bean="inMemoryDaoImpl"/&gt;&lt;/property&gt;
-&lt;/bean&gt;
-
-&lt;bean id="casProxyDecider" class="net.sf.acegisecurity.providers.cas.proxy.RejectProxyTickets"/&gt;</programlisting></para>
-
-        <para>The beans are all reasonable self-explanatory if you refer back
-        to the "How CAS Works" section. Careful readers might notice one
-        surprise: the <literal>statelessTicketCache</literal> property of the
-        <literal>CasAuthenticationProvider</literal>. This is discussed in
-        detail in the "Advanced CAS Usage" section.</para>
-
-        <para>Note the <literal>CasProxyTicketValidator</literal> has a
-        remarked out <literal>trustStore</literal> property. This property
-        might be helpful if you experience HTTPS certificate issues. Also note
-        the <literal>proxyCallbackUrl</literal> is set so the service can
-        receive a proxy-granting ticket. As mentioned above, this is optional
-        and unnecessary if you do not require proxy-granting tickets. If you
-        do use this feature, you will need to configure a suitable servlet to
-        receive the proxy-granting tickets. We suggest you use CAS'
-        <literal>ProxyTicketReceptor</literal> by adding the following to your
-        web application's <literal>web.xml</literal>:</para>
-
-        <para><programlisting>&lt;servlet&gt;
-  &lt;servlet-name&gt;casproxy&lt;/servlet-name&gt;
-  &lt;servlet-class&gt;edu.yale.its.tp.cas.proxy.ProxyTicketReceptor&lt;/servlet-class&gt;
-&lt;/servlet&gt;
-
-&lt;servlet-mapping&gt;
-  &lt;servlet-name&gt;casproxy&lt;/servlet-name&gt;
-  &lt;url-pattern&gt;/casProxy/*&lt;/url-pattern&gt;
-&lt;/servlet-mapping&gt;</programlisting></para>
-
-        <para>This completes the configuration of CAS. If you haven't made any
-        mistakes, your web application should happily work within the
-        framework of CAS single sign on. No other parts of the Acegi Security
-        System for Spring need to be concerned about the fact CAS handled
-        authentication.</para>
-
-        <para>There is also a <literal>contacts-cas.war</literal> file in the
-        sample applications directory. This sample application uses the above
-        settings and can be deployed to see CAS in operation.</para>
-      </sect2>
-
-      <sect2 id="security-cas-advanced-usage">
-        <title>Advanced CAS Usage</title>
-
-        <para>The <literal>CasAuthenticationProvider</literal> distinguishes
-        between stateful and stateless clients. A stateful client is
-        considered any that originates via the
-        <literal>CasProcessingFilter</literal>. A stateless client is any that
-        presents an authentication request via the
-        <literal>UsernamePasswordAuthenticationToken</literal> with a
-        principal equal to
-        <literal>CasProcessingFilter.CAS_STATELESS_IDENTIFIER</literal>.</para>
-
-        <para>Stateless clients are likely to be via remoting protocols such
-        as Hessian and Burlap. The <literal>BasicProcessingFilter</literal> is
-        still used in this case, but the remoting protocol client is expected
-        to present a username equal to the static string above, and a password
-        equal to a CAS service ticket. Clients should acquire a CAS service
-        ticket directly from the CAS server.</para>
-
-        <para>Because remoting protocols have no way of presenting themselves
-        within the context of a <literal>HttpSession</literal>, it isn't
-        possible to rely on the <literal>HttpSession</literal>'s
-        <literal>HttpSessionIntegrationFilter.ACEGI_SECURITY_AUTHENTICATION_KEY</literal>
-        attribute to locate the <literal>CasAuthenticationToken</literal>.
-        Furthermore, because the CAS server invalidates a service ticket after
-        it has been validated by the <literal>TicketValidator</literal>,
-        presenting the same service ticket on subsequent requests will not
-        work. It is similarly very difficult to obtain a proxy-granting ticket
-        for a remoting protocol client, as they are often deployed on client
-        machines which rarely have HTTPS URLs that would be accessible to the
-        CAS server.</para>
-
-        <para>One obvious option is to not use CAS at all for remoting
-        protocol clients. However, this would eliminate many of the desirable
-        features of CAS.</para>
-
-        <para>As a middle-ground, the
-        <literal>CasAuthenticationProvider</literal> uses a
-        <literal>StatelessTicketCache</literal>. This is used solely for
-        requests with a principal equal to
-        <literal>CasProcessingFilter.CAS_STATELESS_IDENTIFIER</literal>. What
-        happens is the <literal>CasAuthenticationProvider</literal> will store
-        the resulting <literal>CasAuthenticationToken</literal> in the
-        <literal>StatelessTicketCache</literal>, keyed on the service ticket.
-        Accordingly, remoting protocol clients can present the same service
-        ticket and the <literal>CasAuthenticationProvider</literal> will not
-        need to contact the CAS server for validation (aside from the first
-        request).</para>
-
-        <para>The other aspect of advanced CAS usage involves creating proxy
-        tickets from the proxy-granting ticket. As indicated above, we
-        recommend you use CAS' <literal>ProxyTicketReceptor</literal> to
-        receive these tickets. The <literal>ProxyTicketReceptor</literal>
-        provides a static method that enables you to obtain a proxy ticket by
-        presenting the proxy-granting IOU ticket. You can obtain the
-        proxy-granting IOU ticket by calling
-        <literal>CasAuthenticationToken.getProxyGrantingTicketIou()</literal>.</para>
-
-        <para>It is hoped you find CAS integration easy and useful with the
-        Acegi Security System for Spring classes. Welcome to enterprise-wide
-        single sign on!</para>
-      </sect2>
-    </sect1>
-
-    <sect1 id="security-channels">
-      <title>Channel Security</title>
-
-      <sect2 id="security-channels-overview">
-        <title>Overview</title>
-
-        <para>In addition to coordinating the authentication and authorization
-        requirements of your application, the Acegi Security System for Spring
-        is also able to ensure unauthenticated web requests have certain
-        properties. These properties may include being of a particular
-        transport type, having a particular <literal>HttpSession</literal>
-        attribute set and so on. The most common requirement is for your web
-        requests to be received using a particular transport protocol, such as
-        HTTPS.</para>
-
-        <para>An important issue in considering transport security is that of
-        session hijacking. Your web container manages a
-        <literal>HttpSession</literal> by reference to a
-        <literal>jsessionid</literal> that is sent to user agents either via a
-        cookie or URL rewriting. If the <literal>jsessionid</literal> is ever
-        sent over HTTP, there is a possibility that session identifier can be
-        intercepted and used to impersonate the user after they complete the
-        authentication process. This is because most web containers maintain
-        the same session identifier for a given user, even after they switch
-        from HTTP to HTTPS pages.</para>
-
-        <para>If session hijacking is considered too significant a risk for
-        your particular application, the only option is to use HTTPS for every
-        request. This means the <literal>jsessionid</literal> is never sent
-        across an insecure channel. You will need to ensure your
-        <literal>web.xml</literal>-defined
-        <literal>&lt;welcome-file&gt;</literal> points to a HTTPS location,
-        and the application never directs the user to a HTTP location. The
-        Acegi Security System for Spring provides a solution to assist with
-        the latter.</para>
-      </sect2>
-
-      <sect2 id="security-channels-installation">
-        <title>Configuration</title>
-
-        <para>To utilise Acegi Security's channel security services, add the
-        following lines to <literal>web.xml</literal>:</para>
-
-        <para><programlisting>&lt;filter&gt;
-  &lt;filter-name&gt;Acegi Channel Processing Filter&lt;/filter-name&gt;
-  &lt;filter-class&gt;net.sf.acegisecurity.util.FilterToBeanProxy&lt;/filter-class&gt;
-  &lt;init-param&gt;
-    &lt;param-name&gt;targetClass&lt;/param-name&gt;
-    &lt;param-value&gt;net.sf.acegisecurity.securechannel.ChannelProcessingFilter&lt;/param-value&gt;
-  &lt;/init-param&gt;
-&lt;/filter&gt;
-
-&lt;filter-mapping&gt;
-  &lt;filter-name&gt;Acegi Channel Processing Filter&lt;/filter-name&gt;
-  &lt;url-pattern&gt;/*&lt;/url-pattern&gt;
-&lt;/filter-mapping&gt;</programlisting></para>
-
-        <para>As usual when running <literal>FilterToBeanProxy</literal>, you
-        will also need to configure the filter in your application
-        context:</para>
-
-        <para><programlisting>&lt;bean id="channelProcessingFilter" class="net.sf.acegisecurity.securechannel.ChannelProcessingFilter"&gt;
-  &lt;property name="channelDecisionManager"&gt;&lt;ref bean="channelDecisionManager"/&gt;&lt;/property&gt;
-  &lt;property name="filterInvocationDefinitionSource"&gt;
-    &lt;value&gt;
-      CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON
-      \A/secure/.*\Z=REQUIRES_SECURE_CHANNEL
-      \A/acegilogin.jsp.*\Z=REQUIRES_SECURE_CHANNEL
-      \A/j_acegi_security_check.*\Z=REQUIRES_SECURE_CHANNEL	
-      \A.*\Z=REQUIRES_INSECURE_CHANNEL
-    &lt;/value&gt;
-  &lt;/property&gt;
-&lt;/bean&gt;
-
-&lt;bean id="channelDecisionManager" class="net.sf.acegisecurity.securechannel.ChannelDecisionManagerImpl"&gt;
-  &lt;property name="channelProcessors"&gt;
-    &lt;list&gt;
-      &lt;ref bean="secureChannelProcessor"/&gt;
-      &lt;ref bean="insecureChannelProcessor"/&gt;
-    &lt;/list&gt;
-  &lt;/property&gt;
-&lt;/bean&gt;
-
-&lt;bean id="secureChannelProcessor" class="net.sf.acegisecurity.securechannel.SecureChannelProcessor"/&gt;
-&lt;bean id="insecureChannelProcessor" class="net.sf.acegisecurity.securechannel.InsecureChannelProcessor"/&gt;</programlisting></para>
-
-        <para>Like <literal>FilterSecurityInterceptor</literal>, Apache Ant
-        style paths are also supported by the
-        <literal>ChannelProcessingFilter</literal>.</para>
-
-        <para>The <literal>ChannelProcessingFilter</literal> operates by
-        filtering all web requests and determining the configuration
-        attributes that apply. It then delegates to the
-        <literal>ChannelDecisionManager</literal>. The default implementation,
-        <literal>ChannelDecisionManagerImpl</literal>, should suffice in most
-        cases. It simply delegates through the list of configured
-        <literal>ChannelProcessor</literal> instances. A
-        <literal>ChannelProcessor</literal> will review the request, and if it
-        is unhappy with the request (eg it was received across the incorrect
-        transport protocol), it will perform a redirect, throw an exception or
-        take whatever other action is appropriate.</para>
-
-        <para>Included with the Acegi Security System for Spring are two
-        concrete <literal>ChannelProcessor</literal> implementations:
-        <literal>SecureChannelProcessor</literal> ensures requests with a
-        configuration attribute of <literal>REQUIRES_SECURE_CHANNEL</literal>
-        are received over HTTPS, whilst
-        <literal>InsecureChannelProcessor</literal> ensures requests with a
-        configuration attribute of
-        <literal>REQUIRES_INSECURE_CHANNEL</literal> are received over HTTP.
-        Both implementations delegate to a
-        <literal>ChannelEntryPoint</literal> if the required transport
-        protocol is not used. The two <literal>ChannelEntryPoint</literal>
-        implementations included with Acegi Security simply redirect the
-        request to HTTP and HTTPS as appropriate. Appropriate defaults are
-        assigned to the <literal>ChannelProcessor</literal> implementations
-        for the configuration attribute keywords they respond to and the
-        <literal>ChannelEntryPoint</literal> they delegate to, although you
-        have the ability to override these using the application
-        context.</para>
-
-        <para>Note that the redirections are absolute (eg
-        http://www.company.com:8080/app/page), not relative (eg /app/page).
-        During testing it was discovered that Internet Explorer 6 Service Pack
-        1 has a bug whereby it does not respond correctly to a redirection
-        instruction which also changes the port to use. Accordingly, absolute
-        URLs are used in conjunction with bug detection logic in the
-        <literal>PortResolverImpl</literal> that is wired up by default to
-        many Acegi Security beans. Please refer to the JavaDocs for
-        <literal>PortResolverImpl</literal> for further details.</para>
-      </sect2>
-
-      <sect2 id="security-channels-usage">
-        <title>Usage</title>
-
-        <para>Once configured, using the channel security filter is very easy.
-        Simply request pages without regard to the protocol (ie HTTP or HTTPS)
-        or port (eg 80, 8080, 443, 8443 etc). Obviously you'll still need a
-        way of making the initial request (probably via the
-        <literal>web.xml</literal> <literal>&lt;welcome-file&gt;</literal> or
-        a well-known home page URL), but once this is done the filter will
-        perform redirects as defined by your application context.</para>
-
-        <para>You can also add your own <literal>ChannelProcessor</literal>
-        implementations to the <literal>ChannelDecisionManagerImpl</literal>.
-        For example, you might set a <literal>HttpSession</literal> attribute
-        when a human user is detected via a "enter the contents of this
-        graphic" procedure. Your <literal>ChannelProcessor</literal> would
-        respond to say <literal>REQUIRES_HUMAN_USER</literal> configuration
-        attributes and redirect to an appropriate entry point to start the
-        human user validation process if the <literal>HttpSession</literal>
-        attribute is not currently set.</para>
-
-        <para>To decide whether a security check belongs in a
-        <literal>ChannelProcessor</literal> or an
-        <literal>AccessDecisionVoter</literal>, remember that the former is
-        designed to handle unauthenticated requests, whilst the latter is
-        designed to handle authenticated requests. The latter therefore has
-        access to the granted authorities of the authenticated principal. In
-        addition, problems detected by a <literal>ChannelProcessor</literal>
-        will generally cause a HTTP/HTTPS redirection so its requirements can
-        be met, whilst problems detected by an
-        <literal>AccessDecisionVoter</literal> will ultimately result in an
-        <literal>AccessDeniedException</literal> (depending on the governing
-        <literal>AccessDecisionManager</literal>).</para>
-      </sect2>
-    </sect1>
-
-    <sect1 id="acls">
-      <title>Instance-Based Access Control List (ACL) Security</title>
-
-      <sect2 id="acls-overview">
-        <title>Overview</title>
-
-        <para>THIS FEATURE WAS ADDED IN VERSION 0.6. WE WELCOME YOUR COMMENTS
-        AND IMPROVEMENTS.</para>
-
-        <para>Complex applications often will find the need to define access
-        permissions not simply at a web request or method invocation level.
-        Instead, security decisions need to comprise both who
-        (<literal>Authentication</literal>), where
-        (<literal>MethodInvocation</literal>) and what
-        (<literal>SomeDomainObject</literal>). In other words, authorization
-        decisions also need to consider the actual domain object instance
-        subject of a method invocation.</para>
-
-        <para>Imagine you're designing an application for a pet clinic. There
-        will be two main groups of users of your Spring-based application:
-        staff of the pet clinic, as well as the pet clinic's customers. The
-        staff will have access to all of the data, whilst your customers will
-        only be able to see their own customer records. To make it a little
-        more interesting, your customers can allow other users to see their
-        customer records, such as their "puppy preschool "mentor or president
-        of their local "Pony Club". Using Acegi Security System for Spring as
-        the foundation, you have several approaches that can be
-        used:<orderedlist>
-            <listitem>
-              <para>Write your business methods to enforce the security. You
-              could consult a collection within the
-              <literal>Customer</literal> domain object instance to determine
-              which users have access. By using the
-              <literal>ContextHolder.getContext()</literal> and casting it to
-              <literal>SecureContext</literal>, you'll be able to access the
-              <literal>Authentication</literal> object.</para>
-            </listitem>
-
-            <listitem>
-              <para>Write an <literal>AccessDecisionVoter</literal> to enforce
-              the security from the <literal>GrantedAuthority[]</literal>s
-              stored in the <literal>Authentication</literal> object. This
-              would mean your <literal>AuthenticationManager</literal> would
-              need to populate the <literal>Authentication</literal> with
-              custom <literal>GrantedAuthority</literal>[]s representing each
-              of the <literal>Customer</literal> domain object instances the
-              principal has access to.</para>
-            </listitem>
-
-            <listitem>
-              <para>Write an <literal>AccessDecisionVoter</literal> to enforce
-              the security and open the target <literal>Customer</literal>
-              domain object directly. This would mean your voter needs access
-              to a DAO that allows it to retrieve the
-              <literal>Customer</literal> object. It would then access the
-              <literal>Customer</literal> object's collection of approved
-              users and make the appropriate decision.</para>
-            </listitem>
-          </orderedlist></para>
-
-        <para>Each one of these approaches is perfectly legitimate. However,
-        the first couples your authorization checking to your business code.
-        The main problems with this include the enhanced difficulty of unit
-        testing and the fact it would be more difficult to reuse the
-        <literal>Customer</literal> authorization logic elsewhere. Obtaining
-        the <literal>GrantedAuthority[]</literal>s from the
-        <literal>Authentication</literal> object is also fine, but will not
-        scale to large numbers of <literal>Customer</literal>s. If a user
-        might be able to access 5,000 <literal>Customer</literal>s (unlikely
-        in this case, but imagine if it were a popular vet for a large Pony
-        Club!) the amount of memory consumed and time required to construct
-        the <literal>Authentication</literal> object would be undesirable. The
-        final method, opening the <literal>Customer</literal> directly from
-        external code, is probably the best of the three. It achieves
-        separation of concerns, and doesn't misuse memory or CPU cycles, but
-        it is still inefficient in that both the
-        <literal>AccessDecisionVoter</literal> and the eventual business
-        method itself will perform a call to the DAO responsible for
-        retrieving the <literal>Customer</literal> object. Two accesses per
-        method invocation is clearly undesirable. In addition, with every
-        approach listed you'll need to write your own access control list
-        (ACL) persistence and business logic from scratch.</para>
-
-        <para>Fortunately, there is another alternative, which we'll talk
-        about below.</para>
-      </sect2>
-
-      <sect2 id="acls-acl-package">
-        <title>The net.sf.acegisecurity.acl Package</title>
-
-        <para>The <literal>net.sf.acegisecurity.acl</literal> package is very
-        simple, comprising only a handful of interfaces and a single class. It
-        provides the basic foundation for access control list (ACL) lookups.
-        The central interface is <literal>AclManager</literal>, which is
-        defined by two methods:</para>
-
-        <para><programlisting>public AclEntry[] getAcls(java.lang.Object domainInstance);
-public AclEntry[] getAcls(java.lang.Object domainInstance, Authentication authentication);</programlisting></para>
-
-        <para><literal>AclManager</literal> is intended to be used as a
-        collaborator against your business objects, or, more desirably,
-        <literal>AccessDecisionVoter</literal>s. This means you use Spring's
-        normal <literal>ApplicationContext</literal> features to wire up your
-        <literal>AccessDecisionVoter</literal> (or business method) with an
-        <literal>AclManager</literal>. Consideration was given to placing the
-        ACL information in the <literal>ContextHolder</literal>, but it was
-        felt this would be inefficient both in terms of memory usage as well
-        as the time spent loading potentially unused ACL information. The
-        trade-off of needing to wire up a collaborator for those objects
-        requiring ACL information is rather minor, particularly in a
-        Spring-managed application.</para>
-
-        <para>The first method of the <literal>AclManager</literal> will
-        return all ACLs applying to the domain object instance passed to it.
-        The second method does the same, but only returns those ACLs which
-        apply to the passed <literal>Authentication</literal> object.</para>
-
-        <para>The <literal>AclEntry</literal> interface returned by
-        <literal>AclManager</literal> is merely a marker interface. You will
-        need to provide an implementation that reflects that ACL permissions
-        for your application.</para>
-
-        <para>Rounding out the <literal>net.sf.acegisecurity.acl</literal>
-        package is an <literal>AclProviderManager</literal> class, with a
-        corresponding <literal>AclProvider</literal> interface.
-        <literal>AclProviderManager</literal> is a concrete implementation of
-        <literal>AclManager</literal>, which iterates through registered
-        <literal>AclProvider</literal>s. The first
-        <literal>AclProvider</literal> that indicates it can authoritatively
-        provide ACL information for the presented domain object instance will
-        be used. This is very similar to the
-        <literal>AuthenticationProvider</literal> interface used for
-        authentication.</para>
-
-        <para>With this background, let's now look at a usable ACL
-        implementation.</para>
-      </sect2>
-
-      <sect2 id="acls-masking">
-        <title>Integer Masked ACLs</title>
-
-        <para>Acegi Security System for Spring includes a production-quality
-        ACL provider implementation. The implementation is based on integer
-        masking, which is commonly used for ACL permissions given its
-        flexibility and speed. Anyone who has used Unix's
-        <literal>chmod</literal> command will know all about this type of
-        permission masking (eg <literal>chmod 777</literal>). You'll find the
-        classes and interfaces for the integer masking ACL package under
-        <literal>net.sf.acegisecurity.acl.basic</literal>.</para>
-
-        <para>Extending the <literal>AclEntry</literal> interface is a
-        <literal>BasicAclEntry</literal> interface, with the main methods
-        shown below:</para>
-
-        <para><programlisting>public AclObjectIdentity getAclObjectIdentity();
-public AclObjectIdentity getAclObjectParentIdentity();
-public int getMask();
-public java.lang.Object getRecipient();</programlisting></para>
-
-        <para>As shown, each <literal>BasicAclEntry</literal> has four main
-        properties. The <literal>mask</literal> is the integer that represents
-        the permissions granted to the <literal>recipient</literal>. The
-        <literal>aclObjectIdentity</literal> is able to identify the domain
-        object instance for which the ACL applies, and the
-        <literal>aclObjectParentIdentity</literal> optionally specifies the
-        parent of the domain object instance. Multiple
-        <literal>BasicAclEntry</literal>s usually exist against a single
-        domain object instance, and as suggested by the parent identity
-        property, permissions granted higher in the object hierarchy will
-        trickle down and be inherited (unless blocked by integer zero).</para>
-
-        <para><literal>BasicAclEntry</literal> implementations typically
-        provide convenience methods, such as
-        <literal>isReadAllowed()</literal>, to avoid application classes
-        needing to perform bit masking themselves. The
-        <literal>SimpleAclEntry</literal> and
-        <literal>AbstractBasicAclEntry</literal> demonstrate and provide much
-        of this bit masking logic.</para>
-
-        <para>The <literal>AclObjectIdentity</literal> itself is merely a
-        marker interface, so you need to provide implementations for your
-        domain objects. However, the package does include a
-        <literal>NamedEntityObjectIdentity</literal> implementation which will
-        suit many needs. The <literal>NamedEntityObjectIdentity</literal>
-        identifies a given domain object instance by the classname of the
-        instance and the identity of the instance. A
-        <literal>NamedEntityObjectIdentity</literal> can be constructed
-        manually (by calling the constructor and providing the classname and
-        identity <literal>String</literal>s), or by passing in any domain
-        object that contains a <literal>getId()</literal> method.</para>
-
-        <para>The actual <literal>AclProvider</literal> implementation is
-        named <literal>BasicAclProvider</literal>. It has adopted a similar
-        design to that used by the authentication-related
-        <literal>DaoAuthenticationProvder</literal>. Specifically, you define
-        a <literal>BasicAclDao</literal> against the provider, so different
-        ACL repository types can be accessed in a pluggable manner. The
-        <literal>BasicAclProvider</literal> also supports pluggable cache
-        providers (with Acegi Security System for Spring including an
-        implementation that fronts EH-CACHE).</para>
-
-        <para>The <literal>BasicAclDao</literal> interface is very simple to
-        implement:</para>
-
-        <para><programlisting>public BasicAclEntry[] getAcls(AclObjectIdentity aclObjectIdentity);</programlisting></para>
-
-        <para>A <literal>BasicAclDao</literal> implementation needs to
-        understand the presented <literal>AclObjectIdentity</literal> and how
-        it maps to a storage repository, find the relevant records, and create
-        appropriate <literal>BasicAclEntry</literal> objects and return
-        them.</para>
-
-        <para>Acegi Security includes a single <literal>BasicAclDao</literal>
-        implementation called <literal>JdbcDaoImpl</literal>. As implied by
-        the name, it accesses ACL information from a JDBC database. The
-        default database schema and some sample data will aid in understanding
-        its function:</para>
-
-        <para><programlisting>CREATE TABLE acl_object_identity (
-     id IDENTITY NOT NULL,
-     object_identity VARCHAR_IGNORECASE(250) NOT NULL,
-     parent_object INTEGER,
-     acl_class VARCHAR_IGNORECASE(250) NOT NULL,
-     CONSTRAINT unique_object_identity UNIQUE(object_identity),
-     FOREIGN KEY (parent_object) REFERENCES acl_object_identity(id)
-);
-
-CREATE TABLE acl_permission (
-     id IDENTITY NOT NULL,
-     acl_object_identity INTEGER NOT NULL,
-     recipient VARCHAR_IGNORECASE(100) NOT NULL,
-     mask INTEGER NOT NULL,
-     CONSTRAINT unique_recipient UNIQUE(acl_object_identity, recipient),
-     FOREIGN KEY (acl_object_identity) REFERENCES acl_object_identity(id)
-);
-
-INSERT INTO acl_object_identity VALUES (1, 'corp.DomainObject:1', null, 'net.sf.acegisecurity.acl.basic.SimpleAclEntry');
-INSERT INTO acl_object_identity VALUES (2, 'corp.DomainObject:2', 1, 'net.sf.acegisecurity.acl.basic.SimpleAclEntry');
-INSERT INTO acl_object_identity VALUES (3, 'corp.DomainObject:3', 1, 'net.sf.acegisecurity.acl.basic.SimpleAclEntry');
-INSERT INTO acl_object_identity VALUES (4, 'corp.DomainObject:4', 1, 'net.sf.acegisecurity.acl.basic.SimpleAclEntry');
-INSERT INTO acl_object_identity VALUES (5, 'corp.DomainObject:5', 3, 'net.sf.acegisecurity.acl.basic.SimpleAclEntry');
-INSERT INTO acl_object_identity VALUES (6, 'corp.DomainObject:6', 3, 'net.sf.acegisecurity.acl.basic.SimpleAclEntry');
-
-INSERT INTO acl_permission VALUES (null, 1, 'ROLE_SUPERVISOR', 1);
-INSERT INTO acl_permission VALUES (null, 2, 'ROLE_SUPERVISOR', 0);
-INSERT INTO acl_permission VALUES (null, 2, 'marissa', 2);
-INSERT INTO acl_permission VALUES (null, 3, 'scott', 14);
-INSERT INTO acl_permission VALUES (null, 6, 'scott', 1);</programlisting></para>
-
-        <para>As can be seen, database-specific constraints are used
-        extensively to ensure the integrity of the ACL information. If you
-        need to use a different database (Hypersonic SQL statements are shown
-        above), you should try to implement equivalent constraints.</para>
-
-        <para>The <literal>JdbcDaoImpl</literal> will only respond to requests
-        for <literal>NamedEntityObjectIdentity</literal>s. It converts such
-        identities into a single <literal>String</literal>, comprising
-        the<literal> NamedEntityObjectIdentity.getClassname()</literal> +
-        <literal>":"</literal> +
-        <literal>NamedEntityObjectIdentity.getId()</literal>. This yields the
-        type of <literal>object_identity</literal> values shown above. As
-        indicated by the sample data, each database row corresponds to a
-        single <literal>BasicAclEntry</literal>. As stated earlier and
-        demonstrated by <literal>corp.DomainObject:2</literal> in the above
-        sample data, each domain object instance will often have multiple
-        <literal>BasicAclEntry</literal>[]s.</para>
-
-        <para>As <literal>JdbcDaoImpl</literal> is required to return concrete
-        <literal>BasicAclEntry</literal> classes, it needs to know which
-        <literal>BasicAclEntry</literal> implementation it is to create and
-        populate. This is the role of the <literal>acl_class</literal> column.
-        <literal>JdbcDaoImpl</literal> will create the indicated class and set
-        its <literal>mask</literal>, <literal>recipient</literal>,
-        <literal>aclObjectIdentity</literal> and
-        <literal>aclObjectParentIdentity</literal> properties.</para>
-
-        <para>As you can probably tell from the sample data, the
-        <literal>parent_object_identity</literal> value can either be null or
-        in the same format as the <literal>object_identity</literal>. If
-        non-null, <literal>JdbcDaoImpl</literal> will create a
-        <literal>NamedEntityObjectIdentity</literal> to place inside the
-        returned <literal>BasicAclEntry</literal> class.</para>
-
-        <para>Returning to the <literal>BasicAclProvider</literal>, before it
-        can poll the <literal>BasicAclDao</literal> implementation it needs to
-        convert the domain object instance it was passed into an
-        <literal>AclObjectIdentity</literal>.
-        <literal>BasicAclProvider</literal> has a <literal>protected
-        AclObjectIdentity obtainIdentity(Object domainInstance)</literal>
-        method that is responsible for this. As a protected method, it enables
-        subclasses to easily override. The normal implementation checks
-        whether the passed domain object instance implements the
-        <literal>AclObjectIdentityAware</literal> interface, which is merely a
-        getter for an <literal>AclObjectIdentity</literal>. If the domain
-        object does implement this interface, that is the identity returned.
-        If the domain object does not implement this interface, the method
-        will attempt to create an <literal>AclObjectIdentity</literal> by
-        passing the domain object instance to the constructor of a class
-        defined by the
-        <literal>BasicAclProvider.getDefaultAclObjectIdentity()</literal>
-        method. By default the defined class is
-        <literal>NamedEntityObjectIdentity</literal>, which was described in
-        more detail above. Therefore, you will need to either (i) provide a
-        <literal>getId()</literal> method on your domain objects, (ii)
-        implement <literal>AclObjectIdentityAware</literal> on your domain
-        objects, (iii) provide an alternative
-        <literal>AclObjectIdentity</literal> implementation that will accept
-        your domain object in its constructor, or (iv) override the
-        <literal>obtainIdentity(Object)</literal> method.</para>
-
-        <para>Once the <literal>AclObjectIdentity</literal> of the domain
-        object instance is determined, the <literal>BasicAclProvider</literal>
-        will poll the DAO to obtain its <literal>BasicAclEntry</literal>[]s.
-        If any of the entries returned by the DAO indicate there is a parent,
-        that parent will be polled, and the process will repeat until there is
-        no further parent. The permissions assigned to a
-        <literal>recipient</literal> closest to the domain object instance
-        will always take priority and override any inherited permissions. From
-        the sample data above, the following inherited permissions would
-        apply:</para>
-
-        <para><programlisting>--- Mask integer 0  = no permissions
---- Mask integer 1  = administer
---- Mask integer 2  = read
---- Mask integer 6  = read and write permissions
---- Mask integer 14 = read and write and create permissions
-
----------------------------------------------------------------------
---- *** INHERITED RIGHTS FOR DIFFERENT INSTANCES AND RECIPIENTS ***
---- INSTANCE  RECIPIENT         PERMISSION(S) (COMMENT #INSTANCE)
----------------------------------------------------------------------
----    1      ROLE_SUPERVISOR   Administer
----    2      ROLE_SUPERVISOR   None (overrides parent #1)
----           marissa           Read
----    3      ROLE_SUPERVISOR   Administer (from parent #1)
----           scott             Read, Write, Create
----    4      ROLE_SUPERVISOR   Administer (from parent #1)
----    5      ROLE_SUPERVISOR   Administer (from parent #3)
----           scott             Read, Write, Create (from parent #3)
----    6      ROLE_SUPERVISOR   Administer (from parent #3)
----           scott             Administer (overrides parent #3)</programlisting></para>
-
-        <para>So the above explains how a domain object instance has its
-        <literal>AclObjectIdentity</literal> discovered, and the
-        <literal>BasicAclDao</literal> will be polled successively until an
-        array of inherited permissions is constructed for the domain object
-        instance. The final step is to determine the
-        <literal>BasicAclEntry</literal>[]s that are actually applicable to a
-        given <literal>Authentication</literal> object.</para>
-
-        <para>As you would recall, the <literal>AclManager</literal> (and all
-        delegates, up to and including <literal>BasicAclProvider</literal>)
-        provides a method which returns only those
-        <literal>BasicAclEntry</literal>[]s applying to a passed
-        <literal>Authentication</literal> object.
-        <literal>BasicAclProvider</literal> delivers this functionality by
-        delegating the filtering operation to an
-        <literal>EffectiveAclsResolver</literal> implementation. The default
-        implementation,
-        <literal>GrantedAuthorityEffectiveAclsResolver</literal>, will iterate
-        through the <literal>BasicAclEntry</literal>[]s and include only those
-        where the <literal>recipient</literal> is equal to either the
-        <literal>Authentication</literal>'s <literal>principal</literal> or
-        any of the <literal>Authentication</literal>'s
-        <literal>GrantedAuthority</literal>[]s. Please refer to the JavaDocs
-        for more information.</para>
-      </sect2>
-
-      <sect2 id="acls-conclusion">
-        <title>Conclusion</title>
-
-        <para>Acegi Security's instance-specific ACL packages shield you from
-        much of the complexity of developing your own ACL approach. The
-        interfaces and classes detailed above provide a scalable, customisable
-        ACL solution that is decoupled from your application code. Whilst the
-        reference documentation may suggest complexity, the basic
-        implementation is able to support most typical applications
-        out-of-the-box.</para>
-      </sect2>
-    </sect1>
-
-    <sect1 id="security-filters">
-      <title>Filters</title>
-
-      <sect2 id="security-filters-overview">
-        <title>Overview</title>
-
-        <para>The Acegi Security System for Spring uses filters extensively.
-        Each filter is covered in detail in a respective section of this
-        document. This section includes information that applies to all
-        filters.</para>
-      </sect2>
-
-      <sect2 id="security-filters-filtertobeanproxy">
-        <title>FilterToBeanProxy</title>
-
-        <para>Most filters are configured using the
-        <literal>FilterToBeanProxy</literal>. An example configuration from
-        <literal>web.xml</literal> follows:</para>
-
-        <para><programlisting>&lt;filter&gt;
-  &lt;filter-name&gt;Acegi HTTP Request Security Filter&lt;/filter-name&gt;
-  &lt;filter-class&gt;net.sf.acegisecurity.util.FilterToBeanProxy&lt;/filter-class&gt;
-  &lt;init-param&gt;
-    &lt;param-name&gt;targetClass&lt;/param-name&gt;
-    &lt;param-value&gt;net.sf.acegisecurity.ClassThatImplementsFilter&lt;/param-value&gt;
-  &lt;/init-param&gt;
-&lt;/filter&gt;</programlisting></para>
-
-        <para>Notice that the filter in <literal>web.xml</literal> is actually
-        a <literal>FilterToBeanProxy</literal>, and not the filter that will
-        actually implements the logic of the filter. What
-        <literal>FilterToBeanProxy</literal> does is delegate the
-        <literal>Filter</literal>'s methods through to a bean which is
-        obtained from the Spring application context. This enables the bean to
-        benefit from the Spring application context lifecycle support and
-        configuration flexibility. The bean must implement
-        <literal>javax.servlet.Filter</literal>.</para>
-
-        <para>The <literal>FilterToBeanProxy</literal> only requires a single
-        initialization parameter, <literal>targetClass</literal> or
-        <literal>targetBean</literal>. The <literal>targetClass</literal>
-        parameter locates the first object in the application context of the
-        specified class, whilst <literal>targetBean</literal> locates the
-        object by bean name. Like standard Spring web applications, the
-        <literal>FilterToBeanProxy</literal> accesses the application context
-        via<literal>
-        WebApplicationContextUtils.getWebApplicationContext(ServletContext)</literal>,
-        so you should configure a <literal>ContextLoaderListener</literal> in
-        <literal>web.xml</literal>.</para>
-      </sect2>
-
-      <sect2 id="security-filters-order">
-        <title>Filter Ordering</title>
-
-        <para>The order that filters are defined in <literal>web.xml</literal>
-        is important.</para>
-
-        <para>Irrespective of which filters you are actually using, the order
-        of the <literal>&lt;filter-mapping&gt;</literal>s should be as
-        follows:</para>
-
-        <orderedlist>
-          <listitem>
-            <para>Acegi Channel Processing Filter
-            (<literal>ChannelProcessingFilter</literal>)</para>
-          </listitem>
-
-          <listitem>
-            <para>Acegi Authentication Processing Filter
-            (<literal>AuthenticationProcessingFilter</literal>)</para>
-          </listitem>
-
-          <listitem>
-            <para>Acegi CAS Processing Filter
-            (<literal>CasProcessingFilter</literal>)</para>
-          </listitem>
-
-          <listitem>
-            <para>Acegi HTTP BASIC Authorization Filter
-            (<literal>BasicProcessingFilter</literal>)</para>
-          </listitem>
-
-          <listitem>
-            <para>Acegi Security System for Spring Auto Integration Filter
-            (<literal>AutoIntegrationFilter</literal>)</para>
-          </listitem>
-
-          <listitem>
-            <para>Acegi HTTP Request Security Filter
-            (<literal>SecurityEnforcementFilter</literal>)</para>
-          </listitem>
-        </orderedlist>
-
-        <para>All of the above filters use
-        <literal>FilterToBeanProxy</literal>, which is discussed in the
-        previous section.</para>
-
-        <para>If you're using SiteMesh, ensure the Acegi Security filters
-        execute before the SiteMesh filters are called. This enables the
-        <literal>ContextHolder</literal> to be populated in time for use by
-        SiteMesh decorators.</para>
-      </sect2>
-    </sect1>
-
-    <sect1 id="security-sample">
-      <title>Contacts Sample Application</title>
-
-      <para>Included with the Acegi Security System for Spring is a very
-      simple application that can demonstrate the basic security facilities
-      provided by the system (and confirm your Container Adapter is properly
-      configured if you're using one).</para>
-
-      <para>The Contacts sample application includes two deployable versions:
-      <literal>contacts.war</literal> is configured with the HTTP Session
-      Authentication approach, and does not use Container Adapters. The
-      <literal>contacts-container-adapter.war</literal> is configured to use a
-      Container Adapter. If you're just wanting to see how the sample
-      application works, please use <literal>contacts.war</literal> as it does
-      not require special configuration of your container.</para>
-
-      <para>If you are going to use the
-      <literal>contacts-container-adapter.war</literal> version, first
-      configure your container as described in the Container Adapters section
-      of this chapter. Do not modify <literal>acegisecurity.xml</literal>. It
-      contains a very basic in-memory authentication configuration that is
-      compatible with the sample application.</para>
-
-      <para>To deploy, simply copy the relevant
-      <literal>contacts.war</literal> or
-      <literal>contacts-container-adapter.war</literal> file from the Acegi
-      Security System for Spring distribution into your container’s
-      <literal>webapps</literal> directory.</para>
-
-      <para>After starting your container, check the application can load.
-      Visit <literal>http://localhost:8080/contacts</literal> (or whichever
-      URL is appropriate for your web container and the WAR you deployed). A
-      random contact should be displayed. Click "Refresh" several times and
-      you will see different contacts. The business method that provides this
-      random contact is not secured.</para>
-
-      <para>Next, click "Debug". You will be prompted to authenticate, and a
-      series of usernames and passwords are suggested on that page. Simply
-      authenticate with any of these and view the resulting page. It should
-      contain a success message similar to the following:</para>
-
-      <blockquote>
-        <para>Context on ContextHolder is of type:
-        net.sf.acegisecurity.context.SecureContextImpl</para>
-
-        <para>The Context implements SecureContext.</para>
-
-        <para>Authentication object is of type:
-        net.sf.acegisecurity.adapters.PrincipalAcegiUserToken</para>
-
-        <para>Authentication object as a String:
-        net.sf.acegisecurity.adapters.PrincipalAcegiUserToken@e9a7c2:
-        Username: marissa; Password: [PROTECTED]; Authenticated: true; Granted
-        Authorities: ROLE_TELLER, ROLE_SUPERVISOR</para>
-
-        <para>Authentication object holds the following granted
-        authorities:</para>
-
-        <para>ROLE_TELLER (getAuthority(): ROLE_TELLER)</para>
-
-        <para>ROLE_SUPERVISOR (getAuthority(): ROLE_SUPERVISOR)</para>
-
-        <para>SUCCESS! Your [container adapter|web filter] appears to be
-        properly configured!</para>
-      </blockquote>
-
-      <para>If you receive a different message, and deployed
-      <literal>contacts-container-adapter.war</literal>, check you have
-      properly configured your Container Adapter. Refer to the instructions
-      provided above.</para>
-
-      <para>Once you successfully receive the above message, return to the
-      sample application's home page and click "Manage". You can then try out
-      the application. Notice that only the contacts belonging to the
-      currently logged on user are displayed, and only users with
-      <literal>ROLE_SUPERVISOR</literal> are granted access to delete their
-      contacts. Behind the scenes, the
-      <literal>MethodSecurityInterceptor</literal> is securing the business
-      objects. If you're using <literal>contacts.war</literal>, the
-      <literal>FilterSecurityInterceptor</literal> is also securing the HTTP
-      requests. If using <literal>contacts.war</literal>, be sure to try
-      visiting <literal>http://localhost:8080/contacts/secure/super</literal>,
-      which will demonstrate access being denied by the
-      <literal>SecurityEnforcementFilter</literal>.</para>
-
-      <para>The Contacts sample application also include a
-      <literal>client</literal> directory. Inside you will find a small
-      application that queries the backend business objects using the Hessian
-      and Burlap protocols. This demonstrates how to use the Acegi Security
-      System for Spring for authentication with Spring remoting protocols. To
-      try this client, ensure your servlet container is still running the
-      Contacts sample application, and then execute <literal>client marissa
-      marissa koala</literal>. The command-line parameters respectively
-      represent the owner of the contacts to extract, the username to use, and
-      the password to use. Note that you may need to edit
-      <literal>client.properties</literal> to use a different target URL. To
-      see that security does indeed work, try running <literal>client scott
-      marissa koala</literal>, which will try to obtain
-      <literal>scott</literal>'s contacts when authenticating as
-      <literal>marissa</literal>. To see it work properly, use <literal>client
-      scott scott wombat</literal>.</para>
-
-      <para>Please note the sample application's <literal>client</literal>
-      does not currently support CAS. You can still give it a try, though, if
-      you're ambitious: try <literal>client scott _cas_stateless_
-      YOUR-SERVICE-TICKET-ID-FOR-SCOTT</literal>.</para>
-    </sect1>
-
-    <sect1 id="security-become-involved">
-      <title>Become Involved</title>
-
-      <para>We welcome you to become involved in the Acegi Security System for
-      Spring project. There are many ways of contributing, including reading
-      the mailing list and responding to questions from other people, writing
-      new code, improving existing code, assisting with documentation, or
-      simply making suggestions.</para>
-
-      <para>SourceForge provides CVS services for the project, allowing
-      anybody to access the latest code. If you wish to contribute new code,
-      please observe the following requirements. These exist to maintain the
-      quality and consistency of the project:</para>
-
-      <itemizedlist>
-        <listitem>
-          <para>Run the Ant <literal>format</literal> task (or use a suitable
-          IDE plug-in) to convert your code into the project's consistent
-          style</para>
-        </listitem>
-
-        <listitem>
-          <para>Ensure your code does not break any unit tests (run the Ant
-          <literal>tests</literal> target)</para>
-        </listitem>
-
-        <listitem>
-          <para>Please use the container integration test system to test your
-          code in the project's officially supported containers</para>
-        </listitem>
-
-        <listitem>
-          <para>When writing a new container adapter, expand the container
-          integration test system to properly test it</para>
-        </listitem>
-
-        <listitem>
-          <para>If you have added new code, please provide suitable unit tests
-          (use <literal>ant clover.html</literal> to view coverage)</para>
-        </listitem>
-
-        <listitem>
-          <para>Join the acegisecurity-developer and acegisecurity-cvs mailing
-          lists so you're in the loop</para>
-        </listitem>
-
-        <listitem>
-          <para>Use CamelCase</para>
-        </listitem>
-
-        <listitem>
-          <para>Add a CVS <literal>$Id: index.xml,v 1.3 2004/04/02 21:12:25
-          fbos Exp $</literal> tag to the JavaDocs for any new class you
-          create</para>
-        </listitem>
-      </itemizedlist>
-
-      <para>Mentioned above is our container integration test system, which
-      aims to test the Acegi Security System for Spring container adapters
-      with current, production versions of each container. Some containers
-      might not be supported due to difficulties with starting or stopping the
-      container within an Ant target. You will need to download the container
-      release files as specified in the integration test
-      <literal>readme.txt</literal> file. These files are intentionally
-      excluded from CVS due to their large size.</para>
-    </sect1>
-
-    <sect1 id="security-further">
-      <title>Further Information</title>
-
-      <para>Questions and comments on the Acegi Security System for Spring are
-      welcome. Please use the Spring Community Forum web site at
-      <literal>http://forum.springframework.org</literal>. You're also welcome
-      to join the acegisecurity-developer mailing list. Our project home page
-      (where you can obtain the latest release of the project and access to
-      CVS, mailing lists, forums etc) is at
-      <literal>http://acegisecurity.sourceforge.net</literal>.</para>
-    </sect1>
-  </chapter>
-</book>

docs/reference/styles/fopdf.xsl

@@ -1,488 +0,0 @@
-<?xml version="1.0"?>
-
-<!-- 
-
-    This is the XSL FO configuration file for the Hibernate
-    Reference Documentation. It defines a custom titlepage and
-    the parameters for the A4 sized PDF printable output.
-    
-    It took me days to figure out this stuff and fix most of
-    the obvious bugs in the DocBook XSL distribution, so if you
-    use this stylesheet, give some credit back to the Hibernate
-    project.
-    
-    christian.bauer@bluemars.de
--->
-
-<!DOCTYPE xsl:stylesheet [
-    <!ENTITY db_xsl_path        "../lib/docbook-xsl/">
-    <!ENTITY admon_gfx_path     "../images/admons/">
-]>
-
-<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
-                version="1.0"
-                xmlns="http://www.w3.org/TR/xhtml1/transitional"
-                xmlns:fo="http://www.w3.org/1999/XSL/Format"
-                exclude-result-prefixes="#default">
-                
-<xsl:import href="&db_xsl_path;/fo/docbook.xsl"/>
-
-<!--###################################################
-                   Custom Title Page
-    ################################################### --> 
-    
-    <xsl:template name="book.titlepage.recto">
-        <fo:block>
-            <fo:table table-layout="fixed" width="175mm">
-                <fo:table-column column-width="175mm"/>
-                <fo:table-body>
-                    <fo:table-row>
-                        <fo:table-cell text-align="center">
-                            <fo:block>
-                                <fo:external-graphic src="file:images/logo.gif"/>
-                            </fo:block>
-                            <fo:block font-family="Helvetica" font-size="22pt" padding-before="10mm">
-                                <xsl:value-of select="bookinfo/subtitle"/> 
-                            </fo:block>
-                            <fo:block font-family="Helvetica" font-size="12pt" padding="10mm">
-                                <xsl:value-of select="bookinfo/releaseinfo"/>  
-                            </fo:block>
-                        </fo:table-cell>
-                    </fo:table-row>
-                    <fo:table-row>
-                        <fo:table-cell text-align="center">
-                            <fo:block font-family="Helvetica" font-size="14pt" padding="10mm">
-                                <xsl:value-of select="bookinfo/pubdate"/> 
-                            </fo:block>
-                        </fo:table-cell>
-                    </fo:table-row>
-                    <fo:table-row>
-                        <fo:table-cell text-align="center">
-                            <fo:block font-family="Helvetica" font-size="12pt" padding="10mm">
-                                <xsl:text>Copyright (c) 2004  -  </xsl:text>
-                                <xsl:for-each select="bookinfo/authorgroup/author">
-                                    <xsl:if test="position() > 1">
-                                        <xsl:text>, </xsl:text>
-                                    </xsl:if>
-                                    <xsl:value-of select="firstname"/>
-                                    <xsl:text> </xsl:text>
-                                    <xsl:value-of select="surname"/>
-                                </xsl:for-each>
-                            </fo:block>
-                            <fo:block font-family="Helvetica" font-size="10pt" padding="1mm">
-                                <xsl:value-of select="bookinfo/legalnotice"/>  
-                            </fo:block>
-                        </fo:table-cell>
-                    </fo:table-row>
-                </fo:table-body>
-            </fo:table>
-        </fo:block>
-    </xsl:template>
-
-    <!-- Prevent blank pages in output -->    
-    <xsl:template name="book.titlepage.before.verso">
-    </xsl:template>
-    <xsl:template name="book.titlepage.verso">
-    </xsl:template>
-    <xsl:template name="book.titlepage.separator">
-    </xsl:template>
-        
-<!--###################################################
-                      Header
-    ################################################### -->  
-
-    <!-- More space in the center header for long text -->
-    <xsl:attribute-set name="header.content.properties">
-        <xsl:attribute name="font-family">
-            <xsl:value-of select="$body.font.family"/>
-        </xsl:attribute>
-        <xsl:attribute name="margin-left">-5em</xsl:attribute>
-        <xsl:attribute name="margin-right">-5em</xsl:attribute>
-    </xsl:attribute-set>
-
-<!--###################################################
-                      Custom Footer
-    ################################################### -->     
-
-    <!-- This footer prints the version number on the left side -->
-    <xsl:template name="footer.content">
-        <xsl:param name="pageclass" select="''"/>
-        <xsl:param name="sequence" select="''"/>
-        <xsl:param name="position" select="''"/>
-        <xsl:param name="gentext-key" select="''"/>
-
-        <xsl:variable name="Version">
-            <xsl:choose>
-                <xsl:when test="//releaseinfo">
-                        <xsl:text>Acegi Security System for Spring </xsl:text><xsl:value-of select="//releaseinfo"/>
-                </xsl:when>
-                <xsl:otherwise>
-                    <!-- nop -->
-                </xsl:otherwise>
-            </xsl:choose>
-        </xsl:variable>
-
-        <xsl:choose>
-            <xsl:when test="$sequence='blank'">
-            <xsl:choose>
-                <xsl:when test="$double.sided != 0 and $position = 'left'">
-                <xsl:value-of select="$Version"/>
-                </xsl:when>
-
-                <xsl:when test="$double.sided = 0 and $position = 'center'">
-                <!-- nop -->
-                </xsl:when>
-
-                <xsl:otherwise>
-                <fo:page-number/>
-                </xsl:otherwise>
-            </xsl:choose>
-            </xsl:when>
-
-            <xsl:when test="$pageclass='titlepage'">
-            <!-- nop: other titlepage sequences have no footer -->
-            </xsl:when>
-
-            <xsl:when test="$double.sided != 0 and $sequence = 'even' and $position='left'">
-            <fo:page-number/>
-            </xsl:when>
-
-            <xsl:when test="$double.sided != 0 and $sequence = 'odd' and $position='right'">
-            <fo:page-number/>
-            </xsl:when>
-
-            <xsl:when test="$double.sided = 0 and $position='right'">
-            <fo:page-number/>
-            </xsl:when>
-
-            <xsl:when test="$double.sided != 0 and $sequence = 'odd' and $position='left'">
-            <xsl:value-of select="$Version"/>
-            </xsl:when>
-
-            <xsl:when test="$double.sided != 0 and $sequence = 'even' and $position='right'">
-            <xsl:value-of select="$Version"/>
-            </xsl:when>
-
-            <xsl:when test="$double.sided = 0 and $position='left'">
-            <xsl:value-of select="$Version"/>
-            </xsl:when>
-
-            <xsl:otherwise>
-            <!-- nop -->
-            </xsl:otherwise>
-        </xsl:choose>
-    </xsl:template>    
-    
-<!--###################################################
-                   Custom Toc Line
-    ################################################### -->
-    
-    <!-- The default DocBook XSL TOC printing is seriously broken... -->
-    <xsl:template name="toc.line">
-        <xsl:variable name="id">
-            <xsl:call-template name="object.id"/>
-        </xsl:variable>
-
-        <xsl:variable name="label">
-            <xsl:apply-templates select="." mode="label.markup"/>
-        </xsl:variable>
-
-        <!-- justify-end removed from block attributes (space problem in title.markup) -->
-        <fo:block  end-indent="{$toc.indent.width}pt"
-                   last-line-end-indent="-{$toc.indent.width}pt"
-                   white-space-treatment="preserve"
-                   white-space-collapse="false">
-            <fo:inline keep-with-next.within-line="always">
-                <!-- print Chapters in bold style -->
-                <xsl:choose>
-                    <xsl:when test="local-name(.) = 'chapter'">
-                        <xsl:attribute name="font-weight">bold</xsl:attribute>
-                    </xsl:when>
-                </xsl:choose>        
-                <fo:basic-link internal-destination="{$id}">
-                    <xsl:if test="$label != ''">
-                        <xsl:copy-of select="$label"/>
-                        <fo:inline white-space-treatment="preserve"
-                                    white-space-collapse="false">
-                            <xsl:value-of select="$autotoc.label.separator"/>
-                        </fo:inline>
-                    </xsl:if>
-                    <xsl:apply-templates select="." mode="title.markup"/>
-                </fo:basic-link>
-            </fo:inline>
-            <fo:inline keep-together.within-line="always">
-            <xsl:text> </xsl:text>
-            <fo:leader leader-pattern="dots"
-                        leader-pattern-width="3pt"
-                        leader-alignment="reference-area"
-                        keep-with-next.within-line="always"/>
-            <xsl:text> </xsl:text>
-            <fo:basic-link internal-destination="{$id}">
-                <fo:page-number-citation ref-id="{$id}"/>
-            </fo:basic-link>
-            </fo:inline>
-        </fo:block>
-    </xsl:template>
-    
-<!--###################################################
-                      Extensions
-    ################################################### -->  
-
-    <!-- These extensions are required for table printing and other stuff -->
-    <xsl:param name="use.extensions">1</xsl:param>
-    <xsl:param name="tablecolumns.extension">0</xsl:param>
-    <xsl:param name="callout.extensions">1</xsl:param>
-    <!-- FOP provide only PDF Bookmarks at the moment -->
-    <xsl:param name="fop.extensions">1</xsl:param>
-
-<!--###################################################
-                      Table Of Contents
-    ################################################### -->   
-
-    <!-- Generate the TOCs for named components only -->
-    <xsl:param name="generate.toc">
-        book   toc
-    </xsl:param>
-    
-    <!-- Show only Sections up to level 3 in the TOCs -->
-    <xsl:param name="toc.section.depth">2</xsl:param>
-    
-    <!-- Dot and Whitespace as separator in TOC between Label and Title-->
-    <xsl:param name="autotoc.label.separator" select="'.  '"/>
-
-        
-<!--###################################################
-                   Paper & Page Size
-    ################################################### -->  
-    
-    <!-- Paper type, no headers on blank pages, no double sided printing -->
-    <xsl:param name="paper.type" select="'A4'"/>
-    <xsl:param name="double.sided">0</xsl:param>
-    <xsl:param name="headers.on.blank.pages">0</xsl:param>
-    <xsl:param name="footers.on.blank.pages">0</xsl:param>
-
-    <!-- Space between paper border and content (chaotic stuff, don't touch) -->
-    <xsl:param name="page.margin.top">5mm</xsl:param>
-    <xsl:param name="region.before.extent">10mm</xsl:param>
-    <xsl:param name="body.margin.top">10mm</xsl:param>
-    
-    <xsl:param name="body.margin.bottom">15mm</xsl:param>
-    <xsl:param name="region.after.extent">10mm</xsl:param>
-    <xsl:param name="page.margin.bottom">0mm</xsl:param>
-    
-    <xsl:param name="page.margin.outer">18mm</xsl:param>
-    <xsl:param name="page.margin.inner">18mm</xsl:param>
-
-    <!-- No intendation of Titles -->
-    <xsl:param name="title.margin.left">0pc</xsl:param>
-
-<!--###################################################
-                   Fonts & Styles
-    ################################################### -->      
-
-    <!-- Left aligned text and no hyphenation -->
-    <xsl:param name="alignment">left</xsl:param>
-    <xsl:param name="hyphenate">false</xsl:param>
-
-    <!-- Default Font size -->
-    <xsl:param name="body.font.master">11</xsl:param>
-    <xsl:param name="body.font.small">8</xsl:param>
-
-    <!-- Line height in body text -->
-    <xsl:param name="line-height">1.4</xsl:param>
-
-    <!-- Monospaced fonts are smaller than regular text -->
-    <xsl:attribute-set name="monospace.properties">
-        <xsl:attribute name="font-family">
-            <xsl:value-of select="$monospace.font.family"/>
-        </xsl:attribute>
-        <xsl:attribute name="font-size">0.8em</xsl:attribute>
-    </xsl:attribute-set>
-    
-<!--###################################################
-                   Tables
-    ################################################### -->
-
-    <!-- The table width should be adapted to the paper size -->
-    <xsl:param name="default.table.width">17.4cm</xsl:param>
-
-    <!-- Some padding inside tables -->    
-    <xsl:attribute-set name="table.cell.padding">
-        <xsl:attribute name="padding-left">4pt</xsl:attribute>
-        <xsl:attribute name="padding-right">4pt</xsl:attribute>
-        <xsl:attribute name="padding-top">4pt</xsl:attribute>
-        <xsl:attribute name="padding-bottom">4pt</xsl:attribute>
-    </xsl:attribute-set>
-    
-    <!-- Only hairlines as frame and cell borders in tables -->
-    <xsl:param name="table.frame.border.thickness">0.1pt</xsl:param>
-    <xsl:param name="table.cell.border.thickness">0.1pt</xsl:param>
-        
-<!--###################################################
-                         Labels
-    ################################################### -->   
-
-    <!-- Label Chapters and Sections (numbering) -->
-    <xsl:param name="chapter.autolabel">1</xsl:param>
-    <xsl:param name="section.autolabel" select="1"/>
-    <xsl:param name="section.label.includes.component.label" select="1"/>
-
-<!--###################################################
-                         Titles
-    ################################################### -->   
-    
-    <!-- Chapter title size -->
-    <xsl:attribute-set name="chapter.titlepage.recto.style">
-        <xsl:attribute name="text-align">left</xsl:attribute>
-        <xsl:attribute name="font-weight">bold</xsl:attribute>
-        <xsl:attribute name="font-size">
-            <xsl:value-of select="$body.font.master * 1.8"/>
-            <xsl:text>pt</xsl:text>
-        </xsl:attribute>        
-    </xsl:attribute-set>
-
-    <!-- Why is the font-size for chapters hardcoded in the XSL FO templates? 
-        Let's remove it, so this sucker can use our attribute-set only... -->
-    <xsl:template match="title" mode="chapter.titlepage.recto.auto.mode">
-        <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format"
-                  xsl:use-attribute-sets="chapter.titlepage.recto.style">
-            <xsl:call-template name="component.title">
-                <xsl:with-param name="node" select="ancestor-or-self::chapter[1]"/>
-            </xsl:call-template>
-            </fo:block>
-    </xsl:template>
-    
-    <!-- Sections 1, 2 and 3 titles have a small bump factor and padding -->    
-    <xsl:attribute-set name="section.title.level1.properties">
-        <xsl:attribute name="space-before.optimum">0.8em</xsl:attribute>
-        <xsl:attribute name="space-before.minimum">0.8em</xsl:attribute>
-        <xsl:attribute name="space-before.maximum">0.8em</xsl:attribute>
-        <xsl:attribute name="font-size">
-            <xsl:value-of select="$body.font.master * 1.5"/>
-            <xsl:text>pt</xsl:text>
-        </xsl:attribute>
-        <xsl:attribute name="space-after.optimum">0.1em</xsl:attribute>
-        <xsl:attribute name="space-after.minimum">0.1em</xsl:attribute>
-        <xsl:attribute name="space-after.maximum">0.1em</xsl:attribute>
-    </xsl:attribute-set>
-    <xsl:attribute-set name="section.title.level2.properties">
-        <xsl:attribute name="space-before.optimum">0.6em</xsl:attribute>
-        <xsl:attribute name="space-before.minimum">0.6em</xsl:attribute>
-        <xsl:attribute name="space-before.maximum">0.6em</xsl:attribute>
-        <xsl:attribute name="font-size">
-            <xsl:value-of select="$body.font.master * 1.25"/>
-            <xsl:text>pt</xsl:text>
-        </xsl:attribute>
-        <xsl:attribute name="space-after.optimum">0.1em</xsl:attribute>
-        <xsl:attribute name="space-after.minimum">0.1em</xsl:attribute>
-        <xsl:attribute name="space-after.maximum">0.1em</xsl:attribute>
-    </xsl:attribute-set>
-    <xsl:attribute-set name="section.title.level3.properties">
-        <xsl:attribute name="space-before.optimum">0.4em</xsl:attribute>
-        <xsl:attribute name="space-before.minimum">0.4em</xsl:attribute>
-        <xsl:attribute name="space-before.maximum">0.4em</xsl:attribute>
-        <xsl:attribute name="font-size">
-            <xsl:value-of select="$body.font.master * 1.0"/>
-            <xsl:text>pt</xsl:text>
-        </xsl:attribute>
-        <xsl:attribute name="space-after.optimum">0.1em</xsl:attribute>
-        <xsl:attribute name="space-after.minimum">0.1em</xsl:attribute>
-        <xsl:attribute name="space-after.maximum">0.1em</xsl:attribute>
-    </xsl:attribute-set>
-
-    <!-- Titles of formal objects (tables, examples, ...) -->
-    <xsl:attribute-set name="formal.title.properties" use-attribute-sets="normal.para.spacing">
-        <xsl:attribute name="font-weight">bold</xsl:attribute>
-        <xsl:attribute name="font-size">
-            <xsl:value-of select="$body.font.master"/>
-            <xsl:text>pt</xsl:text>
-        </xsl:attribute>
-        <xsl:attribute name="hyphenate">false</xsl:attribute>
-        <xsl:attribute name="space-after.minimum">0.4em</xsl:attribute>
-        <xsl:attribute name="space-after.optimum">0.6em</xsl:attribute>
-        <xsl:attribute name="space-after.maximum">0.8em</xsl:attribute>
-    </xsl:attribute-set>    
-
-<!--###################################################
-                      Programlistings
-    ################################################### -->  
-    
-    <!-- Verbatim text formatting (programlistings) -->
-    <xsl:attribute-set name="monospace.verbatim.properties">
-        <xsl:attribute name="font-size">
-            <xsl:value-of select="$body.font.small * 1.0"/>
-            <xsl:text>pt</xsl:text>
-        </xsl:attribute>
-    </xsl:attribute-set>
-    
-    <xsl:attribute-set name="verbatim.properties">
-        <xsl:attribute name="space-before.minimum">1em</xsl:attribute>
-        <xsl:attribute name="space-before.optimum">1em</xsl:attribute>
-        <xsl:attribute name="space-before.maximum">1em</xsl:attribute>
-        <!-- alef: commented out because footnotes were screwed because of it -->
-        <!--<xsl:attribute name="space-after.minimum">0.1em</xsl:attribute>
-        <xsl:attribute name="space-after.optimum">0.1em</xsl:attribute>
-        <xsl:attribute name="space-after.maximum">0.1em</xsl:attribute>-->
-        <xsl:attribute name="border-color">#444444</xsl:attribute>
-        <xsl:attribute name="border-style">solid</xsl:attribute>
-        <xsl:attribute name="border-width">0.1pt</xsl:attribute>      
-        <xsl:attribute name="padding-top">0.5em</xsl:attribute>      
-        <xsl:attribute name="padding-left">0.5em</xsl:attribute>      
-        <xsl:attribute name="padding-right">0.5em</xsl:attribute>      
-        <xsl:attribute name="padding-bottom">0.5em</xsl:attribute>      
-        <xsl:attribute name="margin-left">0.5em</xsl:attribute>      
-        <xsl:attribute name="margin-right">0.5em</xsl:attribute>      
-    </xsl:attribute-set>    
-
-    <!-- Shade (background) programlistings -->    
-    <xsl:param name="shade.verbatim">1</xsl:param>
-    <xsl:attribute-set name="shade.verbatim.style">
-        <xsl:attribute name="background-color">#F0F0F0</xsl:attribute>
-    </xsl:attribute-set>
-                    
-<!--###################################################
-                         Callouts
-    ################################################### -->   
-
-    <!-- Use images for callouts instead of (1) (2) (3) -->
-    <xsl:param name="callout.graphics">0</xsl:param>
-    <xsl:param name="callout.unicode">1</xsl:param>
-    
-    <!-- Place callout marks at this column in annotated areas -->
-    <xsl:param name="callout.defaultcolumn">90</xsl:param>
-
-<!--###################################################
-                       Admonitions
-    ################################################### -->   
-
-    <!-- Use nice graphics for admonitions -->
-    <xsl:param name="admon.graphics">'1'</xsl:param>
-    <xsl:param name="admon.graphics.path">&admon_gfx_path;</xsl:param>
-
-<!--###################################################
-                          Misc
-    ################################################### -->   
-
-    <!-- Placement of titles -->
-    <xsl:param name="formal.title.placement">
-        figure after
-        example before
-        equation before
-        table before
-        procedure before
-    </xsl:param>
-    
-    <!-- Format Variable Lists as Blocks (prevents horizontal overflow) -->
-    <xsl:param name="variablelist.as.blocks">1</xsl:param>
-
-    <!-- The horrible list spacing problems -->
-    <xsl:attribute-set name="list.block.spacing">
-        <xsl:attribute name="space-before.optimum">0.8em</xsl:attribute>
-        <xsl:attribute name="space-before.minimum">0.8em</xsl:attribute>
-        <xsl:attribute name="space-before.maximum">0.8em</xsl:attribute>
-        <xsl:attribute name="space-after.optimum">0.1em</xsl:attribute>
-        <xsl:attribute name="space-after.minimum">0.1em</xsl:attribute>
-        <xsl:attribute name="space-after.maximum">0.1em</xsl:attribute>
-    </xsl:attribute-set>
-    
-</xsl:stylesheet>

docs/reference/styles/html.css

@@ -1,168 +0,0 @@
-A {
-    color: #003399;
-}
-
-A:active {
-    color: #003399;
-}
-
-A:visited {
-    color: #888888;
-}
-
-P, DL, DT, DD, BLOCKQUOTE {
-    color: #000000;
-    margin-bottom: 3px;
-    margin-top: 3px;
-    padding-top: 0px;
-    /*border: 1px solid black;*/
-}
-
-OL, UL, P {
-    margin-top: 6px;
-    margin-bottom: 6px;
-}
-
-P, BLOCKQUOTE {
-    font-size: 90%;
-}
-
-P.releaseinfo {
-    font-size: 120%; font-weight: bold; 
-    font-family: Arial, helvetica, sans-serif;
-    padding-top: 10px;
-}
-
-P.pubdate {
-    font-size: 120%; font-weight: bold; 
-    font-family: Arial, helvetica, sans-serif;
-}
-
-td {
-    font-size: 80%;
-}
-
-
-TD, TH, SPAN {
-    color: #000000;
-}
-
-BLOCKQUOTE {
-    margin-right: 0px;
-}
-
-H1, H2, H3, H4, H5, H6    {
-    color: #000000;
-    font-weight:500;
-    margin-top:0px;
-    padding-top:14px;
-    font-family: Arial, helvetica, sans-serif;
-    margin-bottom: 0px;
-}
-
-H2.title {
-    font-weight:800;
-    margin-bottom: 8px;
-}
-
-H2.subtitle {
-    font-weight:800;
-    margin-bottom: 20px;
-}
-
-H3.author {
-    color: #000000;
-    font-weight:500;
-    margin-top:0px;
-    padding-top:0px;
-    font-family: Arial, helvetica, sans-serif;
-    margin-bottom: 0px;
-}
-
-TABLE  {
-    border-collapse: collapse;
-    border-spacing:0;
-    border: 1px thin black;
-    empty-cells: hide;
-}
-
-TD  {
-    padding: 4pt;
-}
-
-H1 { 
-    font-size: 150%; 
-}
-H2 { 
-    font-size: 110%; 
-}
-H3 {
-    font-size: 100%; font-weight: bold; 
-}
-H4 { 
-    font-size: 90%; font-weight: bold;
-}
-H5 {
-    font-size: 90%; font-style: italic; 
-}
-H6 { 
-    font-size: 100%; font-style: italic; 
-}
-
-TT {
-    font-size: 90%;
-    font-family: "Courier New", Courier, monospace;
-    color: #000000;
-}
-
-.navheader, .navfooter {    
-    background-color: #e4eff3;
-}
-
-PRE {
-    font-size: 90%;
-    padding: 5px;
-    border-style: solid;
-    border-width: 1px;
-    border-color: #CCCCCC;
-    background-color: #F4F4F4;
-}
-
-UL, OL, LI {
-    list-style: disc;
-}
-
-HR  {
-    width: 100%;
-    height: 1px;
-    background-color: #CCCCCC;
-    border-width: 0px;
-    padding: 0px;
-    color: #CCCCCC;
-}
-
-.variablelist { 
-    padding-top: 10; 
-    padding-bottom:10; 
-    margin:0;
-}
-
-/*(.itemizedlist, UL { 
-    padding-top: 0; 
-    padding-bottom:0; 
-    margin:0; 
-}*/
-
-.term { 
-    font-weight:bold;
-}
-
-.mediaobject {
-    padding-top: 30px; 
-    padding-bottom: 30px; 
-}
-
-.legalnotice {
-    font-size: 70%;
-}
-    

docs/reference/styles/html.xsl

@@ -1,94 +0,0 @@
-<?xml version="1.0"?>
-
-<!-- 
-
-    This is the XSL HTML configuration file for the Hibernate
-    Reference Documentation. 
-    
-    It took me days to figure out this stuff and fix most of
-    the obvious bugs in the DocBook XSL distribution, so if you
-    use this stylesheet, give some credit back to the Hibernate
-    project.
-    
-    christian.bauer@bluemars.de
--->
-
-<!DOCTYPE xsl:stylesheet [
-    <!ENTITY db_xsl_path        "../lib/docbook-xsl/">
-    <!ENTITY callout_gfx_path   "../images/callouts/">
-    <!ENTITY admon_gfx_path     "../images/admons/">
-]>
-
-<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
-                version="1.0"
-                xmlns="http://www.w3.org/TR/xhtml1/transitional"
-                exclude-result-prefixes="#default">
-                
-<xsl:import href="&db_xsl_path;/html/docbook.xsl"/>
-
-<!--###################################################
-                     HTML Settings
-    ################################################### -->   
-
-    <xsl:param name="html.stylesheet">../styles/html.css</xsl:param>
-
-    <!-- These extensions are required for table printing and other stuff -->
-    <xsl:param name="use.extensions">1</xsl:param>
-    <xsl:param name="tablecolumns.extension">0</xsl:param>
-    <xsl:param name="callout.extensions">1</xsl:param>
-    <xsl:param name="graphicsize.extension">0</xsl:param>
-
-<!--###################################################
-                      Table Of Contents
-    ################################################### -->   
-
-    <!-- Generate the TOCs for named components only -->
-    <xsl:param name="generate.toc">
-        book   toc
-    </xsl:param>
-    
-    <!-- Show only Sections up to level 3 in the TOCs -->
-    <xsl:param name="toc.section.depth">3</xsl:param>
-    
-<!--###################################################
-                         Labels
-    ################################################### -->   
-
-    <!-- Label Chapters and Sections (numbering) -->
-    <xsl:param name="chapter.autolabel">1</xsl:param>
-    <xsl:param name="section.autolabel" select="1"/>
-    <xsl:param name="section.label.includes.component.label" select="1"/>
-        
-<!--###################################################
-                         Callouts
-    ################################################### -->   
-
-    <!-- Use images for callouts instead of (1) (2) (3) -->
-    <xsl:param name="callout.graphics">1</xsl:param>
-    <xsl:param name="callout.graphics.path">&callout_gfx_path;</xsl:param>
-    
-    <!-- Place callout marks at this column in annotated areas -->
-    <xsl:param name="callout.defaultcolumn">90</xsl:param>
-
-<!--###################################################
-                       Admonitions
-    ################################################### -->   
-
-    <!-- Use nice graphics for admonitions -->
-    <xsl:param name="admon.graphics">'1'</xsl:param>
-    <xsl:param name="admon.graphics.path">&admon_gfx_path;</xsl:param>
-
-<!--###################################################
-                          Misc
-    ################################################### -->   
-
-    <!-- Placement of titles -->
-    <xsl:param name="formal.title.placement">
-        figure after
-        example before
-        equation before
-        table before
-        procedure before
-    </xsl:param>    
-    
-</xsl:stylesheet>

docs/reference/styles/html_chunk.xsl

@@ -1,96 +0,0 @@
-<?xml version="1.0"?>
-
-<!-- 
-
-    This is the XSL HTML configuration file for the Hibernate
-    Reference Documentation. 
-    
-    It took me days to figure out this stuff and fix most of
-    the obvious bugs in the DocBook XSL distribution, so if you
-    use this stylesheet, give some credit back to the Hibernate
-    project.
-    
-    christian.bauer@bluemars.de
--->
-
-<!DOCTYPE xsl:stylesheet [
-    <!ENTITY db_xsl_path        "../lib/docbook-xsl/">
-    <!ENTITY callout_gfx_path   "../images/callouts/">
-    <!ENTITY admon_gfx_path     "../images/admons/">
-]>
-
-<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
-                version="1.0"
-                xmlns="http://www.w3.org/TR/xhtml1/transitional"
-                exclude-result-prefixes="#default">
-                
-<xsl:import href="&db_xsl_path;/html/chunk.xsl"/>
-
-<!--###################################################
-                     HTML Settings
-    ################################################### -->   
-
-    <xsl:param name="chunk.section.depth">'5'</xsl:param>
-    <xsl:param name="use.id.as.filename">'1'</xsl:param>
-    <xsl:param name="html.stylesheet">../styles/html.css</xsl:param>
-
-    <!-- These extensions are required for table printing and other stuff -->
-    <xsl:param name="use.extensions">1</xsl:param>
-    <xsl:param name="tablecolumns.extension">0</xsl:param>
-    <xsl:param name="callout.extensions">1</xsl:param>
-    <xsl:param name="graphicsize.extension">0</xsl:param>
-    
-<!--###################################################
-                      Table Of Contents
-    ################################################### -->   
-
-    <!-- Generate the TOCs for named components only -->
-    <xsl:param name="generate.toc">
-        book   toc
-    </xsl:param>
-    
-    <!-- Show only Sections up to level 3 in the TOCs -->
-    <xsl:param name="toc.section.depth">3</xsl:param>
-
-<!--###################################################
-                         Labels
-    ################################################### -->   
-
-    <!-- Label Chapters and Sections (numbering) -->
-    <xsl:param name="chapter.autolabel">1</xsl:param>
-    <xsl:param name="section.autolabel" select="1"/>
-    <xsl:param name="section.label.includes.component.label" select="1"/>
-                
-<!--###################################################
-                         Callouts
-    ################################################### -->   
-
-    <!-- Use images for callouts instead of (1) (2) (3) -->
-    <xsl:param name="callout.graphics">1</xsl:param>
-    <xsl:param name="callout.graphics.path">&callout_gfx_path;</xsl:param>
-    
-    <!-- Place callout marks at this column in annotated areas -->
-    <xsl:param name="callout.defaultcolumn">90</xsl:param>
-
-<!--###################################################
-                       Admonitions
-    ################################################### -->   
-
-    <!-- Use nice graphics for admonitions -->
-    <xsl:param name="admon.graphics">'1'</xsl:param>
-    <xsl:param name="admon.graphics.path">&admon_gfx_path;</xsl:param>
-
-<!--###################################################
-                          Misc
-    ################################################### -->   
-
-    <!-- Placement of titles -->
-    <xsl:param name="formal.title.placement">
-        figure after
-        example before
-        equation before
-        table before
-        procedure before
-    </xsl:param>    
-    
-</xsl:stylesheet>