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

<?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-control 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. (Deprecated)</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 contains
				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>