You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
213 lines
11 KiB
213 lines
11 KiB
<?xml version="1.0" encoding="UTF-8"?> |
|
<?oxygen RNGSchema="https://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>A 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="https://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="https://www.se-radio.net/transcript-82-organization-large-code-bases-juergen-hoeller" |
|
>transcript</link> and an <link |
|
xlink:href="https://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.59*"/> |
|
<colspec colnum="2" colname="c2" colwidth="0.92*"/> |
|
<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 3.0.0.M1 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>
|
|
|