diff --git a/docs/articles/src/docbook/codebase-structure.xml b/docs/articles/src/docbook/codebase-structure.xml new file mode 100644 index 0000000000..95635db4bc --- /dev/null +++ b/docs/articles/src/docbook/codebase-structure.xml @@ -0,0 +1,213 @@ + + +
+ + The Spring Security 3.0 Codebase + Why have the packages changed in Spring Security 3.0? + + Luke Taylor + SpringSource + + An quick introduction to the code modules and package structure of the Spring + Security 3.0 codebase. + + + + Introduction + In versions prior to 3.0, most of Spring Security's code was contained in the + spring-security-core jar + There was also an additional spring-security-core-tiger + 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. + . 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 pom.xml are required for a + particular set of features within the framework. + 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. +
+ Spring Security 2.0.4 Package Structure + + + + + +
+ + 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 + Structure101 is an excellent tool for analyzing your own code or for + understanding someone else's. It is developed by Headway Software. + . 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. + For more information on how to structure a large codebase, Juergen Hoeller's + Organization of Large Code Bases 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 transcript and an InfoQ video. + . 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. + Let's take a look at how things are now organised. + + + Spring Security 3.0 + + Project Jars + The first thing we did was split the core out into several jars. The + spring-security-core 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. + Spring Security Jars + + + + + + + + Jar Name + Description + When to use + Root Package(s) + + + + + spring-security-core + Core authentication and access-contol classes and interfaces. + Remoting support and basic provisioning APIs. + Required by any application which uses Spring Security. + Supports standalone applications, remote clients, method + (service layer) security and JDBC user provisioning. + + org.springframework.security.core, + org.springframework.security.access, + org.springframework.security.authentication, + org.springframework.security.provisioning, + org.springframework.security.remoting + + + + spring-security-web + Filters and other web-security infrastructure and related + code. Anything with a servlet API dependency. + If you require Spring Security web authentication services + and URL-based access-control + org.springframework.security.web + + + spring-security-config + Namespace parsing code. + If you are using the Spring Security XML namespace. + org.springframework.security.config + + + spring-security-ldap + LDAP authentication and provisioning code. + If you need to use LDAP authentication or manage LDAP user + entries. + org.springframework.security.ldap + + + spring-security-acl + Domain object ACL implementation. + If you need to apply security to specific domain object + instances within your application. + org.springframework.security.acls + + + spring-security-cas + Spring Security's CAS client integration. + If you want to use Spring Security web authentication with a + CAS single sign-on server. + org.springframework.security.cas + + + spring-security-openid + OpenID web authentication support. + If you need to authenticate users against an external OpenID + server. + org.springframework.security.openid + + + +
+ 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 .
+ Inter-Jar Dependencies + + + + + +
+ + + Package Structure + The package layout in 3.0 is show in . As you can + see, there are no longer any circular references and the structure is much clearer. + The core 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 authentication and + access. The access package containst + access-control/authorization code such as the + AccessDecisionManager 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 + authentication package contains the + AuthenticationManager and related classes (such + as authentication exception classes), the simple DAO-based authentication provider + and password-encoders.
+ Spring Security 2.0.4 Package Structure + + + + + +
+ + + + How will these changes affect you? + 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 + Ctrl-Shift-Tor Ctrl-Shift-O in Eclipse can do + wonders). + 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. + We hope you enjoy using Spring Security 3.0. + +
diff --git a/docs/articles/src/docbook/images/spring-security-2.0.4.png b/docs/articles/src/docbook/images/spring-security-2.0.4.png new file mode 100644 index 0000000000..b593384e4d Binary files /dev/null and b/docs/articles/src/docbook/images/spring-security-2.0.4.png differ diff --git a/docs/articles/src/docbook/images/spring-security-3.0.0.M1.png b/docs/articles/src/docbook/images/spring-security-3.0.0.M1.png new file mode 100644 index 0000000000..10664ed10e Binary files /dev/null and b/docs/articles/src/docbook/images/spring-security-3.0.0.M1.png differ diff --git a/docs/articles/src/docbook/images/spring-security-3.0.0.M2-jars.png b/docs/articles/src/docbook/images/spring-security-3.0.0.M2-jars.png new file mode 100644 index 0000000000..1fd92a08e6 Binary files /dev/null and b/docs/articles/src/docbook/images/spring-security-3.0.0.M2-jars.png differ