Spring/spring-data-mongodb
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

DATAMONGO-856 - Documentation update.

Browse Source 
Removed outdated why-spring-data-doc. Removed CouchDB reference from requirements document. Fixed some typos. Added missing opening <para>-element. Fixed rendering of author information. Added copyright and product name information.

Original pull request: #128.
This commit is contained in:
Thomas Darimont
2014-02-21 11:25:01 +01:00
committed by Oliver Gierke
parent eb03ae61f2
commit f16e8d85e5
8 changed files with 60 additions and 92 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
src/docbkx/index.xml
View File

@@ -42,11 +42,20 @@
<legalnotice>
<para>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.
</para>
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.</para>
</legalnotice>
<pubdate />
<copyright>
<year>2008-2014</year>
<holder> The original authors.</holder>
</copyright>
<productname>Spring Data MongoDB - Reference Documentation</productname>
</bookinfo>
<toc/>
@@ -57,7 +66,6 @@
<title>Introduction</title>
<xi:include href="introduction/introduction.xml"/>
<xi:include href="introduction/why-sd-doc.xml"/>
<xi:include href="introduction/requirements.xml"/>
<xi:include href="introduction/getting-started.xml"/>
<xi:include href="https://raw.github.com/spring-projects/spring-data-commons/1.7.0.RC1/src/docbkx/repositories.xml">

2
src/docbkx/introduction/getting-started.xml
View File

@@ -19,7 +19,7 @@
<title>Community Forum</title>
<para>The Spring Data <ulink
url="http://forum.springframework.org/forumdisplay.php?f=80">forum
url="http://forum.spring.io/forum/spring-projects/data">forum
</ulink> is a message board for all Spring Data (not just Document)
users to share information and help each other. Note that registration
is needed <emphasis>only</emphasis> for posting.</para>

5
src/docbkx/introduction/introduction.xml
View File

@@ -61,6 +61,11 @@
other useful resources.</para>
<itemizedlist>
<listitem>
<para>The <ulink url="http://docs.mongodb.org/manual/">manual</ulink> introduces MongoDB and contains links to
getting started guides, reference documentation and tutorials.</para>
</listitem>
<listitem>
<para>The <ulink url="http://try.mongodb.org/">online shell</ulink>
provides a convenient way to interact with a MongoDB instance in

7
src/docbkx/introduction/requirements.xml
View File

@@ -1,7 +1,7 @@
<chapter id="requirements">
<title>Requirements</title>
<para>Spring Data Document 1.x binaries requires JDK level 6.0 and above,
<para>Spring Data MongoDB 1.x binaries requires JDK level 6.0 and above,
and
<ulink url="https://spring.io/docs">Spring Framework</ulink>
3.2.x and above.
@@ -9,9 +9,6 @@
<para>
In terms of document stores,
<ulink url="http://www.mongodb.org/">MongoDB</ulink>
preferably version 2.4
or later or
<ulink url="http://couchdb.apache.org/">CouchDB</ulink>
1.0.1 or later are required.
preferably version 2.4.
</para>
</chapter>

39
src/docbkx/introduction/why-sd-doc.xml
View File

@@ -1,39 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<chapter id="why-Spring Data-Document">
<title>Why Spring Data - Document?</title>
<para>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.</para>
<para><ulink url="http://en.wikipedia.org/wiki/NoSQL">NoSQL</ulink> 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.</para>
<para>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.
</para>
<para>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.</para>
</chapter>

2
src/docbkx/reference/mapping.xml
View File

@@ -679,8 +679,6 @@ public class PersonWriteConverter implements Converter&lt;Person, DBObject&gt; {
}
}</programlisting>
<para/>
</section>
</section>
</chapter>

10
src/docbkx/reference/mongo-repositories.xml
View File

@@ -224,7 +224,7 @@ public class PersonRepositoryTests {
<entry><code>{"age" : {"$gt" : age}}</code></entry>
</row>
<row>
<entry><literal>GreaterThanEqual</literal></entry>
@@ -242,7 +242,7 @@ public class PersonRepositoryTests {
<entry><code>{"age" : {"$lt" : age}}</code></entry>
</row>
<row>
<entry><literal>LessThanEqual</literal></entry>
@@ -260,7 +260,7 @@ public class PersonRepositoryTests {
<entry><code>{"age" : {"$gt" : from, "$lt" : to}}</code></entry>
</row>
<row>
<entry><literal>In</literal></entry>
@@ -269,7 +269,7 @@ public class PersonRepositoryTests {
<entry><code>{"age" : {"$in" : [ages...]}}</code></entry>
</row>
<row>
<entry><literal>NotIn</literal></entry>
@@ -565,7 +565,7 @@ Page&lt;Person&gt; page = repository.findAll(person.lastname.contains("a"),
</programlisting>
<para>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</para>
<programlisting lang="" language="java">public interface PersonRepository extends MongoRepository&lt;Person, String&gt;, QueryDslPredicateExecutor&lt;Person&gt; {

69
src/docbkx/reference/mongodb.xml
View File

@@ -44,8 +44,8 @@
</listitem>
<listitem>
<para>Automatic implementatin of Repository interfaces including support
for custom finder methods.</para>
<para>Automatic implementation of Repository interfaces including
support for custom finder methods.</para>
</listitem>
<listitem>
@@ -81,20 +81,20 @@
<title>Getting Started</title>
<para>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 <ulink
url="http://spring.io/tools/sts">STS</ulink>.</para>
<para>First you need to set up a running Mongodb server. Refer to the
<ulink url="http://docs.mongodb.org/manual/core/introduction/">Mongodb Quick
Start guide</ulink> for an explanation on how to startup a MongoDB
<ulink url="http://docs.mongodb.org/manual/core/introduction/">Mongodb
Quick Start guide</ulink> for an explanation on how to startup a MongoDB
instance. Once installed starting MongoDB is typically a matter of
executing the following command:
<literal>MONGO_HOME/bin/mongod</literal></para>
<para>To create a Spring project in STS go to File -&gt; New -&gt; Spring
Template Project -&gt; Simple Spring Utility Project --&gt; press Yes when
Template Project -&gt; Simple Spring Utility Project -&gt; press Yes when
prompted. Then enter a project and a package name such as
org.spring.mongodb.example.</para>
@@ -107,14 +107,13 @@
&lt;dependency&gt;
&lt;groupId&gt;org.springframework.data&lt;/groupId&gt;
&lt;artifactId&gt;spring-data-mongodb&lt;/artifactId&gt;
&lt;version&gt;1.1.0.RELEASE&lt;/version&gt;
&lt;version&gt;1.3.4.RELEASE&lt;/version&gt;
&lt;/dependency&gt;
&lt;/dependencies&gt;</programlisting>
<para>Also change the version of Spring in the pom.xml to be</para>
<programlisting lang="" language="xml">&lt;spring.framework.version&gt;3.1.2.RELEASE&lt;/spring.framework.version&gt;</programlisting>
<programlisting lang="" language="xml">&lt;spring.framework.version&gt;3.2.8.RELEASE&lt;/spring.framework.version&gt;</programlisting>
<para>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;
}</programlisting>
<para>The following sections show how you can use the contiainer with
<para>The following sections show how you can use the container with
either Java or the XML based metadata to configure an instance of the
<classname>MongoDbFactory</classname> interface. In turn, you can use
the <classname>MongoDbFactory</classname> instance to configure
@@ -971,7 +970,7 @@ DEBUG work.data.mongodb.core.MongoTemplate: 376 - Dropped collection [database.p
functionality</para>
</note>
<para>The query stynax used in the example is explained in more detail in
<para>The query syntax used in the example is explained in more detail in
the section <link linkend="mongo.query">Querying Documents</link>.</para>
<section id="mongo-template.id-handling">
@@ -1080,7 +1079,7 @@ mongoTemplate.save(sample);
</example>
<para>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 <classname>Contact</classname>. So if you're now using
<methodname>mongoTemplate.findAll(Object.class, "sample")</methodname>
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.</para>
<para>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
<classname>String</classname>, <classname>ObjectId</classname>, or
<classname>BigInteger</classname>.</para>
@@ -1285,14 +1284,14 @@ Person qp = mongoTemplate.findOne(query(where("age").is(33)), Person.class);
<listitem>
<para><emphasis role="bold">insertAll</emphasis> Takes a
<literal>Collection </literal>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.</para>
</listitem>
<listitem>
<para><emphasis role="bold">save</emphasis> Save the object
ovewriting any object that might exist with the same id.</para>
overwriting any object that might exist with the same id.</para>
</listitem>
</itemizedlist></para>
</section>
@@ -1372,7 +1371,7 @@ import static org.springframework.data.mongodb.core.query.Update;
<title>Methods for the Update class</title>
<para>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
<literal>public static Update update(String key, Object
value)</literal> and using static imports.</para>
@@ -1451,7 +1450,7 @@ import static org.springframework.data.mongodb.core.query.Update;
<section id="mongo-template.upserts">
<title>Upserting documents in a collection</title>
<para>Related to perfomring an <methodname>updateFirst</methodname>
<para>Related to performing an <methodname>updateFirst</methodname>
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&lt;Person&gt; result = mongoTemplate.find(query(where("age").lt(50)
</emphasis> <literal>(String key) </literal>Adds a chained
<classname>Criteria</classname> with the specified
<literal>key</literal> to the current
<classname>Criteria</classname> and retuns the newly created
<classname>Criteria</classname> and returns the newly created
one</para>
</listitem>
@@ -2157,7 +2156,7 @@ MapReduceResults&lt;ValueObject&gt; results = mongoOperations.mapReduce(query, "
<title>Example Usage</title>
<para>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.</para>
@@ -2233,7 +2232,7 @@ MapReduceResults&lt;ValueObject&gt; results = mongoOperations.mapReduce(query, "
}
}</programlisting>
<para>You can also obtain tha raw result as a
<para>You can also obtain the raw result as a
<classname>DbObject</classname> by calling the method
<methodname>getRawResults</methodname> on the
<classname>GroupByResults</classname> class.</para>
@@ -2319,9 +2318,9 @@ GroupByResults&lt;XObject&gt; results = mongoTemplate.group(where("x").gt(0),
<para><classname>AggregationResults</classname> is the container for
the result of an aggregate operation. It provides access to the raw
aggreation result in the form of an <classname>DBObject</classname>,
to the mapped objects and information which performed the
aggregation.</para>
aggregation result in the form of an
<classname>DBObject</classname>, to the mapped objects and
information which performed the aggregation.</para>
</listitem>
</itemizedlist>
@@ -2345,8 +2344,8 @@ List&lt;OutputType&gt; mappedResult = results.getMappedResults();
<classname>MongoTemplate</classname> 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.</para>
an input-class and an input-collection is provided the latter takes
precedence.</para>
</section>
<section id="mongo.aggregation.supported-aggregation-operations">
@@ -2461,7 +2460,7 @@ project("a","b").and("foo").as("bar") // will generate {$project: {a: 1, b: 1, b
documentation.</para>
<section id="mongo.aggregation.projection.expressions">
<title>Spring Expresison Support in Projection Expressions</title>
<title>Spring Expression Support in Projection Expressions</title>
<para>As of Version 1.4.0 we support the use of SpEL expression in
projection expressions via the <methodname>andExpression</methodname>
@@ -2472,7 +2471,7 @@ project("a","b").and("foo").as("bar") // will generate {$project: {a: 1, b: 1, b
calculations.</para>
<example>
<title>Complex calulations with SpEL expressions</title>
<title>Complex calculations with SpEL expressions</title>
<para>The following SpEL expression:</para>
@@ -2500,14 +2499,14 @@ project("a","b").and("foo").as("bar") // will generate {$project: {a: 1, b: 1, b
<section id="mongo.aggregation.examples">
<title>Aggregation Framework Examples</title>
<para>The follwing examples demonstrate the usage patterns for the
<para>The following examples demonstrate the usage patterns for the
MongoDB Aggregation Framework with Spring Data MongoDB.</para>
<example id="mongo.aggregation.examples.example1">
<title>Aggregation Framework Example 1</title>
<para>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 <code>"tags"</code> 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&lt;TagCount&gt; tagCount = results.getMappedResults();</programlisting>
<listitem>
<para>In the forth step we use the <methodname>group</methodname>
operation to define a group for each <code>"tags"</code>-value for
which we aggregate the occurence count via the
which we aggregate the occurrence count via the
<methodname>count</methodname> aggregation operator and collect the
result in a new field called <code>"n"</code>.</para>
</listitem>
@@ -2570,7 +2569,7 @@ List&lt;TagCount&gt; tagCount = results.getMappedResults();</programlisting>
<listitem>
<para>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
<methodname>sort</methodname> operation.</para>
</listitem>
@@ -2688,7 +2687,7 @@ ZipInfoStats firstZipInfoStats = result.getMappedResults().get(0);
<para>As the forth step we select the <code>"state"</code> field
from the previous <methodname>group</methodname> operation. Note
that <code>"state"</code> 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
<code>and(previousOperation()).exclude()</code>. As we want to
populate the nested <classname>City</classname> structures in our
@@ -2917,7 +2916,7 @@ public class PersonWriteConverter implements Converter&lt;Person, DBObject&gt; {
<section id="mongo.custom-converters.reader">
<title>Reading using a Spring Converter</title>
<para>An example implemention of a Converter that converts from a
<para>An example implementation of a Converter that converts from a
DBObject ot a Person object is shownn below</para>
<programlisting language="java">public class PersonReadConverter implements Converter&lt;DBObject, Person&gt; {
@@ -3000,12 +2999,12 @@ class MyConverter implements Converter&lt;String, Person&gt; { … }</programlis
</section>
<section id="mongo-template.index-and-collections">
<title>Index and Collection managment</title>
<title>Index and Collection management</title>
<para><classname>MongoTemplate</classname> provides a few methods for
managing indexes and collections. These are collected into a helper
interface called <interfacename>IndexOperations</interfacename>. You
access these operations by calilng the method
access these operations by calling the method
<methodname>indexOps</methodname> and pass in either the collection name
or the <literal>java.lang.Class</literal> of your entity (the collection
name will be derived from the .class either by name or via annotation