From eb03ae61f2742fd1c2258d432998c3e29c46a58a Mon Sep 17 00:00:00 2001 From: Christoph Strobl Date: Fri, 21 Feb 2014 09:18:07 +0100 Subject: [PATCH] DATAMONGO-856 - Documentation updates. Updated references from springsource.org to spring.io. Updated references to mongodb.org. Update vendor to Pivotal Software, Inc. Update required/recommended versions. Update CustomConversions configuration section. Added missing section id's. Fixed some typos. Added missing JavaDoc. Original pull request: #128. --- README.md | 18 ++-- pom.xml | 2 +- spring-data-mongodb-cross-store/template.mf | 2 +- spring-data-mongodb-log4j/template.mf | 2 +- .../mongodb/core/MongoDocumentWriter.java | 20 ---- .../data/mongodb/core/MongoOperations.java | 98 ++++++++++++++++--- .../mongodb/core/MongoSynchronization.java | 18 ++++ .../mongodb/core/index/CompoundIndex.java | 14 +++ .../data/mongodb/core/index/Index.java | 20 +++- .../data/mongodb/core/index/Indexed.java | 26 +++++ .../data/mongodb/core/query/Criteria.java | 96 ++++++++++++++---- .../data/mongodb/core/query/Query.java | 25 +++++ .../data/mongodb/core/query/Update.java | 32 ++++-- spring-data-mongodb/template.mf | 2 +- src/docbkx/index.xml | 4 + src/docbkx/introduction/getting-started.xml | 2 +- src/docbkx/introduction/introduction.xml | 8 +- src/docbkx/introduction/requirements.xml | 4 +- src/docbkx/introduction/why-sd-doc.xml | 4 +- src/docbkx/reference/cross-store.xml | 6 +- src/docbkx/reference/mapping.xml | 48 ++++----- src/docbkx/reference/mongo-repositories.xml | 46 ++++++++- src/docbkx/reference/mongodb.xml | 23 ++--- src/main/resources/readme.txt | 4 +- 24 files changed, 393 insertions(+), 131 deletions(-) delete mode 100644 spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/MongoDocumentWriter.java diff --git a/README.md b/README.md index 99475d045..1322af676 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Spring Data MongoDB -The primary goal of the [Spring Data](http://www.springsource.org/spring-data) project is to make it easier to build Spring-powered applications that use new data access technologies such as non-relational databases, map-reduce frameworks, and cloud based data services. +The primary goal of the [Spring Data](http://projects.spring.io/spring-data) project is to make it easier to build Spring-powered applications that use new data access technologies such as non-relational databases, map-reduce frameworks, and cloud based data services. The Spring Data MongoDB project aims to provide a familiar and consistent Spring-based programming model for new datastores while retaining store-specific features and capabilities. The Spring Data MongoDB project provides integration with the MongoDB document database. Key functional areas of Spring Data MongoDB are a POJO centric model for interacting with a MongoDB DBCollection and easily writing a repository style data access layer. @@ -8,12 +8,12 @@ The Spring Data MongoDB project aims to provide a familiar and consistent Spring For a comprehensive treatment of all the Spring Data MongoDB features, please refer to: -* the [User Guide](http://static.springsource.org/spring-data/data-mongodb/docs/current/reference/html/) -* the [JavaDocs](http://static.springsource.org/spring-data/data-mongodb/docs/current/api/) have extensive comments in them as well. -* the home page of [Spring Data MongoDB](http://www.springsource.org/spring-data/mongodb) contains links to articles and other resources. -* for more detailed questions, use the [forum](http://forum.springsource.org/forumdisplay.php?f=80). +* the [User Guide](http://docs.spring.io/spring-data/mongodb/docs/current/reference/html/) +* the [JavaDocs](http://docs.spring.io/spring-data/mongodb/docs/current/api/) have extensive comments in them as well. +* the home page of [Spring Data MongoDB](http://projects.spring.io/spring-data-mongodb) contains links to articles and other resources. +* for more detailed questions, use the [forum](http://forum.spring.io/forum/spring-projects/data/nosql). -If you are new to Spring as well as to Spring Data, look for information about [Spring projects](http://www.springsource.org/projects). +If you are new to Spring as well as to Spring Data, look for information about [Spring projects](http://projects.spring.io/). ## Quick Start @@ -53,7 +53,7 @@ MongoTemplate is the central support class for Mongo database operations. It pro * Basic POJO mapping support to and from BSON * Convenience methods to interact with the store (insert object, update objects) and MongoDB specific ones (geo-spatial operations, upserts, map-reduce etc.) * Connection affinity callback -* Exception translation into Spring's [technology agnostic DAO exception hierarchy](http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/dao.html#dao-exceptions). +* Exception translation into Spring's [technology agnostic DAO exception hierarchy](http://docs.spring.io/spring/docs/current/spring-framework-reference/html/dao.html#dao-exceptions). ### Spring Data repositories @@ -139,9 +139,9 @@ public class MyService { Here are some ways for you to get involved in the community: -* Get involved with the Spring community on the Spring Community Forums. Please help out on the [forum](http://forum.springsource.org/forumdisplay.php?f=80) by responding to questions and joining the debate. +* Get involved with the Spring community on the Spring Community Forums. Please help out on the [forum](http://forum.spring.io/forum/spring-projects/data/nosql) by responding to questions and joining the debate. * Create [JIRA](https://jira.springframework.org/browse/DATADOC) tickets for bugs and new features and comment and vote on the ones that you are interested in. * Github is for social coding: if you want to write code, we encourage contributions through pull requests from [forks of this repository](http://help.github.com/forking/). If you want to contribute code this way, please reference a JIRA ticket as well covering the specific issue you are addressing. -* Watch for upcoming articles on Spring by [subscribing](http://www.springsource.org/node/feed) to springframework.org +* Watch for upcoming articles on Spring by [subscribing](http://spring.io/blog) to spring.io. Before we accept a non-trivial patch or pull request we will need you to sign the [contributor's agreement](https://support.springsource.com/spring_committer_signup). Signing the contributor's agreement does not grant anyone commit rights to the main repository, but it does mean that we can accept your contributions, and you will get an author credit if we do. Active contributors might be asked to join the core team, and given the ability to merge pull requests. diff --git a/pom.xml b/pom.xml index 34aaa13dc..73830c11e 100644 --- a/pom.xml +++ b/pom.xml @@ -10,7 +10,7 @@ Spring Data MongoDB MongoDB support for Spring Data - http://www.springsource.org/spring-data/mongodb + http://projects.spring.io/spring-data-mongodb org.springframework.data.build diff --git a/spring-data-mongodb-cross-store/template.mf b/spring-data-mongodb-cross-store/template.mf index b60ecf1fb..8c38801c1 100644 --- a/spring-data-mongodb-cross-store/template.mf +++ b/spring-data-mongodb-cross-store/template.mf @@ -1,6 +1,6 @@ Bundle-SymbolicName: org.springframework.data.mongodb.crossstore Bundle-Name: Spring Data MongoDB Cross Store Support -Bundle-Vendor: SpringSource +Bundle-Vendor: Pivotal Software, Inc. Bundle-ManifestVersion: 2 Import-Package: sun.reflect;version="0";resolution:=optional diff --git a/spring-data-mongodb-log4j/template.mf b/spring-data-mongodb-log4j/template.mf index bee95d777..606d49db0 100644 --- a/spring-data-mongodb-log4j/template.mf +++ b/spring-data-mongodb-log4j/template.mf @@ -1,6 +1,6 @@ Bundle-SymbolicName: org.springframework.data.mongodb.log4j Bundle-Name: Spring Data Mongo DB Log4J Appender -Bundle-Vendor: SpringSource +Bundle-Vendor: Pivotal Software, Inc. Bundle-ManifestVersion: 2 Import-Package: sun.reflect;version="0";resolution:=optional diff --git a/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/MongoDocumentWriter.java b/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/MongoDocumentWriter.java deleted file mode 100644 index a860731ea..000000000 --- a/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/MongoDocumentWriter.java +++ /dev/null @@ -1,20 +0,0 @@ -/* - * Copyright 2010-2011 the original author or authors. - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ -package org.springframework.data.mongodb.core; - -public interface MongoDocumentWriter { - -} diff --git a/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/MongoOperations.java b/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/MongoOperations.java index b5ae39ee3..36ecb036a 100644 --- a/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/MongoOperations.java +++ b/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/MongoOperations.java @@ -1,6 +1,6 @@ /* - * Copyright 2010-2013 the original author or authors. - * + * Copyright 2011-2014 the original author or authors. + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -468,10 +468,32 @@ public interface MongoOperations { */ T findOne(Query query, Class entityClass, String collectionName); + /** + * Determine result of given {@link Query} contains at least one element. + * + * @param query the {@link Query} class that specifies the criteria used to find a record. + * @param collectionName name of the collection to check for objects. + * @return + */ boolean exists(Query query, String collectionName); + /** + * Determine result of given {@link Query} contains at least one element. + * + * @param query the {@link Query} class that specifies the criteria used to find a record. + * @param entityClass the parameterized type. + * @return + */ boolean exists(Query query, Class entityClass); + /** + * Determine result of given {@link Query} contains at least one element. + * + * @param query the {@link Query} class that specifies the criteria used to find a record. + * @param entityClass the parameterized type. + * @param collectionName name of the collection to check for objects. + * @return + */ boolean exists(Query query, Class entityClass, String collectionName); /** @@ -529,12 +551,58 @@ public interface MongoOperations { */ T findById(Object id, Class entityClass, String collectionName); + /** + * Triggers findAndModify + * to apply provided {@link Update} on documents matching {@link Criteria} of given {@link Query}. + * + * @param query the {@link Query} class that specifies the {@link Criteria} used to find a record and also an optional + * fields specification. + * @param update the {@link Update} to apply on matching documents. + * @param entityClass the parameterized type. + * @return + */ T findAndModify(Query query, Update update, Class entityClass); + /** + * Triggers findAndModify + * to apply provided {@link Update} on documents matching {@link Criteria} of given {@link Query}. + * + * @param query the {@link Query} class that specifies the {@link Criteria} used to find a record and also an optional + * fields specification. + * @param update the {@link Update} to apply on matching documents. + * @param entityClass the parameterized type. + * @param collectionName the collection to query. + * @return + */ T findAndModify(Query query, Update update, Class entityClass, String collectionName); + /** + * Triggers findAndModify + * to apply provided {@link Update} on documents matching {@link Criteria} of given {@link Query} taking + * {@link FindAndModifyOptions} into account. + * + * @param query the {@link Query} class that specifies the {@link Criteria} used to find a record and also an optional + * fields specification. + * @param update the {@link Update} to apply on matching documents. + * @param options the {@link FindAndModifyOptions} holding additional information. + * @param entityClass the parameterized type. + * @return + */ T findAndModify(Query query, Update update, FindAndModifyOptions options, Class entityClass); + /** + * Triggers findAndModify + * to apply provided {@link Update} on documents matching {@link Criteria} of given {@link Query} taking + * {@link FindAndModifyOptions} into account. + * + * @param query the {@link Query} class that specifies the {@link Criteria} used to find a record and also an optional + * fields specification. + * @param update the {@link Update} to apply on matching documents. + * @param options the {@link FindAndModifyOptions} holding additional information. + * @param entityClass the parameterized type. + * @param collectionName the collection to query. + * @return + */ T findAndModify(Query query, Update update, FindAndModifyOptions options, Class entityClass, String collectionName); @@ -598,9 +666,9 @@ public interface MongoOperations { *

* If you object has an "Id' property, it will be set with the generated Id from MongoDB. If your Id property is a * String then MongoDB ObjectId will be used to populate that string. Otherwise, the conversion from ObjectId to your - * property type will be handled by Spring's BeanWrapper class that leverages Spring 3.0's new Type Conversion API. - * See Spring 3 Type - * Conversion" for more details. + * property type will be handled by Spring's BeanWrapper class that leverages Type Conversion API. See Spring's Type Conversion" for more details. *

*

* Insert is used to initially store the object into the database. To update an existing object use the save method. @@ -655,9 +723,9 @@ public interface MongoOperations { *

* If you object has an "Id' property, it will be set with the generated Id from MongoDB. If your Id property is a * String then MongoDB ObjectId will be used to populate that string. Otherwise, the conversion from ObjectId to your - * property type will be handled by Spring's BeanWrapper class that leverages Spring 3.0's new Type Conversion API. - * See Spring 3 Type - * Conversion" for more details. + * property type will be handled by Spring's BeanWrapper class that leverages Type Conversion API. See Spring's Type Conversion" for more details. * * @param objectToSave the object to store in the collection */ @@ -672,9 +740,9 @@ public interface MongoOperations { *

* If you object has an "Id' property, it will be set with the generated Id from MongoDB. If your Id property is a * String then MongoDB ObjectId will be used to populate that string. Otherwise, the conversion from ObjectId to your - * property type will be handled by Spring's BeanWrapper class that leverages Spring 3.0's new Type Cobnversion API. - * See Spring 3 Type - * Conversion" for more details. + * property type will be handled by Spring's BeanWrapper class that leverages Type Cobnversion API. See Spring's + * Type Conversion" for more details. * * @param objectToSave the object to store in the collection * @param collectionName name of the collection to store the object in @@ -814,6 +882,14 @@ public interface MongoOperations { */ void remove(Query query, Class entityClass); + /** + * Remove all documents that match the provided query document criteria from the the collection used to store the + * entityClass. The Class parameter is also used to help convert the Id of the object if it is present in the query. + * + * @param query + * @param entityClass + * @param collectionName + */ void remove(Query query, Class entityClass, String collectionName); /** diff --git a/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/MongoSynchronization.java b/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/MongoSynchronization.java index e35046d9d..02e48989f 100644 --- a/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/MongoSynchronization.java +++ b/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/MongoSynchronization.java @@ -1,8 +1,26 @@ +/* + * Copyright 2012-2014 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ package org.springframework.data.mongodb.core; import org.springframework.transaction.support.ResourceHolder; import org.springframework.transaction.support.ResourceHolderSynchronization; +/** + * @author Oliver Gierke + */ class MongoSynchronization extends ResourceHolderSynchronization { public MongoSynchronization(ResourceHolder resourceHolder, Object resourceKey) { diff --git a/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/index/CompoundIndex.java b/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/index/CompoundIndex.java index 1b4190544..8c8209022 100644 --- a/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/index/CompoundIndex.java +++ b/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/index/CompoundIndex.java @@ -51,10 +51,24 @@ public @interface CompoundIndex { @Deprecated IndexDirection direction() default IndexDirection.ASCENDING; + /** + * @see http://docs.mongodb.org/manual/core/index-unique/ + * @return + */ boolean unique() default false; + /** + * If set to true index will skip over any document that is missing the indexed field. + * + * @see http://docs.mongodb.org/manual/core/index-sparse/ + * @return + */ boolean sparse() default false; + /** + * @see http://docs.mongodb.org/manual/core/index-creation/#index-creation-duplicate-dropping + * @return + */ boolean dropDups() default false; /** diff --git a/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/index/Index.java b/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/index/Index.java index 0a5e6d3d4..c7bbd7c8c 100644 --- a/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/index/Index.java +++ b/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/index/Index.java @@ -41,8 +41,7 @@ public class Index implements IndexDefinition { private boolean sparse = false; - public Index() { - } + public Index() {} public Index(String key, Direction direction) { fieldSpec.put(key, direction); @@ -83,16 +82,33 @@ public class Index implements IndexDefinition { return this; } + /** + * Reject all documents that contain a duplicate value for the indexed field. + * + * @see http://docs.mongodb.org/manual/core/index-unique/ + * @return + */ public Index unique() { this.unique = true; return this; } + /** + * Skip over any document that is missing the indexed field. + * + * @see http://docs.mongodb.org/manual/core/index-sparse/ + * @return + */ public Index sparse() { this.sparse = true; return this; } + /** + * @see http://docs.mongodb.org/manual/core/index-creation/#index-creation-duplicate-dropping + * @param duplicates + * @return + */ public Index unique(Duplicates duplicates) { if (duplicates == Duplicates.DROP) { this.dropDuplicates = true; diff --git a/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/index/Indexed.java b/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/index/Indexed.java index f918fa026..65838c54e 100644 --- a/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/index/Indexed.java +++ b/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/index/Indexed.java @@ -32,16 +32,42 @@ import java.lang.annotation.Target; @Retention(RetentionPolicy.RUNTIME) public @interface Indexed { + /** + * If set to true reject all documents that contain a duplicate value for the indexed field. + * + * @see http://docs.mongodb.org/manual/core/index-unique/ + * @return + */ boolean unique() default false; IndexDirection direction() default IndexDirection.ASCENDING; + /** + * If set to true index will skip over any document that is missing the indexed field. + * + * @see http://docs.mongodb.org/manual/core/index-sparse/ + * @return + */ boolean sparse() default false; + /** + * @see http://docs.mongodb.org/manual/core/index-creation/#index-creation-duplicate-dropping + * @return + */ boolean dropDups() default false; + /** + * Index name. + * + * @return + */ String name() default ""; + /** + * Colleciton name for index to be created on. + * + * @return + */ String collection() default ""; /** diff --git a/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/query/Criteria.java b/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/query/Criteria.java index 786b0cc84..22241b553 100644 --- a/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/query/Criteria.java +++ b/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/query/Criteria.java @@ -43,6 +43,7 @@ import com.mongodb.DBObject; * @author Thomas Risberg * @author Oliver Gierke * @author Thomas Darimont + * @author Christoph Strobl */ public class Criteria implements CriteriaDefinition { @@ -117,8 +118,9 @@ public class Criteria implements CriteriaDefinition { } /** - * Creates a criterion using the $ne operator + * Creates a criterion using the {@literal $ne} operator. * + * @see http://docs.mongodb.org/manual/reference/operator/query/ne/ * @param o * @return */ @@ -128,8 +130,9 @@ public class Criteria implements CriteriaDefinition { } /** - * Creates a criterion using the $lt operator + * Creates a criterion using the {@literal $lt} operator. * + * @see http://docs.mongodb.org/manual/reference/operator/query/lt/ * @param o * @return */ @@ -139,8 +142,9 @@ public class Criteria implements CriteriaDefinition { } /** - * Creates a criterion using the $lte operator + * Creates a criterion using the {@literal $lte} operator. * + * @see http://docs.mongodb.org/manual/reference/operator/query/lte/ * @param o * @return */ @@ -150,8 +154,9 @@ public class Criteria implements CriteriaDefinition { } /** - * Creates a criterion using the $gt operator + * Creates a criterion using the {@literal $gt} operator. * + * @see http://docs.mongodb.org/manual/reference/operator/query/gt/ * @param o * @return */ @@ -161,8 +166,9 @@ public class Criteria implements CriteriaDefinition { } /** - * Creates a criterion using the $gte operator + * Creates a criterion using the {@literal $gte} operator. * + * @see http://docs.mongodb.org/manual/reference/operator/query/gte/ * @param o * @return */ @@ -172,8 +178,9 @@ public class Criteria implements CriteriaDefinition { } /** - * Creates a criterion using the $in operator + * Creates a criterion using the {@literal $in} operator. * + * @see http://docs.mongodb.org/manual/reference/operator/query/in/ * @param o the values to match against * @return */ @@ -187,8 +194,9 @@ public class Criteria implements CriteriaDefinition { } /** - * Creates a criterion using the $in operator + * Creates a criterion using the {@literal $in} operator. * + * @see http://docs.mongodb.org/manual/reference/operator/query/in/ * @param c the collection containing the values to match against * @return */ @@ -198,8 +206,9 @@ public class Criteria implements CriteriaDefinition { } /** - * Creates a criterion using the $nin operator + * Creates a criterion using the {@literal $nin} operator. * + * @see http://docs.mongodb.org/manual/reference/operator/query/nin/ * @param o * @return */ @@ -207,14 +216,22 @@ public class Criteria implements CriteriaDefinition { return nin(Arrays.asList(o)); } + /** + * Creates a criterion using the {@literal $nin} operator. + * + * @see http://docs.mongodb.org/manual/reference/operator/query/nin/ + * @param o + * @return + */ public Criteria nin(Collection o) { criteria.put("$nin", o); return this; } /** - * Creates a criterion using the $mod operator + * Creates a criterion using the {@literal $mod} operator. * + * @see http://docs.mongodb.org/manual/reference/operator/query/mod/ * @param value * @param remainder * @return @@ -228,8 +245,9 @@ public class Criteria implements CriteriaDefinition { } /** - * Creates a criterion using the $all operator + * Creates a criterion using the {@literal $all} operator. * + * @see http://docs.mongodb.org/manual/reference/operator/query/all/ * @param o * @return */ @@ -237,14 +255,22 @@ public class Criteria implements CriteriaDefinition { return all(Arrays.asList(o)); } + /** + * Creates a criterion using the {@literal $all} operator. + * + * @see http://docs.mongodb.org/manual/reference/operator/query/all/ + * @param o + * @return + */ public Criteria all(Collection o) { criteria.put("$all", o); return this; } /** - * Creates a criterion using the $size operator + * Creates a criterion using the {@literal $size} operator. * + * @see http://docs.mongodb.org/manual/reference/operator/query/size/ * @param s * @return */ @@ -254,8 +280,9 @@ public class Criteria implements CriteriaDefinition { } /** - * Creates a criterion using the $exists operator + * Creates a criterion using the {@literal $exists} operator. * + * @see http://docs.mongodb.org/manual/reference/operator/query/exists/ * @param b * @return */ @@ -265,8 +292,9 @@ public class Criteria implements CriteriaDefinition { } /** - * Creates a criterion using the $type operator + * Creates a criterion using the {@literal $type} operator. * + * @see http://docs.mongodb.org/manual/reference/operator/query/type/ * @param t * @return */ @@ -276,22 +304,31 @@ public class Criteria implements CriteriaDefinition { } /** - * Creates a criterion using the $not meta operator which affects the clause directly following + * Creates a criterion using the {@literal $not} meta operator which affects the clause directly following * + * @see http://docs.mongodb.org/manual/reference/operator/query/not/ * @return */ public Criteria not() { return not(null); } + /** + * Creates a criterion using the {@literal $not} operator. + * + * @see http://docs.mongodb.org/manual/reference/operator/query/not/ + * @param value + * @return + */ private Criteria not(Object value) { criteria.put("$not", value); return this; } /** - * Creates a criterion using a $regex + * Creates a criterion using a {@literal $regex} operator. * + * @see http://docs.mongodb.org/manual/reference/operator/query/regex/ * @param re * @return */ @@ -300,8 +337,10 @@ public class Criteria implements CriteriaDefinition { } /** - * Creates a criterion using a $regex and $options + * Creates a criterion using a {@literal $regex} and {@literal $options} operator. * + * @see http://docs.mongodb.org/manual/reference/operator/query/regex/ + * @see http://docs.mongodb.org/manual/reference/operator/query/regex/#op._S_options * @param re * @param options * @return @@ -334,8 +373,11 @@ public class Criteria implements CriteriaDefinition { } /** - * Creates a geospatial criterion using a $within $center operation. This is only available for Mongo 1.7 and higher. + * Creates a geospatial criterion using a {@literal $within $centerSphere} operation. This is only available for Mongo + * 1.7 and higher. * + * @see http://docs.mongodb.org/manual/reference/operator/query/geoWithin/ + * @see http://docs.mongodb.org/manual/reference/operator/query/centerSphere/ * @param circle must not be {@literal null} * @return */ @@ -345,6 +387,13 @@ public class Criteria implements CriteriaDefinition { return this; } + /** + * Creates a geospatial criterion using a {@literal $within} operation. + * + * @see http://docs.mongodb.org/manual/reference/operator/query/geoWithin/ + * @param shape + * @return + */ public Criteria within(Shape shape) { Assert.notNull(shape); @@ -353,8 +402,9 @@ public class Criteria implements CriteriaDefinition { } /** - * Creates a geospatial criterion using a $near operation + * Creates a geospatial criterion using a {@literal $near} operation. * + * @see http://docs.mongodb.org/manual/reference/operator/query/near/ * @param point must not be {@literal null} * @return */ @@ -365,8 +415,10 @@ public class Criteria implements CriteriaDefinition { } /** - * Creates a geospatial criterion using a $nearSphere operation. This is only available for Mongo 1.7 and higher. + * Creates a geospatial criterion using a {@literal $nearSphere} operation. This is only available for Mongo 1.7 and + * higher. * + * @see http://docs.mongodb.org/manual/reference/operator/query/nearSphere/ * @param point must not be {@literal null} * @return */ @@ -377,8 +429,9 @@ public class Criteria implements CriteriaDefinition { } /** - * Creates a geospatical criterion using a $maxDistance operation, for use with $near + * Creates a geospatical criterion using a {@literal $maxDistance} operation, for use with $near * + * @see http://docs.mongodb.org/manual/reference/operator/query/maxDistance/ * @param maxDistance * @return */ @@ -388,8 +441,9 @@ public class Criteria implements CriteriaDefinition { } /** - * Creates a criterion using the $elemMatch operator + * Creates a criterion using the {@literal $elemMatch} operator * + * @see http://docs.mongodb.org/manual/reference/operator/query/elemMatch/ * @param c * @return */ diff --git a/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/query/Query.java b/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/query/Query.java index 172861e13..fb9ccd971 100644 --- a/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/query/Query.java +++ b/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/query/Query.java @@ -99,11 +99,23 @@ public class Query { return this.fieldSpec; } + /** + * Set number of documents to skip before returning results. + * + * @param skip + * @return + */ public Query skip(int skip) { this.skip = skip; return this; } + /** + * Limit the number of returned documents to {@code limit}. + * + * @param limit + * @return + */ public Query limit(int limit) { this.limit = limit; return this; @@ -231,14 +243,27 @@ public class Query { return dbo; } + /** + * Get the number of documents to skip. + * + * @return + */ public int getSkip() { return this.skip; } + /** + * Get the maximum number of documents to be return. + * + * @return + */ public int getLimit() { return this.limit; } + /** + * @return + */ public String getHint() { return hint; } diff --git a/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/query/Update.java b/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/query/Update.java index 8500bec40..cb74f434b 100644 --- a/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/query/Update.java +++ b/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/query/Update.java @@ -96,8 +96,9 @@ public class Update { } /** - * Update using the $set update modifier + * Update using the {@literal $set} update modifier * + * @see http://docs.mongodb.org/manual/reference/operator/update/set/ * @param key * @param value * @return @@ -108,8 +109,9 @@ public class Update { } /** - * Update using the $setOnInsert update modifier + * Update using the {@literal $setOnInsert} update modifier * + * @see http://docs.mongodb.org/manual/reference/operator/update/setOnInsert/ * @param key * @param value * @return @@ -120,8 +122,9 @@ public class Update { } /** - * Update using the $unset update modifier + * Update using the {@literal $unset} update modifier * + * @see http://docs.mongodb.org/manual/reference/operator/update/unset/ * @param key * @return */ @@ -131,8 +134,9 @@ public class Update { } /** - * Update using the $inc update modifier + * Update using the {@literal $inc} update modifier * + * @see http://docs.mongodb.org/manual/reference/operator/update/inc/ * @param key * @param inc * @return @@ -143,8 +147,9 @@ public class Update { } /** - * Update using the $push update modifier + * Update using the {@literal $push} update modifier * + * @see http://docs.mongodb.org/manual/reference/operator/update/push/ * @param key * @param value * @return @@ -158,6 +163,8 @@ public class Update { * Update using {@code $push} modifier.
* Allows creation of {@code $push} command for single or multiple (using {@code $each}) values. * + * @see http://docs.mongodb.org/manual/reference/operator/update/push/ + * @see http://docs.mongodb.org/manual/reference/operator/update/each/ * @param key * @return {@link PushOperatorBuilder} for given key */ @@ -190,8 +197,9 @@ public class Update { } /** - * Update using the $addToSet update modifier + * Update using the {@literal $addToSet} update modifier * + * @see http://docs.mongodb.org/manual/reference/operator/update/addToSet/ * @param key * @param value * @return @@ -202,8 +210,9 @@ public class Update { } /** - * Update using the $pop update modifier + * Update using the {@literal $pop} update modifier * + * @see http://docs.mongodb.org/manual/reference/operator/update/pop/ * @param key * @param pos * @return @@ -214,8 +223,9 @@ public class Update { } /** - * Update using the $pull update modifier + * Update using the {@literal $pull} update modifier * + * @see http://docs.mongodb.org/manual/reference/operator/update/pull/ * @param key * @param value * @return @@ -226,8 +236,9 @@ public class Update { } /** - * Update using the $pullAll update modifier + * Update using the {@literal $pullAll} update modifier * + * @see http://docs.mongodb.org/manual/reference/operator/update/pullAll/ * @param key * @param values * @return @@ -243,8 +254,9 @@ public class Update { } /** - * Update using the $rename update modifier + * Update using the {@literal $rename} update modifier * + * @see http://docs.mongodb.org/manual/reference/operator/update/rename/ * @param oldName * @param newName * @return diff --git a/spring-data-mongodb/template.mf b/spring-data-mongodb/template.mf index ace44eab8..581928954 100644 --- a/spring-data-mongodb/template.mf +++ b/spring-data-mongodb/template.mf @@ -1,6 +1,6 @@ Bundle-SymbolicName: org.springframework.data.mongodb Bundle-Name: Spring Data MongoDB Support -Bundle-Vendor: SpringSource +Bundle-Vendor: Pivotal Software, Inc. Bundle-ManifestVersion: 2 Import-Package: sun.reflect;version="0";resolution:=optional diff --git a/src/docbkx/index.xml b/src/docbkx/index.xml index 72acfa2c8..c3d891824 100644 --- a/src/docbkx/index.xml +++ b/src/docbkx/index.xml @@ -34,6 +34,10 @@ Thomas Darimont + + Christoph + Strobl + diff --git a/src/docbkx/introduction/getting-started.xml b/src/docbkx/introduction/getting-started.xml index 1b38ad2a1..a4da51ddf 100644 --- a/src/docbkx/introduction/getting-started.xml +++ b/src/docbkx/introduction/getting-started.xml @@ -30,7 +30,7 @@ Professional, from-the-source support, with guaranteed response time, is available from SpringSource, the company + url="http://gopivotal.com/">Pivotal Sofware, Inc., the company behind Spring Data and Spring. diff --git a/src/docbkx/introduction/introduction.xml b/src/docbkx/introduction/introduction.xml index 00c3a108f..c7a8aabed 100644 --- a/src/docbkx/introduction/introduction.xml +++ b/src/docbkx/introduction/introduction.xml @@ -62,21 +62,21 @@ - The online shell + The online shell provides a convenient way to interact with a MongoDB instance in combination with the online tutorial. + url="http://docs.mongodb.org/manual/tutorial/getting-started/">tutorial. MongoDB Java + url="http://docs.mongodb.org/ecosystem/drivers/java/">Java Language Center Several books + url="http://www.mongodb.org/books">books available for purchase diff --git a/src/docbkx/introduction/requirements.xml b/src/docbkx/introduction/requirements.xml index af591655e..8aca138f4 100644 --- a/src/docbkx/introduction/requirements.xml +++ b/src/docbkx/introduction/requirements.xml @@ -4,12 +4,12 @@ Spring Data Document 1.x binaries requires JDK level 6.0 and above, and Spring Framework - 3.0.x and above. + 3.2.x and above. In terms of document stores, MongoDB - preferably version 1.6.5 + preferably version 2.4 or later or CouchDB 1.0.1 or later are required. diff --git a/src/docbkx/introduction/why-sd-doc.xml b/src/docbkx/introduction/why-sd-doc.xml index ee9dd0ddb..637fca234 100644 --- a/src/docbkx/introduction/why-sd-doc.xml +++ b/src/docbkx/introduction/why-sd-doc.xml @@ -20,7 +20,7 @@ provide an extension to the Spring programming model that supports writing applications that use Document databases. The Spring framework has always promoted a POJO programming model with a strong emphasis on portability and - productivity. These values are caried over into Spring Data Document. + productivity. These values are carried over into Spring Data Document. Notable features that are used in Spring Data Document from the Spring @@ -28,7 +28,7 @@ framework that are used are the Conversion Service, JMX Exporters, portable Data Access Exception hierarchy, Spring Expression Language, and Java based IoC container configuration. The programming model follows the familiar - Spring 'template' style, so if you are familar with Spring template classes + Spring 'template' style, so if you are familiar with Spring template classes such as JdbcTemplate, JmsTemplate, RestTemplate, you will feel right at home. For example, MongoTemplate removes much of the boilerplate code you would have to write when using the MongoDB driver to save POJOs as well as a diff --git a/src/docbkx/reference/cross-store.xml b/src/docbkx/reference/cross-store.xml index 50d945262..510d8d4c5 100644 --- a/src/docbkx/reference/cross-store.xml +++ b/src/docbkx/reference/cross-store.xml @@ -8,7 +8,7 @@ data stores can be of different types. One might be relational while the other a document store. For this use case we have created a separate module in the MongoDB support that handles what we call cross-store support. The - current implemenatation is based on JPA as the driver for the relational + current implementation is based on JPA as the driver for the relational database and we allow select fields in the Entities to be stored in a Mongo database. In addition to allowing you to store your data in two stores we also coordinate persistence operations for the non-transactional MongoDB @@ -186,14 +186,14 @@ We are assuming that you have a working JPA application so we will only cover the additional steps needed to persist part of your Entity in your Mongo database. First you need to identify the field you want - persited. It should be a domain class and follow the general rules for the + persisted. It should be a domain class and follow the general rules for the Mongo mapping support covered in previous chapters. The field you want persisted in MongoDB should be annotated using the @RelatedDocument annotation. That is really all you need to do!. The cross-store aspects take care of the rest. This includes marking the field with @Transient so it won't be persisted using JPA, keeping track of any changes made to the field value and writing them to - the database on succesfull transaction completion, loading the document + the database on successful transaction completion, loading the document from MongoDB the first time the value is used in your application. Here is an example of a simple Entity that has a field annotated with @RelatedEntity. diff --git a/src/docbkx/reference/mapping.xml b/src/docbkx/reference/mapping.xml index 62d6d369b..16cde3cca 100644 --- a/src/docbkx/reference/mapping.xml +++ b/src/docbkx/reference/mapping.xml @@ -4,7 +4,7 @@ Mapping - Rich maping support is provided by the + Rich mapping support is provided by the MongoMappingConverter. MongoMappingConverter has a rich metadata model that provides a full feature set of functionality to map domain objects to @@ -60,13 +60,13 @@ You can have a single non-zero argument constructor whose constructor argument names match top level field names of document, - that constructor will be used. Otherewise the zero arg constructor - will be used. if there is more than one non-zero argument constructor - an exception will be thrown. + that constructor will be used. Otherwise the zero arg constructor will + be used. if there is more than one non-zero argument constructor an + exception will be thrown. -

+
How the '_id' field is handled in the mapping layer MongoDB requires that you have an '_id' field for all documents. @@ -104,7 +104,7 @@ the Java class it will be converted to and stored as an ObjectId if possible. ObjectId as a field type is also valid. If you specify a value for 'id' in your application, the conversion to an ObjectId is - delected to the MongoDBdriver. If the specified 'id' value cannot be + detected to the MongoDBdriver. If the specified 'id' value cannot be converted to an ObjectId, then the value will be stored as is in the document's _id field. @@ -172,12 +172,14 @@ public class GeoSpatialAppConfig extends AbstractMongoConfiguration { // the following are optional + + @Bean @Override - protected void afterMappingMongoConverterCreation(MappingMongoConverter converter) { - Set<Converter<?, ?>> converterList = new HashSet<Converter<?, ?>>(); + public CustomConversions customConversions() throws Exception { + List<Converter<?, ?>> converterList = new ArrayList<Converter<?, ?>>(); converterList.add(new org.springframework.data.mongodb.test.PersonReadConverter()); converterList.add(new org.springframework.data.mongodb.test.PersonWriteConverter()); - converter.setCustomConverters(converterList); + return new CustomConversions(converterList); } @Bean @@ -454,7 +456,7 @@ public class Person<T extends Address> {
Customized Object Construction - The Mapping Subsystem allows the customization of the object + The mapping subsystem allows the customization of the object construction by annotating a constructor with the @PersistenceConstructor annotation. The values to be used for the constructor parameters are resolved in the following @@ -487,9 +489,9 @@ public class Person<T extends Address> { class OrderItem { - @Id String id; - int quantity; - double unitPrice; + private @Id String id; + private int quantity; + private double unitPrice; OrderItem(String id, @Value("#root.qty ?: 0") int quantity, double unitPrice) { this.id = id; @@ -642,20 +644,17 @@ public class Person { 3 Type Conversion. - The setConverters method on - SimpleMongoConverter and - MappingMongoConverter should be used for this - purpose. The method - afterMappingMongoConverterCreation in - AbstractMongoConfiguration can be overriden to - configure a MappingMongoConverter. The examples here at the begining of this chapter show how to - perform the configuration using Java and XML. + The method customConversions in + AbstractMongoConfiguration can be used to + configure Converters. The examples here at the begining of this + chapter show how to perform the configuration using Java and XML. Below is an example of a Spring Converter implementation that converts from a DBObject to a Person POJO. - public class PersonReadConverter implements Converter<DBObject, Person> { + @ReadingConverter + public class PersonReadConverter implements Converter<DBObject, Person> { public Person convert(DBObject source) { Person p = new Person((ObjectId) source.get("_id"), (String) source.get("name")); @@ -668,7 +667,8 @@ public class Person { Here is an example that converts from a Person to a DBObject. - public class PersonWriteConverter implements Converter<Person, DBObject> { + @WritingConverter +public class PersonWriteConverter implements Converter<Person, DBObject> { public DBObject convert(Person source) { DBObject dbo = new BasicDBObject(); diff --git a/src/docbkx/reference/mongo-repositories.xml b/src/docbkx/reference/mongo-repositories.xml index 03ec90f8d..8f7303fc1 100644 --- a/src/docbkx/reference/mongo-repositories.xml +++ b/src/docbkx/reference/mongo-repositories.xml @@ -224,6 +224,15 @@ public class PersonRepositoryTests { {"age" : {"$gt" : age}} + + + GreaterThanEqual + + findByAgeGreaterThanEqual(int + age) + + {"age" : {"$gte" : age}} + LessThan @@ -233,6 +242,15 @@ public class PersonRepositoryTests { {"age" : {"$lt" : age}} + + + LessThanEqual + + findByAgeLessThanEqual(int + age) + + {"age" : {"$lte" : age}} + Between @@ -242,6 +260,24 @@ public class PersonRepositoryTests { {"age" : {"$gt" : from, "$lt" : to}} + + + In + + findByAgeIn(Collection ages) + + + {"age" : {"$in" : [ages...]}} + + + + NotIn + + findByAgeNotIn(Collection ages) + + + {"age" : {"$nin" : [ages...]}} + IsNotNull, @@ -358,7 +394,7 @@ public class PersonRepositoryTests { -
+
Geo-spatial repository queries As you've just seen there are a few keywords triggering @@ -418,7 +454,7 @@ Distance distance = new Distance(200, Metrics.KILOMETERS);
-
+
MongoDB JSON based query methods and field restriction By adding the annotation @@ -452,7 +488,7 @@ Distance distance = new Distance(200, Metrics.KILOMETERS); set and its value will therefore be null.
-
+
Type-safe Query methods MongoDB repository support integrates with the
-
+
Miscellaneous -
+
CDI Integration Instances of the repository interfaces are usually created by a diff --git a/src/docbkx/reference/mongodb.xml b/src/docbkx/reference/mongodb.xml index 7f300e52a..2d3ac9f3f 100644 --- a/src/docbkx/reference/mongodb.xml +++ b/src/docbkx/reference/mongodb.xml @@ -84,10 +84,10 @@ or higher. The latest production release (2.0.x as of this writing) is recommended. An easy way to bootstrap setting up a working environment is to create a Spring based project in STS. + url="http://spring.io/tools/sts">STS. First you need to set up a running Mongodb server. Refer to the - Mongodb Quick + 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: @@ -115,6 +115,7 @@ Also change the version of Spring in the pom.xml to be <spring.framework.version>3.1.2.RELEASE</spring.framework.version> + <spring.framework.version>3.2.8.RELEASE</spring.framework.version> 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 @@ -124,7 +125,7 @@ <repository> <id>spring-milestone</id> <name>Spring Maven MILESTONE Repository</name> - <url>http://repo.springsource.org/libs-milestone</url> + <url>http://repo.spring.io/libs-milestone</url> </repository> </repositories> @@ -310,7 +311,7 @@ public class AppConfig { classes annoated with the @Repository annotation. This hierarchy and use of @Repository is described in Spring's + url="http://docs.spring.io/spring/docs/current/spring-framework-reference/html/dao.html">Spring's DAO support features. An example of a Java based bean metadata that supports exception @@ -1459,7 +1460,7 @@ import static org.springframework.data.mongodb.core.query.Update; template.upsert(query(where("ssn").is(1111).and("firstName").is("Joe").and("Fraizer").is("Update")), update("address", addr), Person.class);
-
+
Finding and Upserting documents in a collection The findAndModify(…) method on @@ -2029,7 +2030,7 @@ GeoResults<Restaurant> = operations.geoNear(query, Restaurant.class);Resource + url="http://docs.spring.io/spring/docs/current/spring-framework-reference/html/resources.html">Resource abstraction abstraction. This will let you place your JavaScript files on the file system, classpath, http server or any other Spring Resource implementation and then reference the JavaScript resources via an @@ -2143,7 +2144,7 @@ MapReduceResults<ValueObject> results = mongoOperations.mapReduce(query, " providing methods on MongoOperations to simplify the creation and execution of group operations. It can convert the results of the group operation to a POJO and also integrates with Spring's Resource + url="http://docs.spring.io/spring/docs/current/spring-framework-reference/html/resources.html">Resource abstraction abstraction. This will let you place your JavaScript files on the file system, classpath, http server or any other Spring Resource implementation and then reference the JavaScript resources via an @@ -2885,7 +2886,7 @@ List<DBObject> resultList = result.getMappedResults(); For more information on the Spring type conversion service see the reference docs here. + url="http://docs.spring.io/spring/docs/current/spring-framework-reference/html/validation.html#core-convert">here.
@@ -2968,7 +2969,7 @@ public class PersonWriteConverter implements Converter<Person, DBObject> { </mongo:mapping-converter>
-
+
Converter disambiguation Generally we inspect the Converter @@ -3244,11 +3245,11 @@ mongoTemplate.dropCollection("MyNewCollection"); interface. The motivation behind mapping to Spring's consistent + url="http://docs.spring.io/spring/docs/current/spring-framework-reference/html/dao.html#dao-exceptions">consistent data access exception hierarchy is that you are then able to write portable and descriptive exception handling code without resorting to coding against MongoDB error + url="http://www.mongodb.org/about/contributors/error-codes/">MongoDB error codes. All of Spring's data access exceptions are inherited from the root DataAccessException class so you can be sure that you will be able to catch all database related exception within diff --git a/src/main/resources/readme.txt b/src/main/resources/readme.txt index 86210102b..366931ac4 100644 --- a/src/main/resources/readme.txt +++ b/src/main/resources/readme.txt @@ -13,5 +13,5 @@ The reference manual and javadoc are located in the 'docs' directory. ADDITIONAL RESOURCES: -Spring Data Homepage: http://www.springsource.org/spring-data -Spring Data Forum: http://forum.springsource.org/forumdisplay.php?f=80 +Spring Data Homepage: http://projects.spring.io/spring-data +Spring Data Forum: http://forum.spring.io/forum/spring-projects/data/nosql