From af2e1c50c36ad70cf57aa1042d9d30cfbc700c8f Mon Sep 17 00:00:00 2001 From: Oliver Gierke Date: Mon, 4 May 2015 14:23:39 +0200 Subject: [PATCH] DATACMNS-687 - Added section on dependency management to reference docs. Added a dedicated dependencies.adoc that outlines the usage of the Spring Data release train BOM as well as the way one would customize the release train to be used with Spring Boot. Also, we now explicitly list the Spring Framework version the release requires. --- src/main/asciidoc/dependencies.adoc | 57 +++++++++++++++++++ src/main/asciidoc/index.adoc | 1 + src/main/asciidoc/preface.adoc | 2 +- ...pository-query-return-types-reference.adoc | 6 +- 4 files changed, 62 insertions(+), 4 deletions(-) create mode 100644 src/main/asciidoc/dependencies.adoc diff --git a/src/main/asciidoc/dependencies.adoc b/src/main/asciidoc/dependencies.adoc new file mode 100644 index 000000000..2fd0a0f88 --- /dev/null +++ b/src/main/asciidoc/dependencies.adoc @@ -0,0 +1,57 @@ +[[dependencies]] += Dependencies + +Due to different inception dates of individual Spring Data modules, most of them carry different major and minor version numbers. The easiest way to find compatible ones is by relying on the Spring Data Release Train BOM we ship with the compatible versions defined. In a Maven project you'd declare this dependency in the `` section of your POM: + +.Using the Spring Data release train BOM +==== +[source, xml] +---- + + + + org.springframework.data + spring-data-releasetrain + ${release-train} + import + pom + + + +---- +==== + +The current release train version is {releasetrainVersion}. The train names are ascending alphabetically and currently available ones are listed https://github.com/spring-projects/spring-data-commons/wiki/Release-planning[here]. The version name follows the following pattern: `${name}-${release}` where release can be one of the following: + +* `BUILD-SNAPSHOT` - current snapshots +* `M1`, `M2` etc. - milestones +* `RC1`, `RC2` etc. - release candidates +* `RELEASE` - GA release +* `SR1`, `SR2` etc. - service releases + +A working example of using the BOMs can be found in our https://github.com/spring-projects/spring-data-examples/tree/master/bom[Spring Data examples repository]. + +If that's in place declare the Spring Data modules you'd like to use without a version in the `` block. + +.Declaring a dependency to a Spring Data module +==== +[source, xml] +---- + + + org.springframework.data + spring-data-jpa + + +---- +==== + +[[dependencies.spring-boot]] +== Dependency management with Spring Boot + +Spring Boot already selects a very recent version of Spring Data modules for you. In case you want to upgrade to a newer version nonetheless, simply configure the property `spring-data-releasetrain.version` to the train name and iteration you'd like to use. + +[[dependencies.spring-framework]] +== Spring Framework + +The current version of Spring Data modules require Spring Framework in version {springVersion} or better. The modules might also work with an older bugfix version of that minor version. However, using the most recent version within that generation is highly recommended. diff --git a/src/main/asciidoc/index.adoc b/src/main/asciidoc/index.adoc index 38adae2ea..29fec7115 100644 --- a/src/main/asciidoc/index.adoc +++ b/src/main/asciidoc/index.adoc @@ -17,6 +17,7 @@ include::preface.adoc[] = Reference documentation :leveloffset: +1 +include::dependencies.adoc[] include::repositories.adoc[] include::auditing.adoc[] :leveloffset: -1 diff --git a/src/main/asciidoc/preface.adoc b/src/main/asciidoc/preface.adoc index 47788ffa0..226ebd440 100644 --- a/src/main/asciidoc/preface.adoc +++ b/src/main/asciidoc/preface.adoc @@ -10,4 +10,4 @@ The Spring Data Commons project applies core Spring concepts to the development * Bugtracker - https://jira.spring.io/browse/DATACMNS * Release repository - https://repo.spring.io/libs-release * Milestone repository - https://repo.spring.io/libs-milestone -* Snapshot repository - https://repo.spring.io/libs-snapshot \ No newline at end of file +* Snapshot repository - https://repo.spring.io/libs-snapshot diff --git a/src/main/asciidoc/repository-query-return-types-reference.adoc b/src/main/asciidoc/repository-query-return-types-reference.adoc index bab910458..e0b135f36 100644 --- a/src/main/asciidoc/repository-query-return-types-reference.adoc +++ b/src/main/asciidoc/repository-query-return-types-reference.adoc @@ -21,9 +21,9 @@ NOTE: Geospatial types like (`GeoResult`, `GeoResults`, `GeoPage`) are only avai |`Optional`|A Java 8 or Guava `Optional`. Expects the query method to return one result at most. In case no result is found `Optional.empty()`/`Optional.absent()` is returned. More than one result will trigger an `IncorrectResultSizeDataAccessException`. |`Stream`|A Java 8 `Stream`. |`Slice`|A sized chunk of data with information whether there is more data available. Requires a `Pageable` method parameter. -|`Page`|A Slice with additional information, e.g. the total number of results. Requires a `Pageable` method parameter. +|`Page`|A `Slice` with additional information, e.g. the total number of results. Requires a `Pageable` method parameter. |`GeoResult`|A result entry with additional information, e.g. distance to a reference location. -|`GeoResults`|A list of GeoResult with additional information, e.g. average distance to a reference location. -|`GeoPage`|A Page with GeoResult, e.g. average distance to a reference location. +|`GeoResults`|A list of `GeoResult` with additional information, e.g. average distance to a reference location. +|`GeoPage`|A `Page` with `GeoResult`, e.g. average distance to a reference location. |===============