Why have the packages changed in Spring Security 3.0?
Abstract
A quick introduction to the code modules and package structure of the Spring Security 3.0 codebase.
Table of Contents
In versions prior to 3.0, most of Spring Security's code was contained in the
spring-security-core jar[1]. 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.
Figure 1, “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[2]. 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.[3]. 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.
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.
Table 1. 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-client | 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 Figure 2, “Inter-Jar Dependencies”.
The package layout in 3.0 is show in Figure 3, “Spring Security 3.0.0.M1 Package Structure”. 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.
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.
[1] 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.
[2] Structure101 is an excellent tool for analyzing your own code or for understanding someone else's. It is developed by Headway Software.
[3] 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.