SEC-2385: Document how to use with Spring 4

build.gradle

@@ -24,6 +24,8 @@ allprojects {
 
     ext.releaseBuild = version.endsWith('RELEASE')
     ext.snapshotBuild = version.endsWith('SNAPSHOT')
+    ext.springVersion = '3.2.4.RELEASE'
+    ext.spring4Version = '4.0.0.BUILD-SNAPSHOT'
 
     group = 'org.springframework.security'
 
@@ -106,7 +108,7 @@ configure(coreModuleProjects) {
     configurations.spring4TestRuntime {
         resolutionStrategy.eachDependency { DependencyResolveDetails details ->
             if (details.requested.group == 'org.springframework') {
-                details.useVersion '4.0.0.RC1'
+                details.useVersion spring4Version
             }
             if (details.requested.name == 'ehcache') {
                 details.useVersion '2.6.5'

docs/docs.gradle

@@ -25,6 +25,8 @@ project('manual') {
               doctype: 'book',
               numbered: '',
               'spring-security-version' : project.version,
+              'spring-version' : springVersion,
+              'spring4-version' : spring4Version,
               revnumber : project.version
           ]
         ]

docs/manual/src/asciidoc/Guardfile

@@ -3,7 +3,7 @@ require 'erb'
 
 guard 'shell' do
   watch(/^.*\.adoc$/) {|m|
-    Asciidoctor.render_file(m[0], :to_dir => "build/", :safe => Asciidoctor::SafeMode::UNSAFE, :attributes=> {'idprefix' => '', 'idseparator' => '-', 'copycss' => '', 'icons' => 'font', 'source-highlighter' => 'prettify', 'sectanchors' => '', 'doctype' => 'book','toc2' => '', 'spring-security-version' => '3.2.0.CI-SNAPSHOT', 'revnumber' => '3.2.0.CI-SNAPSHOT' })
+    Asciidoctor.render_file(m[0], :to_dir => "build/", :safe => Asciidoctor::SafeMode::UNSAFE, :attributes=> {'idprefix' => '', 'idseparator' => '-', 'copycss' => '', 'icons' => 'font', 'source-highlighter' => 'prettify', 'sectanchors' => '', 'doctype' => 'book','toc2' => '', 'spring-security-version' => '3.2.0.CI-SNAPSHOT','spring-version' => '3.2.0.RELEASE','spring4-version' => '4.0.0.RELEASE', 'revnumber' => '3.2.0.CI-SNAPSHOT', 'numbered'=>'' })
   }
 end
 

docs/manual/src/asciidoc/index.adoc

@@ -135,8 +135,165 @@ You should always test your application thoroughly before rolling out a new vers
 
 [[get-spring-security]]
 === Getting Spring Security
-You can get hold of Spring Security in several ways. You can download a packaged distribution from the main Spring http://www.springsource.com/download/community?project=Spring%20Security[download page], download individual jars (and sample WAR files) from the Maven Central repository (or a SpringSource Maven repository for snapshot and milestone releases) or, alternatively, you can build the project from source yourself. See the project web site for more details.
+You can get hold of Spring Security in several ways. You can download a packaged distribution from the main http://spring.io/spring-security[Spring Security] page, download individual jars from the Maven Central repository (or a SpringSource Maven repository for snapshot and milestone releases) or, alternatively, you can build the project from source yourself.
 
+[[maven]]
+==== Usage with Maven
+
+A minimal Spring Security Maven set of dependencies typically looks like the following:
+
+.pom.xml
+[source,xml]
+[subs="verbatim,attributes"]
+----
+<dependencies>
+  <!-- ... other dependency elements ... -->
+  <dependency>
+    <groupId>org.springframework.security</groupId>
+    <artifactId>spring-security-web</artifactId>
+    <version>{spring-security-version}</version>
+  </dependency>
+  <dependency>
+    <groupId>org.springframework.security</groupId>
+    <artifactId>spring-security-config</artifactId>
+    <version>{spring-security-version}</version>
+  </dependency>
+</dependencies>
+----
+
+If you are using additional features like LDAP, OpenID, etc. you will need to also include the appropriate <<modules>>.
+
+[[maven-repositories]]
+===== Maven Repositories
+All GA releases (i.e. versions ending in .RELEASE) are deployed to Maven Central, so no additional Maven repositories need to be declared in your pom.
+
+If you are using a SNAPSHOT version, you will need to ensure you have the Spring Snapshot repository defined as shown below:
+
+.pom.xml
+[source,xml]
+----
+<repositories>
+  <!-- ... possibly other repository elements ... -->
+  <repository>
+    <id>spring-snapshot</id>
+    <name>Spring Snapshot Repository</name>
+    <url>http://repo.springsource.org/snapshot</url>
+  </repository>
+</repositories>
+----
+
+If you are using a milestone or release candidate version, you will need to ensure you have the Spring Milestone repository defined as shown below:
+
+.pom.xml
+[source,xml]
+----
+<repositories>
+  <!-- ... possibly other repository elements ... -->
+  <repository>
+    <id>spring-milestone</id>
+    <name>Spring Milestone Repository</name>
+    <url>http://repo.springsource.org/milestone</url>
+  </repository>
+</repositories>
+----
+
+[[maven-bom]]
+===== Using Spring 4 and Maven
+
+Spring Security builds against Spring Framework {spring-version}, but is also tested against Spring Framework {spring4-version}. This means you can use Spring Security {spring-security-version} with Spring Framework {spring4-version}. The problem that many users will have is that Spring Security's transitive dependencies resolve Spring Framework {spring-version} causing all sorts of strange classpath problems.
+
+One (tedious) way to circumvent this issue would be to include all the Spring Framework modules in a http://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html#Dependency_Management[<dependencyManagement>] section of your pom. An alternative approach is to include the `spring-framework-bom` within your `<dependencyManagement>` section of your `pom.xml` as shown below:
+
+.pom.xml
+[source,xml]
+[subs="verbatim,attributes"]
+----
+<dependencyManagement>
+    <dependencies>
+      <dependency>
+        <groupId>org.springframework</groupId>
+        <artifactId>spring-framework-bom</artifactId>
+        <version>{spring4-version}</version>
+        <type>pom</type>
+        <scope>import</scope>
+      </dependency>
+    </dependencies>
+</dependencyManagement>
+----
+
+This will ensure that all the transitive dependencies of Spring Security use the Spring {spring4-version} modules.
+
+NOTE: This approach uses Maven's "bill of materials" (BOM) concept and is only available in Maven 2.0.9+. For additional details about how dependencies are resolved refer to http://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html[Maven's Introduction to the Dependency Mechanism documentation].
+
+[[gradle]]
+==== Gradle
+A minimal Spring Security Gradle set of dependencies typically looks like the following:
+
+.build.gradle
+[source,groovy]
+[subs="verbatim,attributes"]
+----
+dependencies {
+    compile 'org.springframework.security:spring-security-web:{spring-security-version}'
+    compile 'org.springframework.security:spring-security-config:{spring-security-version}'
+}
+----
+
+If you are using additional features like LDAP, OpenID, etc. you will need to also include the appropriate <<modules>>.
+
+[[gradle-repositories]]
+===== Gradle Repositories
+All GA releases (i.e. versions ending in .RELEASE) are deployed to Maven Central, so using the mavenCentral() repository is sufficient for GA releases.
+
+.build.gradle
+[source,groovy]
+----
+repositories {
+    mavenCentral()
+}
+----
+
+If you are using a SNAPSHOT version, you will need to ensure you have the Spring Snapshot repository defined as shown below:
+
+.build.gradle
+[source,groovy]
+----
+repositories {
+    maven { url 'https://repo.spring.io/snapshot' }
+}
+----
+
+If you are using a milestone or release candidate version, you will need to ensure you have the Spring Milestone repository defined as shown below:
+
+.build.gradle
+[source,groovy]
+----
+repositories {
+    maven { url 'https://repo.spring.io/milestone' }
+}
+----
+
+[[gradle-resolutionStrategy]]
+===== Using Spring 4 and Gradle
+
+By default Gradle will use the newest version when resolving transitive versions. This means that often times no additional work is necessary when running Spring Security {spring-security-version} with Spring Framework {spring4-version}. However, at times there can be issues that come up so it is best to mitigate this using http://www.gradle.org/docs/current/dsl/org.gradle.api.artifacts.ResolutionStrategy.html[Gradle's ResolutionStrategy] as shown below:
+
+.build.gradle
+[source,groovy]
+[subs="verbatim,attributes"]
+----
+ configurations.spring4TestRuntime {
+        resolutionStrategy.eachDependency { DependencyResolveDetails details ->
+            if (details.requested.group == 'org.springframework') {
+                details.useVersion {spring4-version}
+            }
+        }
+    }
+----
+
+This will ensure that all the transitive dependencies of Spring Security use the Spring {spring4-version} modules.
+
+NOTE: This example uses Gradle 1.9, but may need modifications to work in future versions of Gradle since this is an incubating feature within Gradle.
 
 [[modules]]
 ==== Project Modules

gradle/javaprojects.gradle

@@ -11,7 +11,6 @@ apply plugin: 'propdeps-eclipse'
 sourceCompatibility = 1.5
 targetCompatibility = 1.5
 
-ext.springVersion = '3.2.4.RELEASE'
 ext.springLdapVersion = '1.3.2.RELEASE'
 ext.ehcacheVersion = '1.6.2'
 ext.aspectjVersion = '1.6.10'