- 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.
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.
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
- 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
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.
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
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
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.
- 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.
- 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).
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.
- 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.
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.
Problems
- Eliminate — in favor of —
— was causing 'no such entity' errors during docbook
processing; — 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
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.
The docbook-gradle-plugin has been custom-developed specifically to
handle Spring projects. It is highly opinionated, and not terribly
configurable in its current form. Sources and documentation are
available via the 'gradle-plugins' github repository at
https://github.com/cbeams/gradle-plugins
Note that this repository may soon move locations to the SpringSource
GitHub organization, in which case the url will be
https://github.com/SpringSource/gradle-plugins
In any case, the build plans for these plugins can be found at
https://build.springsource.org/browse/GRADLEPLUGINS
This change eliminates the spring-framework-reference subproject, moving
these sources into the root project's own src directory.
This makes sense because the reference docs span all submodules, and
also because api Javadoc is created at the root project level as well.
This means that both api and reference documentation output will now
reside in the root project's 'build' directory. This is more consistent
and easy to discover.
This commit eliminates the 'integration-tests' subproject in favor of
managing these sources under the root project's own 'src' directory.
This helps to avoid special-case handling for integration-tests in the
Gradle build, e.g. avoiding publication of jars to Artifactory /
Maven Central.
It is also semantically more correct. This is not a Spring Framework
subproject so much as it is a collection of integration tests that
span functionality across many subprojects. In this way, it makes
sense to place them directly under the root project.
Issue: SPR-8116
- Use recent Gradle 1.0-milestone-8 snapshot
- Add initial cut of build.gradle able to compile/test all modules
- Update .gitignore
- Generate Gradle wrapper scripts
- Remove all Eclipse metadata files
- Temporarily @Ignore tests that do not pass under Gradle
Previously flash attributes were automatically merged into the
model of annotated controllers only. This change extends the same
benefit to ParameterizableView- and UrlFilenameViewController,
both of which merely select a view without user controller logic
and (the views) would otherwise not have access to the flash
attributes.
When checking for an exact match of Accept header media types
additional parameters such as quality need to be excluded.
For example "*/*" matches "*/*;q=0.9".
- Eliminate trailing whitespace
- Update long method signatures to follow framework whitespace
conventions
Based on the following search,
$ git grep -A3 '^.public .* .*([^\{;]*$' */src/main
the strong convention throughout the framework when dealing with
methods having long signatures (i.e. many parameters) is to break
immediately after the opening paren, indent two tabs deeper and break
lines around 90 characters as necessary. Such signatures should also
be followed by a newline after the opening curly brace to break
things up visually.
The files edited in this commit had a particularly different style of
intenting arguments to align with each other vertically, but the
alignment only worked if one's tabstop is set at four spaces.
When viewed at a different tabstop value, the effect is is jarring,
both in that it is misaligned and significantly different from most
of the framework. The convention described above reads well at any
tabstop value.
Before this change, flash attributes could only be added if via
RedirectAttributes.addFlashAttribute(..) if the method returned
a view name or a View instance. With this change, the above is
supported with a ModelAndView return value as well.
Chris Beams
Arjen Poutsma
Arjen Poutsma
Rossen Stoyanchev
Chris Beams
Juergen Hoeller
Costin Leau