From f16e8d85e5360abdf237564d3bb8bc9e41709f5f Mon Sep 17 00:00:00 2001 From: Thomas Darimont Date: Fri, 21 Feb 2014 11:25:01 +0100 Subject: [PATCH] DATAMONGO-856 - Documentation update. Removed outdated why-spring-data-doc. Removed CouchDB reference from requirements document. Fixed some typos. Added missing opening -element. Fixed rendering of author information. Added copyright and product name information. Original pull request: #128. --- src/docbkx/index.xml | 18 ++++-- src/docbkx/introduction/getting-started.xml | 2 +- src/docbkx/introduction/introduction.xml | 5 ++ src/docbkx/introduction/requirements.xml | 7 +-- src/docbkx/introduction/why-sd-doc.xml | 39 ------------ src/docbkx/reference/mapping.xml | 2 - src/docbkx/reference/mongo-repositories.xml | 10 +-- src/docbkx/reference/mongodb.xml | 69 ++++++++++----------- 8 files changed, 60 insertions(+), 92 deletions(-) delete mode 100644 src/docbkx/introduction/why-sd-doc.xml diff --git a/src/docbkx/index.xml b/src/docbkx/index.xml index c3d891824..2976b8fcd 100644 --- a/src/docbkx/index.xml +++ b/src/docbkx/index.xml @@ -42,11 +42,20 @@ Copies of this document may be made for your own use and for - distribution to others, provided that you do not charge any fee for such - copies and further provided that each copy contains this Copyright - Notice, whether distributed in print or electronically. - + distribution to others, provided that you do not charge any fee for such + copies and further provided that each copy contains this Copyright + Notice, whether distributed in print or electronically. + + + + + 2008-2014 + + The original authors. + + + Spring Data MongoDB - Reference Documentation @@ -57,7 +66,6 @@ Introduction - diff --git a/src/docbkx/introduction/getting-started.xml b/src/docbkx/introduction/getting-started.xml index a4da51ddf..ea4206501 100644 --- a/src/docbkx/introduction/getting-started.xml +++ b/src/docbkx/introduction/getting-started.xml @@ -19,7 +19,7 @@ Community Forum The Spring Data forum + url="http://forum.spring.io/forum/spring-projects/data">forum is a message board for all Spring Data (not just Document) users to share information and help each other. Note that registration is needed only for posting. diff --git a/src/docbkx/introduction/introduction.xml b/src/docbkx/introduction/introduction.xml index c7a8aabed..7684a1259 100644 --- a/src/docbkx/introduction/introduction.xml +++ b/src/docbkx/introduction/introduction.xml @@ -61,6 +61,11 @@ other useful resources. + + The manual introduces MongoDB and contains links to + getting started guides, reference documentation and tutorials. + + The online shell provides a convenient way to interact with a MongoDB instance in diff --git a/src/docbkx/introduction/requirements.xml b/src/docbkx/introduction/requirements.xml index 8aca138f4..8640ce9d1 100644 --- a/src/docbkx/introduction/requirements.xml +++ b/src/docbkx/introduction/requirements.xml @@ -1,7 +1,7 @@ Requirements - Spring Data Document 1.x binaries requires JDK level 6.0 and above, + Spring Data MongoDB 1.x binaries requires JDK level 6.0 and above, and Spring Framework 3.2.x and above. @@ -9,9 +9,6 @@ In terms of document stores, MongoDB - preferably version 2.4 - or later or - CouchDB - 1.0.1 or later are required. + preferably version 2.4. \ No newline at end of file diff --git a/src/docbkx/introduction/why-sd-doc.xml b/src/docbkx/introduction/why-sd-doc.xml deleted file mode 100644 index 637fca234..000000000 --- a/src/docbkx/introduction/why-sd-doc.xml +++ /dev/null @@ -1,39 +0,0 @@ - - - - Why Spring Data - Document? - - The Spring Framework is the leading full-stack Java/JEE application - framework. It provides a lightweight container and a non-invasive - programming model enabled by the use of dependency injection, AOP, and - portable service abstractions. - - NoSQL storages - provide an alternative to classical RDBMS for horizontal scalability and - speed. In terms of implementation, Document stores represent one of the most - popular types of stores in the NoSQL space. The document database supported - by Spring Data are MongoDB and CouchDB, though just MongoDB integration has - been released to date. - - The goal of the Spring Data Document (or DATADOC) framework is to - 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 carried over into Spring Data Document. - - - Notable features that are used in Spring Data Document from the Spring - framework are the Features that particular, features from the Spring - 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 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 - rich java based query interface to retrieve POJOs. The programming model - also offers a new Repository approach in which the Spring container will - provide an implementation of a Repository based soley off an interface - definition which can also include custom finder methods. - diff --git a/src/docbkx/reference/mapping.xml b/src/docbkx/reference/mapping.xml index 16cde3cca..775df2286 100644 --- a/src/docbkx/reference/mapping.xml +++ b/src/docbkx/reference/mapping.xml @@ -679,8 +679,6 @@ public class PersonWriteConverter implements Converter<Person, DBObject> { } } - - diff --git a/src/docbkx/reference/mongo-repositories.xml b/src/docbkx/reference/mongo-repositories.xml index 8f7303fc1..9ca801feb 100644 --- a/src/docbkx/reference/mongo-repositories.xml +++ b/src/docbkx/reference/mongo-repositories.xml @@ -224,7 +224,7 @@ public class PersonRepositoryTests { {"age" : {"$gt" : age}} - + GreaterThanEqual @@ -242,7 +242,7 @@ public class PersonRepositoryTests { {"age" : {"$lt" : age}} - + LessThanEqual @@ -260,7 +260,7 @@ public class PersonRepositoryTests { {"age" : {"$gt" : from, "$lt" : to}} - + In @@ -269,7 +269,7 @@ public class PersonRepositoryTests { {"age" : {"$in" : [ages...]}} - + NotIn @@ -565,7 +565,7 @@ Page<Person> page = repository.findAll(person.lastname.contains("a"), To use this in your repository implementation, simply inherit from - it in additiion to other repository interfaces. This is shown + it in addition to other repository interfaces. This is shown below public interface PersonRepository extends MongoRepository<Person, String>, QueryDslPredicateExecutor<Person> { diff --git a/src/docbkx/reference/mongodb.xml b/src/docbkx/reference/mongodb.xml index 2d3ac9f3f..9053358b6 100644 --- a/src/docbkx/reference/mongodb.xml +++ b/src/docbkx/reference/mongodb.xml @@ -44,8 +44,8 @@ - Automatic implementatin of Repository interfaces including support - for custom finder methods. + Automatic implementation of Repository interfaces including + support for custom finder methods. @@ -81,20 +81,20 @@ Getting Started Spring MongoDB support requires MongoDB 1.4 or higher and Java SE 5 - or higher. The latest production release (2.0.x as of this writing) is + 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 STS. First you need to set up a running Mongodb server. Refer to the - Mongodb Quick - Start guide for an explanation on how to startup a MongoDB + 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 To create a Spring project in STS go to File -> New -> Spring - Template Project -> Simple Spring Utility Project --> press Yes when + Template Project -> Simple Spring Utility Project -> press Yes when prompted. Then enter a project and a package name such as org.spring.mongodb.example. @@ -107,14 +107,13 @@ <dependency> <groupId>org.springframework.data</groupId> <artifactId>spring-data-mongodb</artifactId> - <version>1.1.0.RELEASE</version> + <version>1.3.4.RELEASE</version> </dependency> </dependencies> 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 @@ -435,7 +434,7 @@ public class AppConfig { DB getDb(String dbName) throws DataAccessException; } - The following sections show how you can use the contiainer with + The following sections show how you can use the container with either Java or the XML based metadata to configure an instance of the MongoDbFactory interface. In turn, you can use the MongoDbFactory instance to configure @@ -971,7 +970,7 @@ DEBUG work.data.mongodb.core.MongoTemplate: 376 - Dropped collection [database.p functionality - The query stynax used in the example is explained in more detail in + The query syntax used in the example is explained in more detail in the section Querying Documents.
@@ -1080,7 +1079,7 @@ mongoTemplate.save(sample); As you can see we store the type information for the actual root - class persistet as well as for the nested type as it is complex and a + class persistent as well as for the nested type as it is complex and a subtype of Contact. So if you're now using mongoTemplate.findAll(Object.class, "sample") we are able to find out that the document stored shall be a @@ -1198,8 +1197,8 @@ class SampleMongoConfiguration extends AbstractMongoConfiguration { overriden using mapping metadata. When inserting or saving, if the Id property is not set, the - assumption is that its value will be autogenerated by the database. As - such, for autogeneration of an ObjectId to succeed the type of the Id + assumption is that its value will be auto-generated by the database. As + such, for auto-generation of an ObjectId to succeed the type of the Id property/field in your class must be either a String, ObjectId, or BigInteger. @@ -1285,14 +1284,14 @@ Person qp = mongoTemplate.findOne(query(where("age").is(33)), Person.class); insertAll Takes a Collection of objects as the first parameter. - This method ispects each object and inserts it to the + This method inspects each object and inserts it to the appropriate collection based on the rules specified above. save Save the object - ovewriting any object that might exist with the same id. + overwriting any object that might exist with the same id.
@@ -1372,7 +1371,7 @@ import static org.springframework.data.mongodb.core.query.Update; Methods for the Update class The Update class can be used with a little 'syntax sugar' as its - methods are meant to be chained together and you can kickstart the + methods are meant to be chained together and you can kick-start the creation of a new Update instance via the static method public static Update update(String key, Object value) and using static imports. @@ -1451,7 +1450,7 @@ import static org.springframework.data.mongodb.core.query.Update;
Upserting documents in a collection - Related to perfomring an updateFirst + Related to performing an updateFirst operations, you can also perform an upsert operation which will perform an insert if no document is found that matches the query. The document that is inserted is a combination of the query document and the update @@ -1618,7 +1617,7 @@ List<Person> result = mongoTemplate.find(query(where("age").lt(50) (String key) Adds a chained Criteria with the specified key to the current - Criteria and retuns the newly created + Criteria and returns the newly created one @@ -2157,7 +2156,7 @@ MapReduceResults<ValueObject> results = mongoOperations.mapReduce(query, " Example Usage In order to understand how group operations work the following - example is used, which is somewhat artifical. For a more realistic + example is used, which is somewhat artificial. For a more realistic example consult the book 'MongoDB - The definitive guide'. A collection named "group_test_collection" created with the following rows. @@ -2233,7 +2232,7 @@ MapReduceResults<ValueObject> results = mongoOperations.mapReduce(query, " } } - You can also obtain tha raw result as a + You can also obtain the raw result as a DbObject by calling the method getRawResults on the GroupByResults class. @@ -2319,9 +2318,9 @@ GroupByResults<XObject> results = mongoTemplate.group(where("x").gt(0), AggregationResults is the container for the result of an aggregate operation. It provides access to the raw - aggreation result in the form of an DBObject, - to the mapped objects and information which performed the - aggregation. + aggregation result in the form of an + DBObject, to the mapped objects and + information which performed the aggregation. @@ -2345,8 +2344,8 @@ List<OutputType> mappedResult = results.getMappedResults(); MongoTemplate will derive the name of the input collection from this class. Otherwise if you don't not specify an input class you must provide the name of the input collection explicitly. If - an input-class and an explicity input-collection is provided the latter - takes precedence. + an input-class and an input-collection is provided the latter takes + precedence.
@@ -2461,7 +2460,7 @@ project("a","b").and("foo").as("bar") // will generate {$project: {a: 1, b: 1, b documentation.
- Spring Expresison Support in Projection Expressions + Spring Expression Support in Projection Expressions As of Version 1.4.0 we support the use of SpEL expression in projection expressions via the andExpression @@ -2472,7 +2471,7 @@ project("a","b").and("foo").as("bar") // will generate {$project: {a: 1, b: 1, b calculations. - Complex calulations with SpEL expressions + Complex calculations with SpEL expressions The following SpEL expression: @@ -2500,14 +2499,14 @@ project("a","b").and("foo").as("bar") // will generate {$project: {a: 1, b: 1, b
Aggregation Framework Examples - The follwing examples demonstrate the usage patterns for the + The following examples demonstrate the usage patterns for the MongoDB Aggregation Framework with Spring Data MongoDB. Aggregation Framework Example 1 In this introductory example we want to aggregate a list of tags - to get the occurence count of a particular tag from a MongoDB + to get the occurrence count of a particular tag from a MongoDB collection called "tags" sorted by the occurrence count in descending order. This example demonstrates the usage of grouping, sorting, projections (selection) and unwinding (result @@ -2556,7 +2555,7 @@ List<TagCount> tagCount = results.getMappedResults(); In the forth step we use the group operation to define a group for each "tags"-value for - which we aggregate the occurence count via the + which we aggregate the occurrence count via the count aggregation operator and collect the result in a new field called "n". @@ -2570,7 +2569,7 @@ List<TagCount> tagCount = results.getMappedResults(); As the sixth step we sort the resulting list of tags by their - occurence count in descending order via the + occurrence count in descending order via the sort operation. @@ -2688,7 +2687,7 @@ ZipInfoStats firstZipInfoStats = result.getMappedResults().get(0); As the forth step we select the "state" field from the previous group operation. Note that "state" again implicitly references an group-id - field. As we do not want an implict generated id to appear, we + field. As we do not want an implicit generated id to appear, we exclude the id from the previous operation via and(previousOperation()).exclude(). As we want to populate the nested City structures in our @@ -2917,7 +2916,7 @@ public class PersonWriteConverter implements Converter<Person, DBObject> {
Reading using a Spring Converter - An example implemention of a Converter that converts from a + An example implementation of a Converter that converts from a DBObject ot a Person object is shownn below public class PersonReadConverter implements Converter<DBObject, Person> { @@ -3000,12 +2999,12 @@ class MyConverter implements Converter<String, Person> { … }
- Index and Collection managment + Index and Collection management MongoTemplate provides a few methods for managing indexes and collections. These are collected into a helper interface called IndexOperations. You - access these operations by calilng the method + access these operations by calling the method indexOps and pass in either the collection name or the java.lang.Class of your entity (the collection name will be derived from the .class either by name or via annotation