spring-security/docs/articles/src/docbook/codebase-structure.xml

<?xml version="1.0" encoding="UTF-8"?>
<?oxygen RNGSchema="http://www.oasis-open.org/docbook/xml/5.0/rng/docbook.rng" type="xml"?>
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
    version="5.0">
    <info>
        <title>The Spring Security 3.0 Codebase</title>
        <subtitle>Why have the packages changed in Spring Security 3.0?</subtitle>
        <author>
            <personname>Luke Taylor</personname>
            <affiliation><orgname>SpringSource</orgname></affiliation></author>
        <abstract>
            <para>An quick introduction to the code modules and package structure of the Spring
                Security 3.0 codebase.</para>
        </abstract>
    </info>
    <sect1>
        <title>Introduction</title>
        <para>In versions prior to 3.0, most of Spring Security's code was contained in the
                <filename>spring-security-core</filename> jar<footnote>
                <para>There was also an additional <filename>spring-security-core-tiger</filename>
                    jar which contained the Java 5 specific code. In Spring Security 3.0 Java 5 is
                    the minimum supported platform, so this code is now part of the core.</para>
            </footnote>. Over the years, as more features have been added, it has become more
            difficult to track the dependencies both within the codebase itself and also on third
            party libraries. For example, it's hard for a user to determine which of the listed
            dependencies in the core Maven <filename>pom.xml</filename> are required for a
            particular set of features within the framework.</para>
        <para>In addition, the original package structure and class names have been around since the
            framework's origins as Acegi Security in 2004, when only a few basic authentication
            mechanisms were supported. As the amount of code has increased and the feature set has
            expanded, this package structure has begun to show its age.</para>
        <figure xml:id="structure-2.0.4">
            <title>Spring Security 2.0.4 Package Structure</title>
            <mediaobject>
                <imageobject>
                    <imagedata fileref="images/spring-security-2.0.4.png" scale="80" align="center"
                    />
                </imageobject>
            </mediaobject>
        </figure>
        <para>
            <xref linkend="structure-2.0.4"/> shows the high-level package diagram of the core,
            core-tiger, cas-client and acl jars in the 2.0.4 release, as produced by the
            Structure101 tool<footnote>
                <para>Structure101 is an excellent tool for analyzing your own code or for
                    understanding someone else's. It is developed by <link
                        xlink:href="http://www.headwaysoftware.com">Headway Software</link>. </para>
            </footnote>. You don't have to be an expert in code structure to realise that there is a
            bit of a problem here. There are a lot of circular references and no clear overall
            dependency structure within the packages. There are also some issues with packages being
            split across jar boundaries, which can cause problems with OSGi, for example.<footnote>
                <para>For more information on how to structure a large codebase, Juergen Hoeller's
                        <quote>Organization of Large Code Bases</quote> is an excellent overview of
                    the topic where he shares some of the insights gained from maintaining the
                    Spring Framework through multiple versions. You can find him discussing the
                    topic in an online interview <link
                        xlink:href="http://www.se-radio.net/transcript-82-organization-large-code-bases-juergen-hoeller"
                        >transcript</link> and an <link
                        xlink:href="http://www.infoq.com/presentations/code-organization-large-projects"
                        >InfoQ video</link>. </para>
            </footnote>. This fragility in the code structure would likely have caused a maintenance
            overhead as Spring Security evolved, so the decision was made to restructure the code
            for the 3.0 release to give us a stable base for future development. </para>
        <para>Let's take a look at how things are now organised.</para>
    </sect1>
    <sect1>
        <title>Spring Security 3.0</title>
        <sect2>
            <title>Project Jars</title>
            <para>The first thing we did was split the core out into several jars. The
                    <filename>spring-security-core</filename> jar now contains only basic
                authentication and access-control code and is much cleaner. It has no dependencies
                on LDAP or the servlet API, for example, and there are now separate jars for
                web-specific code and for LDAP. We've also split out the namespace parsing code out
                int a separate jar, as it depends on most of the other jars and doesn't expose any
                public APIs that you are likely to use directly in your application. You only need
                to use it if you are using Spring Security namespace configuration in your
                application context XML files. The main project jars are shown in the following
                    table.<table xml:id="jar-files-3.0">
                    <title>Spring Security Jars</title>
                    <tgroup cols="3" align="left">
                        <colspec colnum="1" colname="c1" colwidth="0.6*"/>
                        <colspec colnum="2" colname="c2" colwidth="0.9*"/>
                        <colspec colnum="3" colname="c3" colwidth="0.88*"/>
                        <colspec colnum="4" colname="c4" colwidth="1.61*"/>
                        <thead>
                            <row>
                                <entry align="center">Jar Name</entry>
                                <entry align="center">Description</entry>
                                <entry align="center">When to use</entry>
                                <entry align="center">Root Package(s)</entry>
                            </row>
                        </thead>
                        <tbody>
                            <row>
                                <entry valign="middle">spring-security-core</entry>
                                <entry>Core authentication and access-contol classes and interfaces.
                                    Remoting support and basic provisioning APIs.</entry>
                                <entry>Required by any application which uses Spring Security.
                                    Supports standalone applications, remote clients, method
                                    (service layer) security and JDBC user provisioning.</entry>
                                <entry>
                                    <literal>org.springframework.security.core</literal>,
                                        <literal>org.springframework.security.access</literal>,
                                        <literal>org.springframework.security.authentication</literal>,
                                        <literal>org.springframework.security.provisioning</literal>,
                                        <literal>org.springframework.security.remoting</literal>
                                </entry>
                            </row>
                            <row>
                                <entry valign="middle">spring-security-web</entry>
                                <entry>Filters and other web-security infrastructure and related
                                    code. Anything with a servlet API dependency.</entry>
                                <entry>If you require Spring Security web authentication services
                                    and URL-based access-control</entry>
                                <entry><literal>org.springframework.security.web</literal></entry>
                            </row>
                            <row>
                                <entry valign="middle">spring-security-config</entry>
                                <entry>Namespace parsing code.</entry>
                                <entry>If you are using the Spring Security XML namespace.</entry>
                                <entry><literal>org.springframework.security.config</literal></entry>
                            </row>
                            <row>
                                <entry valign="middle">spring-security-ldap</entry>
                                <entry>LDAP authentication and provisioning code.</entry>
                                <entry>If you need to use LDAP authentication or manage LDAP user
                                    entries.</entry>
                                <entry><literal>org.springframework.security.ldap</literal></entry>
                            </row>
                            <row>
                                <entry valign="middle">spring-security-acl</entry>
                                <entry>Domain object ACL implementation.</entry>
                                <entry>If you need to apply security to specific domain object
                                    instances within your application.</entry>
                                <entry><literal>org.springframework.security.acls</literal></entry>
                            </row>
                            <row>
                                <entry valign="middle">spring-security-cas-client</entry>
                                <entry>Spring Security's CAS client integration.</entry>
                                <entry>If you want to use Spring Security web authentication with a
                                    CAS single sign-on server.</entry>
                                <entry><literal>org.springframework.security.cas</literal></entry>
                            </row>
                            <row>
                                <entry valign="middle">spring-security-openid</entry>
                                <entry>OpenID web authentication support.</entry>
                                <entry>If you need to authenticate users against an external OpenID
                                    server.</entry>
                                <entry><literal>org.springframework.security.openid</literal></entry>
                            </row>
                        </tbody>
                    </tgroup>
                </table></para>
            <para>There is now a clearer separation of concerns at the jar level. For example, you
                only need the web jar (and its transitive dependencies) if you are writing a web
                application. This also makes the code easier to navigate and understand. The
                dependencies between the 3.0 jars which now make up the same code set of code we
                looked at for version 2.0.4 are shown in <xref linkend="jar-deps-3.0"/>. <figure
                    xml:id="jar-deps-3.0">
                    <title>Inter-Jar Dependencies</title>
                    <mediaobject>
                        <imageobject>
                            <imagedata fileref="images/spring-security-3.0.0.M2-jars.png"
                                align="center"/>
                        </imageobject>
                    </mediaobject>
                </figure></para>
        </sect2>
        <sect2>
            <title>Package Structure</title>
            <para>The package layout in 3.0 is show in <xref linkend="structure-3.0"/>. As you can
                see, there are no longer any circular references and the structure is much clearer.
                The <filename>core</filename> package and sub packages contain the basic classes and
                interfaces which are used throughout the framework and the other two main packages
                within the core jar are <filename>authentication</filename> and
                    <filename>access</filename>. The <filename>access</filename> package containst
                access-control/authorization code such as the
                    <interfacename>AccessDecisionManager</interfacename> and related voter-based
                implementations, the interception and method security infrastructure, annotation
                classes and support for Spring Security 3.0's expression-based access control. The
                    <filename>authentication</filename> package contains the
                    <interfacename>AuthenticationManager</interfacename> and related classes (such
                as authentication exception classes), the simple DAO-based authentication provider
                and password-encoders. <figure xml:id="structure-3.0">
                    <title>Spring Security 2.0.4 Package Structure</title>
                    <mediaobject>
                        <imageobject>
                            <imagedata fileref="images/spring-security-3.0.0.M1.png" align="center"
                            />
                        </imageobject>
                    </mediaobject>
                </figure></para>
        </sect2>
    </sect1>
    <sect1>
        <title>How will these changes affect you?</title>
        <para>If you are developing a new application then obviously you won't be affected, other
            than by starting out with new package names. But what if you are upgrading an existing
            application or another framework to use Spring Security 3.0. The first thing is that you
            will obviously need to update build paths and dependency lists to take account of the
            new jar modules, but the divisions there are straightforward (see the table above). How
            much the package restructuring will affect you will depend on how much you use the
            framework classes directly or in explicit bean configurations (if you are only using the
            namespace for configuration then it will hide the changes from you). Your IDE should be
            able to help with changing imports and finding out where classes have moved to (a simple
                <command>Ctrl-Shift-T</command>or <command>Ctrl-Shift-O</command> in Eclipse can do
            wonders).</para>
        <para>There are other changes in 3.0 that will affect some users who want to upgrade but for
            the most part, the underlying architecture is unchanged.</para>
        <para>We hope you enjoy using Spring Security 3.0.</para>
    </sect1>
</article>