Introduce jdiff Gradle task

The new jdiff task generates a report of API differences between the
current version (i.e. the value of `version` in gradle.properties) and
any older version of the framework, as specified by -DOLD_VERSION at
the command line, or defaulting to `previousVersion` in
gradle.properties.

Running the command requires a separate clone directory pinned to the
desired old version, as specified by -DOLD_VERSION_ROOT at the command
line. This creates challenges from a build automation perspective,
largely because Gradle doesn't (yet) have APIs for working with Git.

This task may be further automated and included in nightly CI runs, but
in the meantime, a number of reports back to 3.1.3.RELEASE have been
generated manually and uploaded to [1], where one can now find the
following entries in the directory listing:

 - 3.1.3.RELEASE_to_3.2.0.RC1
 - 3.2.0.M1_to_3.2.0.M2
 - 3.2.0.M2_to_3.2.0.RC1
 - 3.2.0.RC1_to_3.2.0.BUILD-SNAPSHOT

Ideally, the final entry there would be kept up-to-date on a daily
basis - again we may revisit doing so in the future. Going forward,
reports will be generated and uploaded manually on an as needed basis
and as part of the release process.

The goal of these reports are as follows:

 - to ease the process of ensuring backward compatibility

 - to aid in code reviews, particularly when reviewing large pull
   requests

 - to ease the process of creating migration guides for project
   maintainers, i.e. to help us remember what's changed

 - to allow ambitious end-users to discover what's been changing at the
   API level without without needing to wait for detailed "what's new in
   version X" and/or migration guide documentation

See documentation in jdiff.gradle for usage details.

Note that the jdiff-1.1.1 distribution as downloaded from [2] has been
added wholesale to the source tree under gradle/jdiff instead of
uploading JDiff jars to repo.springsource.org as we would normally do.
This is due to some unfortunate limitations in the implementation of the
jdiff ant task that require a phisical JDIFF_HOME directory. Checking in
the jars and various resources represents the simplest and most
pragmatic solution to this problem, though ambitious contributors are
free to do what's necessary to arrive at a more elegant arrangement.

[1]: http://static.springframework.org/spring-framework/docs
[2]: http://sourceforge.net/projects/javadiff/files/latest/download

Issue: SPR-9957

Author: cbeams

build.gradle

@@ -659,6 +659,7 @@ configure(rootProject) {
     description = 'Spring Framework'
 
     apply plugin: 'docbook-reference'
+    apply from: "${gradleScriptDir}/jdiff.gradle"
 
     reference {
         sourceDir = file('src/reference/docbook')

gradle.properties

@@ -1 +1,2 @@
 version=3.2.0.BUILD-SNAPSHOT
+previousVersion=3.2.0.RC1

gradle/jdiff.gradle

@@ -0,0 +1,74 @@
+/**
+ * Generate a JDiff report between the current version and an older version.
+ *
+ * Usage:
+ *  gradle jdiff [-D OLD_VERSION=3.1.3.RELEASE] -D OLD_VERSION_ROOT=/path/to/3.1.3.RELEASE
+ *
+ * View generated report at:
+ *  build/reports/jdiff/changes.html
+ *
+ * @param OLD_VERSION optional, defaulting to value of `previousVersion` in gradle.properties
+ * @param OLD_VERSION_ROOT required, typically pointing to a separate git clone dir
+ */
+task jdiff {
+    description = 'Generates a JDiff report'
+    group = 'Documentation'
+
+    def jdiffHome = "${rootProject.rootDir}/gradle/jdiff"
+
+    ant.taskdef(
+            name: 'jdiff',
+            classname: 'jdiff.JDiffAntTask',
+            classpath: "${jdiffHome}/antjdiff.jar")
+
+    def previousVersion = rootProject.previousVersion
+
+    def currentVersion = rootProject.version
+    def currentVersionRoot = rootProject.rootDir
+
+    def oldVersion = System.getProperty("OLD_VERSION") ?: previousVersion
+    def oldVersionRoot = System.getProperty("OLD_VERSION_ROOT")
+
+    def outputDir = "${rootProject.buildDir}/reports/jdiff/${oldVersion}_to_${currentVersion}"
+
+    doLast {
+        if (oldVersionRoot == null)
+            throw new IllegalArgumentException(
+                "Set OLD_VERSION_ROOT property to indicate the root directory for ${oldVersion}")
+
+        oldVersionRoot = new File(oldVersionRoot)
+
+        ant.property(name: 'JDIFF_HOME', value: jdiffHome)
+        ant.mkdir(dir: outputDir)
+        ant.jdiff(
+                destdir: outputDir,
+                verbose: 'off',
+                stats: 'on',
+                docchanges: 'on') {
+            old(name: "Spring Framework ${oldVersion}") {
+                oldVersionRoot.eachDirMatch( {
+                        def candidate = new File(it)
+                        candidate.name.matches("org.springframework.*") ||
+                        candidate.name.matches("spring-.*") }) { match ->
+                    match.eachDirRecurse { subdir ->
+                        if (subdir.path ==~ '.*/src/main/java$') {
+                            dirset(dir: subdir.path, includes: 'org/**')
+                        }
+                    }
+                }
+            }
+            'new'(name: "Spring Framework ${currentVersion}") {
+                currentVersionRoot.eachDirMatch( {
+                        def candidate = new File(it)
+                        candidate.name.matches("org.springframework.*") ||
+                        candidate.name.matches("spring-.*") }) { match ->
+                    match.eachDirRecurse { subdir ->
+                        if (subdir.path ==~ '.*/src/main/java$') {
+                            dirset(dir: subdir.path, includes: 'org/**')
+                        }
+                    }
+                }
+            }
+        }
+    }
+}

gradle/jdiff/LICENSE.txt

@@ -0,0 +1,9 @@
+/** 
+ * This class is used only as a "null" argument for Javadoc when comparing
+ * two API files. Javadoc has to have a package, .java or .class file as an 
+ * argument, even though JDiff doesn't use it.
+ */
+public class Null {
+    public Null() {
+    }
+}

gradle/jdiff/Null.java

@@ -0,0 +1,6 @@
+This distribution of JDiff 1.1.1 is included in the Spring Framework build
+because JDiff has a hard requirement on a JDIFF_HOME directory containing
+jdiff.jar and xerces.jar as well as other presentation resources.
+
+The actual generation of JDiff reports is driven by the `jdiff` task declared
+in build.gradle in the project root.

gradle/jdiff/README-SPRING.txt

@@ -0,0 +1,59 @@
+
+                           JDiff Doclet
+                           ------------
+
+                           Matthew Doar
+                          [email protected]
+
+
+The JDiff doclet is used to generate a report describing the
+difference between two public Java APIs. 
+
+The file jdiff.html contains the reference page for JDiff.  The latest
+version of JDiff can be downloaded at:
+http://sourceforge.net/projects/javadiff
+
+To use the Ant task on your own project, see example.xml. More examples
+of using JDiff to compare the public APIs of J2SE1.3 and J2SE1.4 can
+be seen at http://www.jdiff.org
+
+For an example with the source distribution, run "ant" and
+look at the HTML output in ./build/reports/example/changes.html 
+The page at ./build/reports/example/changes/com.acme.sp.SPImpl.html
+shows what a typical page of changes looks like. 
+
+System Requirements
+-------------------
+
+JDiff has been tested with all releases of Java since J2SE1.2 but
+releases of JDiff after 1.10.0 focus on JDK1.5.
+
+License
+-------
+
+JDiff is licensed under the Lesser GNU General Public License (LGPL).
+See the file LICENSE.txt.
+
+Acknowledgements
+----------------
+
+JDiff uses Stuart D. Gathman's Java translation of Gene Myers' O(ND) 
+difference algorithm.
+
+JDiff uses Xerces 1.4.2 from http://www.apache.org.
+
+JDiff also includes a script to use the classdoc application from
+http://classdoc.sourceforge.net or http://www.jensgulden.de, by Jens
+Gulden, ([email protected]), to call a doclet such as jdiff on a .jar
+file rather than on source.
+
+Many thanks to the reviewers at Sun and Vitria who gave feedback on early
+versions of JDiff output, and also to the distillers of Laphroaig, and to
+Arturo Fuente for his consistently fine cigars which helped inspire
+much of this work.
+
+
+Footnote:
+
+If you are looking for a generalized diff tool for XML, try diffmk from
+http://wwws.sun.com/software/xml/developers/diffmk/