From ab1b39cd79eb4750cd0e44eebec80c9ed8aa8ac4 Mon Sep 17 00:00:00 2001 From: Christoph Strobl Date: Tue, 10 Mar 2015 09:42:11 +0100 Subject: [PATCH 1/2] DATAMONGO-1179 - Update reference documentation. Prepare issue branch. --- pom.xml | 2 +- spring-data-mongodb-cross-store/pom.xml | 4 ++-- spring-data-mongodb-distribution/pom.xml | 2 +- spring-data-mongodb-log4j/pom.xml | 2 +- spring-data-mongodb/pom.xml | 2 +- 5 files changed, 6 insertions(+), 6 deletions(-) diff --git a/pom.xml b/pom.xml index 5cda32baa9..50e2be3f00 100644 --- a/pom.xml +++ b/pom.xml @@ -5,7 +5,7 @@ org.springframework.data spring-data-mongodb-parent - 1.7.0.BUILD-SNAPSHOT + 1.7.0.DATAMONGO-1179-SNAPSHOT pom Spring Data MongoDB diff --git a/spring-data-mongodb-cross-store/pom.xml b/spring-data-mongodb-cross-store/pom.xml index c7610beee4..b3b6c8be27 100644 --- a/spring-data-mongodb-cross-store/pom.xml +++ b/spring-data-mongodb-cross-store/pom.xml @@ -6,7 +6,7 @@ org.springframework.data spring-data-mongodb-parent - 1.7.0.BUILD-SNAPSHOT + 1.7.0.DATAMONGO-1179-SNAPSHOT ../pom.xml @@ -48,7 +48,7 @@ org.springframework.data spring-data-mongodb - 1.7.0.BUILD-SNAPSHOT + 1.7.0.DATAMONGO-1179-SNAPSHOT diff --git a/spring-data-mongodb-distribution/pom.xml b/spring-data-mongodb-distribution/pom.xml index 13110137b6..2c143ca011 100644 --- a/spring-data-mongodb-distribution/pom.xml +++ b/spring-data-mongodb-distribution/pom.xml @@ -13,7 +13,7 @@ org.springframework.data spring-data-mongodb-parent - 1.7.0.BUILD-SNAPSHOT + 1.7.0.DATAMONGO-1179-SNAPSHOT ../pom.xml diff --git a/spring-data-mongodb-log4j/pom.xml b/spring-data-mongodb-log4j/pom.xml index 6ff09e4577..bc5ab37acd 100644 --- a/spring-data-mongodb-log4j/pom.xml +++ b/spring-data-mongodb-log4j/pom.xml @@ -5,7 +5,7 @@ org.springframework.data spring-data-mongodb-parent - 1.7.0.BUILD-SNAPSHOT + 1.7.0.DATAMONGO-1179-SNAPSHOT ../pom.xml diff --git a/spring-data-mongodb/pom.xml b/spring-data-mongodb/pom.xml index 7c2d818c42..61de15b43e 100644 --- a/spring-data-mongodb/pom.xml +++ b/spring-data-mongodb/pom.xml @@ -11,7 +11,7 @@ org.springframework.data spring-data-mongodb-parent - 1.7.0.BUILD-SNAPSHOT + 1.7.0.DATAMONGO-1179-SNAPSHOT ../pom.xml From 292847bd051b378c5f9f3e50cb267db676cb28d7 Mon Sep 17 00:00:00 2001 From: Christoph Strobl Date: Tue, 10 Mar 2015 10:27:06 +0100 Subject: [PATCH 2/2] DATAMONGO-1179 - Update reference documentation. Added new-features section. Update links and requirements. Add section for GeoJSON support. Update Script Operations section. Add return type Stream to repositories section. Update keyword list. --- src/main/asciidoc/index.adoc | 1 + src/main/asciidoc/new-features.adoc | 15 +++ src/main/asciidoc/preface.adoc | 8 +- .../reference/mongo-repositories.adoc | 32 ++++- src/main/asciidoc/reference/mongodb.adoc | 112 ++++++++++++++++-- 5 files changed, 150 insertions(+), 18 deletions(-) create mode 100644 src/main/asciidoc/new-features.adoc diff --git a/src/main/asciidoc/index.adoc b/src/main/asciidoc/index.adoc index f52b3eac54..daee9a287a 100644 --- a/src/main/asciidoc/index.adoc +++ b/src/main/asciidoc/index.adoc @@ -15,6 +15,7 @@ toc::[] include::preface.adoc[] :leveloffset: +1 +include::new-features.adoc[] include::{spring-data-commons-docs}/repositories.adoc[] :leveloffset: -1 diff --git a/src/main/asciidoc/new-features.adoc b/src/main/asciidoc/new-features.adoc new file mode 100644 index 0000000000..c4841d51a2 --- /dev/null +++ b/src/main/asciidoc/new-features.adoc @@ -0,0 +1,15 @@ +[[new-features]] += New Features + +[[new-in-1-7-0]] +== New in Spring Data MongoDB 1.7 + +* Assert compatibility with MongoDB 3.0 and MongoDB Java Driver 3-beta3 (see: <>). +* Support JSR-310 and ThreeTen back-port date/time types. +* Allow `Stream` as query method return type (see: <>). +* Added http://geojson.org/[GeoJSON] support in both domain types and queries (see: <>). +* `QueryDslPredicateExcecutor` now supports `findAll(OrderSpecifier... orders)`. +* Support calling JavaScript functions via <>. +* Improve support for `CONTAINS` keyword on collection like properties. +* Add `$bit`, `$mul` and `$position` operators to `Update`. + diff --git a/src/main/asciidoc/preface.adoc b/src/main/asciidoc/preface.adoc index 7002954f9b..5b45e68556 100644 --- a/src/main/asciidoc/preface.adoc +++ b/src/main/asciidoc/preface.adoc @@ -30,9 +30,9 @@ The jumping off ground for learning about MongoDB is http://www.mongodb.org/[www [[requirements]] == Requirements -Spring Data MongoDB 1.x binaries requires JDK level 6.0 and above, and http://spring.io/docs[Spring Framework] 3.2.x and above. +Spring Data MongoDB 1.x binaries requires JDK level 6.0 and above, and http://spring.io/docs[Spring Framework] 4.0.x and above. -In terms of document stores, http://www.mongodb.org/[MongoDB] at least 2.4, preferably version 2.6. +In terms of document stores, http://www.mongodb.org/[MongoDB] at least 2.6. == Additional Help Resources @@ -46,12 +46,12 @@ There are a few support options available: [[get-started:help:community]] ==== Community Forum -Spring Data on Stackoverflow http://stackoverflow.com/questions/tagged/spring-data[Stackoverflow ] is a tag for all Spring Data (not just Document) users to share information and help each other. Note that registration is needed *only* for posting. +Spring Data on Stackoverflow http://stackoverflow.com/questions/tagged/spring-data[Stackoverflow] is a tag for all Spring Data (not just Document) users to share information and help each other. Note that registration is needed *only* for posting. [[get-started:help:professional]] ==== Professional Support -Professional, from-the-source support, with guaranteed response time, is available from http://gopivotal.com/[Pivotal Sofware, Inc.], the company behind Spring Data and Spring. +Professional, from-the-source support, with guaranteed response time, is available from http://pivotal.io/[Pivotal Sofware, Inc.], the company behind Spring Data and Spring. [[get-started:up-to-date]] === Following Development diff --git a/src/main/asciidoc/reference/mongo-repositories.adoc b/src/main/asciidoc/reference/mongo-repositories.adoc index 6f334624b5..5ee9f88870 100644 --- a/src/main/asciidoc/reference/mongo-repositories.adoc +++ b/src/main/asciidoc/reference/mongo-repositories.adoc @@ -134,16 +134,22 @@ Most of the data access operations you usually trigger on a repository result a ---- public interface PersonRepository extends PagingAndSortingRepository { - List findByLastname(String lastname); + List findByLastname(String lastname); <1> - Page findByFirstname(String firstname, Pageable pageable); + Page findByFirstname(String firstname, Pageable pageable); <2> - Person findByShippingAddresses(Address address); + Person findByShippingAddresses(Address address); <3> + + Stream findAllBy(); <4> } ---- +<1> The method shows a query for all people with the given lastname. The query will be derived parsing the method name for constraints which can be concatenated with `And` and `Or`. Thus the method name will result in a query expression of `{"lastname" : lastname}`. +<2> Applies pagination to a query. Just equip your method signature with a `Pageable` parameter and let the method return a `Page` instance and we will automatically page the query accordingly. +<3> Shows that you can query based on properties which are not a primitive type. +<4> Uses a Java 8 `Stream` which reads and converts individual elements while iterating the stream. ==== -The first method shows a query for all people with the given lastname. The query will be derived parsing the method name for constraints which can be concatenated with `And` and `Or`. Thus the method name will result in a query expression of`{"lastname" : lastname}`. The second example shows how pagination is applied to a query. Just equip your method signature with a `Pageable` parameter and let the method return a `Page` instance and we will automatically page the query accordingly. The third examples shows that you can query based on properties which are not a primitive type. + NOTE: Note that for version 1.0 we currently don't support referring to parameters that are mapped as `DBRef` in the domain class. @@ -154,6 +160,10 @@ NOTE: Note that for version 1.0 we currently don't support referring to paramete | Sample | Logical result +| `After` +| `findByBirthdateAfter(Date date)` +| `{"birthdate" : {"$gt" : date}}` + | `GreaterThan` | `findByAgeGreaterThan(int age)` | `{"age" : {"$gt" : age}}` @@ -162,6 +172,10 @@ NOTE: Note that for version 1.0 we currently don't support referring to paramete | `findByAgeGreaterThanEqual(int age)` | `{"age" : {"$gte" : age}}` +| `Before` +| `findByBirthdateBefore(Date date)` +| `{"birthdate" : {"$lt" : date}}` + | `LessThan` | `findByAgeLessThan(int age)` | `{"age" : {"$lt" : age}}` @@ -190,10 +204,18 @@ NOTE: Note that for version 1.0 we currently don't support referring to paramete | `findByFirstnameNull()` | `{"firstname" : null}` -| `Like` +| `Like`, `StartingWith`, `EndingWith` | `findByFirstnameLike(String name)` | `{"firstname" : name} ( name as regex)` +| `Containing` on String +| `findByFirstnameContaining(String name)` +| `{"firstname" : name} (name as regex)` + +| `Containing` on Collection +| `findByAddressesContaining(Address address)` +| `{"addresses" : { "$in" : address}}` + | `Regex` | `findByFirstnameRegex(String firstname)` | `{"firstname" : {"$regex" : firstname }}` diff --git a/src/main/asciidoc/reference/mongodb.adoc b/src/main/asciidoc/reference/mongodb.adoc index aee74a7807..33607a449e 100644 --- a/src/main/asciidoc/reference/mongodb.adoc +++ b/src/main/asciidoc/reference/mongodb.adoc @@ -21,7 +21,7 @@ For most tasks you will find yourself using `MongoTemplate` or the Repository su [[mongodb-getting-started]] == Getting Started -Spring MongoDB support requires MongoDB 1.4 or higher and Java SE 5 or higher. The latest production release (2.4.9 as of this writing) is recommended. An easy way to bootstrap setting up a working environment is to create a Spring based project in http://spring.io/tools/sts[STS]. +Spring MongoDB support requires MongoDB 2.6 or higher and Java SE 6 or higher. An easy way to bootstrap setting up a working environment is to create a Spring based project in http://spring.io/tools/sts[STS]. First you need to set up a running Mongodb server. Refer to the http://docs.mongodb.org/manual/core/introduction/[Mongodb Quick Start guide] for an explanation on how to startup a MongoDB instance. Once installed starting MongoDB is typically a matter of executing the following command: `MONGO_HOME/bin/mongod` @@ -38,7 +38,7 @@ Then add the following to pom.xml dependencies section. org.springframework.data spring-data-mongodb - 1.4.1.RELEASE + 1.7.0.RELEASE @@ -48,7 +48,7 @@ Also change the version of Spring in the pom.xml to be [source,xml] ---- -3.2.8.RELEASE +4.0.9.RELEASE ---- You will also need to add the location of the Spring Milestone repository for maven to your pom.xml which is at the same level of your element @@ -162,7 +162,7 @@ Even in this simple example, there are few things to take notice of [[mongo.examples-repo]] == Examples Repository -There is an https://github.com/spring-projects/spring-data-document-examples[github repository with several examples] that you can download and play around with to get a feel for how the library works. +There is an https://github.com/spring-projects/spring-data-examples[github repository with several examples] that you can download and play around with to get a feel for how the library works. [[mongodb-connectors]] == Connecting to MongoDB with Spring @@ -1156,6 +1156,96 @@ As you can see we use the `NearQuery` builder API to set up a query to return al The geo near operations return a `GeoResults` wrapper object that encapsulates `GeoResult` instances. The wrapping `GeoResults` allows to access the average distance of all results. A single `GeoResult` object simply carries the entity found plus its distance from the origin. +[[mongo.geo-json]] +=== GeoJSON Support + +MongoDB supports http://geojeson.org/[GeoJSON] and simple (legacy) coordinate pairs for geospatial data. Those formats can both be used for storing as well as querying data. + +NOTE: Please refer to the http://docs.mongodb.org/manual/core/2dsphere/#geospatial-indexes-store-geojson/[MongoDB manual on GeoJSON support] to learn about requirements and restrictions. + +==== GeoJSON types in domain classes + +Usage of http://geojeson.org/[GeoJSON] types in domain classes is straight forward. The `org.springframework.data.mongodb.core.geo` package contains types like `GeoJsonPoint`, `GeoJsonPolygon` and others. Those are extensions to the existing `org.springframework.data.geo` types. + +==== +[source,java] +---- +public class Store { + + String id; + + /** + * location is stored in GeoJSON format. + * { + * "type" : "Point", + * "coordinates" : [ x, y ] + * } + */ + GeoJsonPoint location; +} +---- +==== + +==== GeoJSON types in repository query methods + +Using GeoJSON types as repository query parameters forces usage of the `$geometry` operator when creating the query. + +==== +[source,java] +---- +public interface StoreRepository extends CrudRepository { + + List findByLocationWithin(Polygon polygon); <1> + +} + +/* + * { + * "location": { + * "$geoWithin": { + * "$geometry": { + * "type": "Polygon", + * "coordinates": [ + * [ + * [-73.992514,40.758934], + * [-73.961138,40.760348], + * [-73.991658,40.730006], + * [-73.992514,40.758934] + * ] + * ] + * } + * } + * } + * } + */ +repo.findByLocationWithin( <2> + new GeoJsonPolygon( + new Point(-73.992514, 40.758934), + new Point(-73.961138, 40.760348), + new Point(-73.991658, 40.730006), + new Point(-73.992514, 40.758934))); <3> + +/* + * { + * "location" : { + * "$geoWithin" : { + * "$polygon" : [ [-73.992514,40.758934] , [-73.961138,40.760348] , [-73.991658,40.730006] ] + * } + * } + * } + */ +repo.findByLocationWithin( <4> + new Polygon( + new Point(-73.992514, 40.758934), + new Point(-73.961138, 40.760348), + new Point(-73.991658, 40.730006)); +---- +<1> Repository method definition using the commons type allows calling it with both GeoJSON and legacy format. +<2> Use GeoJSON type the make use of `$geometry` operator. +<3> Plase note that GeoJSON polygons need the define a closed ring. +<4> Use legacy format `$polygon` operator. +==== + [[mongo.textsearch]] === Full Text Queries @@ -1340,17 +1430,21 @@ MongoDB allows to execute JavaScript functions on the server by either directly === Example Usage +==== [source,java] ---- ScriptOperations scriptOps = template.scriptOps(); -ServerSideJavaScript echoScript = new ExecutableMongoScript("function(x) { return x; }"); -scriptOps.execute(echoScript, "directly execute script"); +ExecutableMongoScript echoScript = new ExecutableMongoScript("function(x) { return x; }"); +scriptOps.execute(echoScript, "directly execute script"); <1> -scriptOps.register(new CallableMongoScript("echo", echoScript)); -scriptOps.call("echo", "execute script via name"); +scriptOps.register(new NamedMongoScript("echo", echoScript)); <2> +scriptOps.call("echo", "execute script via name"); <3> ---- - +<1> Execute the script directly without storing the function on server side. +<2> Store the script using 'echo' as its name. The given name identifies the script and allows calling it later. +<3> Execute the script with name 'echo' using the provided parameters. +==== [[mongo.group]] == Group Operations