Remove <emphasis> to work around DocBook bug

It was determined (through painful trial and error) that after the
upgrade to DocBook 5 and the gradle-docbook-reference plugin, that
<emphasis> elements embedded within <programlisting> elements causes
NullPointerExceptions during processing.

This change eliminates these <emphasis> elements to work around the
problem. This means a slight degradation in presentation for the
affected areas of the reference documentation. After some research,
it is not clear what other workarounds may be possible that leave
the text actually emphasized.
Fix minor problems and polish reference docs

Problems

 - Eliminate &mdash; in favor of &#151;

   &mdash; was causing 'no such entity' errors during docbook
   processing; &#151; produces the equivalent output.

 - Fix column issues in appendices

   column counts were set to 3, when they are in fact 4. This passed
   under DocBook 4 and Spring Build for unknown reasons, but caused a
   hard stop under DocBook 5 and the docbook-reference-plugin.

 - Add jdbc callout section in docbook 5-friendly style

   use <co/> tags as advertised in DocBook documentation.

 - Set correct widths for PDF ref doc images

   images were rendering larger than the PDF page; just set all to
   width=400 and everything looks good.

Polish

 - Update reference doc copyright to 2012

 - Remove "work-in-progress" language from ref docs

 - Update maven URLs to repo.springsource.org

 - Update javadoc urls from 3.0.x/javadoc-api => current/api

 - Replace hardcoded "3.1" with ${version} in ref doc
Centralize license, notice, etc in src/dist

Prior to this change, license.txt and notice.txt files were duplicated
across every subproject in their respective src/main/resources/META-INF
directories.

This commit centralizes these files under the root project at src/dist,
along with the changelog and readme files. The definition of the 'jar'
task has been been extended to include the license and notice files in
module jars as they are created.

The directory is named src/dist because these files are all related to
distribution - the readme is different than the one you see at the root
of the source tree - the intended audience is for users who download
the spring-framework distribution zip. A task to create that
distribution zip will be added in subsequent commits.
Generate -docs, -schema and -dist zips

 - Add 'api' gradle task to generate project-wide API Javadoc

   results in <root>/build/api

 - Add docsZip task including api and reference documentation

   suitable for publication to
   http://static.springframework.org/docs/spring-framework

 - Add schemaZip task including all spring-* XSD files

   suitable for publication to http://static.springframework.org/schema

 - Add distZip task to include all libs, docs and schema

   - filter src/dist/*.txt for ${copyright} and ${version}
   - copy legal (notice, license) dynamically into individual jar files
   - copy legal and readme files into root of distribution zip

 - Refactor location of 'wrapper' task

Each of the zip tasks (docsZip, schemaZip, distZip) have been added to
the 'archives' configuration, meaning that (a) they will be built
automatically with `gradle build` and (b) will be published
automatically to artifactory when using the Artifactory Gradle plugin
and/or Artifactory Bamboo integration.
Generate -sources and -javadoc jars

Each spring-* subproject now has sourcesJar and javadocJar tasks

 - Ignore subproject overview.html files for now (not all have one)
 - Ensure @author attribution occurs
 - Javadoc 'header' is project description

spring-asm is a special case

 - source jar is created, but empty (to comply with entry rules for
   Maven Central)

 - add package-info.java explaining the nature of spring-asm
   this is nice, because it shows up in the public API docs now.

 - add SpringAsmInfo in the org.springframework.asm package as a
   placeholder allowing the generation of javadocs (see link to bug)

 - add explicit 'repackageAsm' Gradle task allowing for easy testing
   and merging of jar containing bundlor manifest as well as jar
   containing repackaged ASM classes.
Generate spring-oxm test classes and bindings

 - Generate castor test classes with genCastor task
 - Generate xmlbeans test classes with genXmlbeans task
 - Generate JAXB2 test classes with genJaxb task
 - Generate JiBX bindings by extending existing compileTestJava task

Test classes are written into their own dedicated output folders and
tied into the spring-oxm classpath using the files(...).builtBy(...)
directive.

Incremental build works as expected across all of these customizations.

`gradle eclipse` and `gradle idea` generate correct .project / .iml
metadata respectively, i.e., these special cases do not cause a problem
in the IDE (as they used to prior to the move to Gradle).
Generate OSGi manifests using bundlor-plugin

 - Apply custom-built Gradle 'bundlor' plugin

   This plugin wraps the existing bundlor ant task. Sources available
   at https://github.com/SpringSource/gradle-plugins.

 - Use existing template.mf files

   The bundlor plugin allows for 'inlining' bundlor templates directly
   within build.gradle using the 'importTemplate' property, but opting
   for now to keep the template.mf files separate.

 - Exclude spring-aspects from bundlor processing

   It appears that the bundlor plugin somehow interferes with iajc
   compilation of aspects, resulting in compiler errors. Bundlor
   has been disabled for this project for the time being.

 - Fail the build on any bundlor warning

   The gradle bundlor plugin defaults to failing the build if there are
   any warnings when processing template.mf files. This helps to ensure
   that template.mf files don't drift too far from actual dependency
   declarations. This behavior can be modified by setting

      bundlor {
          failOnWarnings = false
      }

   in the build script.
Remove EBR dependencies where possible

Only a select few EBR dependencies now remain, because these
dependencies cannot be found elsewhere e.g. atinject-tck, or in the case
of Hibernate 3.3.1.GA, to avoid Gradle classpath confusion with
Hibernate 4.0.x (because they have different artifactIds).

Future efforts will be made to fully eliminate these dependencies in
order to ensure we're decoupled completely from EBR.

Important note: these remaining EBR dependencies do not constitute a
problem when publishing artifacts into Maven Central via
oss.sonatype.org, because they are each 'optional' dependencies. It
appears that OSO's restriction around transitive dependencies being
'self-contained' within Maven Central only applies to mandatory
dependencies (which is a good thing for cases just such as this).

Add explicit /ebr-maven-external entry to repositories, as EBR
dependencies are not available via /libs-release.
Remove spring-build and friends
Remove manually-maintained Maven poms

This is in favor of Gradle-generated poms (a la `gradle install`)
Generate Maven Central-compatible poms

Understanding Gradle pom generation
-------------------------------------------

All spring-* subprojects have had Gradle's 'maven' plugin applied to
them. This means that one can run `gradle install`, and POMs will be
generated according to the metadata in the build.gradle file.

The 'customizePom' routine added by this commit hooks into this
generation process in order to add elements to the pom required for
entry into Maven Central via oss.sonatype.org[1].

This pom generation happens on-the-fly during `gradle install` and
the generated poms exist only in your local .m2 cache. Therefore,
you will not see the poms on the source tree after this command.

Handling optional and provided dependencies
-------------------------------------------

Note particularly the handling of 'optional' and 'provided'
dependencies. Gradle does not have a first class notion for these
concepts, nor are they significant to the actual Gradle build process,
but they are important when publishing POMs for consumption via Maven
Central and other Maven-compatible repositories.

<optional>true</optional> indicates that a dependency need not be
downloaded when resolving artifacts. e.g. spring-context has an
compile-time dependency on cglib, but when a Spring user resolves
spring-context from Maven Central, cglib should *not* automatically
be downloaded at the same time. This is because the core functionality
within spring-context can operate just fine without cglib on the
classpath; it is only if the user chooses explicitly to use certain
functionality, e.g. @Configuration classes, which do require cglib,
that the user must declare an explicit dependency in their own build
script on cglib.

Marking these kinds of dependencies as 'optional' provides a kind of
built in 'documentation' about which version of cglib the user should
declare if in fact he wishes to.

Spring has a great many compile-time dependencies, but in fact very
few mandatory runtime dependencies. Therefore, *most* of Spring's
dependencies are optional.

<scope>provided</scope> is similar to 'optional', in that dependencies
so marked should not be automatically downloaded during dependency
resolution, but indicates rather that they are expected to have been
provided by the user application runtime environment. For example, the
Servlet API is in fact a required runtime dependency for spring-webmvc,
but it is expected that it will be available via the user's servlet
container classpath. Again, it serves here as a kind of 'documentation'
that spring-webmvc does in fact expect the servlet api to be available,
and furthermore which (minimum) version.

This commit adds two closures named 'optional' and 'provided' as well as
two arrays (optionalDeps, providedDeps) for tracking which dependencies
are optional or provided. An optional dependency is declared as follows:

    compile("group:artifact:version", optional)

Here, the optional closure accepts the dependency argument implicitly,
and appends it to the 'optionalDeps' array. Then, during pom generation
(again, the customizePom routine), these arrays are interrogated, and
pom <dependency> elements are updated with <optional>true</optional> or
<scope>provided</scope> as appropriate. Thanks to the Spock framework
for inspiration on this approach[2].

[1] http://bit.ly/wauOqP (Sonatype's central sync requirements)
[2] https://github.com/spockframework/spock/blob/groovy-1.7/gradle/publishMaven.gradle#L63
Rename modules {org.springframework.*=>spring-*}

This renaming more intuitively expresses the relationship between
subprojects and the JAR artifacts they produce.

Tracking history across these renames is possible, but it requires
use of the --follow flag to `git log`, for example

    $ git log spring-aop/src/main/java/org/springframework/aop/Advisor.java

will show history up until the renaming event, where

    $ git log --follow spring-aop/src/main/java/org/springframework/aop/Advisor.java

will show history for all changes to the file, before and after the
renaming.

See http://chrisbeams.com/git-diff-across-renamed-directories
Remove bundlor support
Add Implementation-Version entry to MANIFEST.MF

e.g.:

    Implementation-Title: spring-core
    Implementation-Version: 3.2.0.BUILD-SNAPSHOT

Setting these values is good as a general practice, but required in
order to support the functionality in spring-core's SpringVersion class.
Fix and refactor spring-aspects build

 - Fix compileTestJava issue in which test classes were not being
   compiled or run

 - Use built-in eclipse.project DSL instead of withXml closure
   to add AspectJ nature and builder

 - Rename {aspectJ=>aspects}.gradle and format source
Mark remaining @Ignored tests with 'TODO SPR-8116'

Each of these tests began failing during the Gradle build porting
process. None seem severe, many are likely due to classpath issues.

In the case of TestNG support, this needs to be added to the Gradle
build in order to execute these tests. See SPR-8116.txt
Remove remaining static Eclipse/IDEA metadata

Eclipse .project, .classpath, and .settings metadata have already been
removed. Now removing Eclipse .psf and formatter XML files from the root
project as well as removing all manually-maintained IDEA .iml and .ipr
files.

This is in favor of using Gradle's own 'eclipse' and 'idea' tasks that
generate this kind of metadata on the fly.

.gitignore has been updated to ignore these files going forward. In any
case, they should not be checked into the source tree! The README.md
file will be updated to explain how to generate these files using gradle
and how to import the projects into your IDE of choice.
Update README and add IDE import helper scripts

 - Update building from source section with Gradle instructions
 - Add import-into-eclipse.sh interactive helper script
 - Add import-into-idea.md with steps and known issues

Note that use of STS Gradle tooling was attempted, but several issues
remain before it can handle the spring-framework build. In the meantime
the instructions laid out in import-into-eclipse provide an error-free
import.
Ignore Gradle-related files and directories

When switching back to 3.1.x from master, ignore renamed directories,
Gradle 'build' dirs, generated IDE metadata, etc.

You may wish to clean these files with

    $ git clean -dfx

Or do a dry-run beforehand with the '-n' flag:

    $ git clean -dfxn
Add <license> section to 3.1.x Maven poms

Issue: SPR-8927