update docs
add remove method on mongotemplate to MongoOperations change Venue to use primitive arrays
This commit is contained in:
Mark Pollack
@@ -268,6 +268,27 @@ public class AppConfig {
|
||||
own converter. Please refer to the section on MongoCoverters for more
|
||||
detailed information.</para>
|
||||
|
||||
<para>The <classname>MongoTemplate</classname> class implements the
|
||||
interface <interfacename>MongoOperations</interfacename>. In as much as
|
||||
possible, the methods on <interfacename>MongoOperations</interfacename>
|
||||
are named after methods available on the MongoDB driver
|
||||
<classname>Collection</classname> object. For example, you will find
|
||||
methods such as "find", "findAndModify", "findOne", "insert", "remove",
|
||||
"save", "update" and "updateMulti". The design goal was to make it as easy
|
||||
as possible to transition between the use of the base MongoDB driver and
|
||||
<interfacename>MongoOperations</interfacename>. The difference in betwee
|
||||
the two is that MongOperations can be passed domain objects instead of
|
||||
<classname>DBObject</classname> and there are fluent APIs for
|
||||
<classname>Query</classname>, <classname>Criteria</classname>, and
|
||||
<classname>Update</classname> operations instead of
|
||||
<classname>DBObject</classname>..</para>
|
||||
|
||||
<note>
|
||||
<para>The preferred way to reference the operations on
|
||||
<classname>MongoTemplate</classname> instance is via its interface
|
||||
<interfacename>MongoOperations</interfacename>.</para>
|
||||
</note>
|
||||
|
||||
<para>The default converter implementation used by
|
||||
<classname>MongoTemplate</classname> is
|
||||
<classname>SimpleMappingConverter</classname>, which as the name implies,
|
||||
@@ -401,11 +422,13 @@ public class AppConfig {
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<title>Saving, Updating, and Deleting Documents</title>
|
||||
<title>Saving, Updating, and Removing Documents</title>
|
||||
|
||||
<para>MongoTemplate provides a simple way for you to save, update, and
|
||||
delete your domain objects and map those objects to documents stored in
|
||||
MongoDB. Given a simple class such as Person</para>
|
||||
MongoDB. </para>
|
||||
|
||||
<para>Given a simple class such as Person</para>
|
||||
|
||||
<programlisting>public class Person {
|
||||
|
||||
@@ -466,16 +489,49 @@ remove using query: { "_id" : { "$oid" : "4d9e82ac94fa72c65a9e7d5f"}}
|
||||
Number of people = : 0</programlisting>
|
||||
|
||||
<para>There was implicit conversion using SimpleMongoConverter between a
|
||||
String and ObjectId as stored in the database.</para>
|
||||
String and ObjectId as stored in the database and recognizing a convention
|
||||
of the property "Id" name. </para>
|
||||
|
||||
<note>
|
||||
<para>This example is meant to show the use of save, update and remove
|
||||
operations on MongoTemplate and not to show complex mapping
|
||||
functionality</para>
|
||||
</note>
|
||||
|
||||
<para>The query stynax used in the example is explained in more detail in
|
||||
the section <link linkend="mongo.query">Querying Documents</link>.</para>
|
||||
|
||||
<section>
|
||||
<title>Methods for saving documents</title>
|
||||
<title>Methods for saving and inserting documents</title>
|
||||
|
||||
<para>Once we have created the collection and maybe an index we can
|
||||
start using the collection to store our domain objects as documents.
|
||||
Note that we are using a static import for
|
||||
<classname>org.springframework.data.document.mongodb.query.Criteria.where</classname>
|
||||
to make the query more readable.</para>
|
||||
<para>There are several convenient methods on MongoTemplate for saving
|
||||
and inserting your objects. In addition to using a
|
||||
<interfacename>MongoCoverter</interfacename> to converter your domain
|
||||
object to the database, you can also use an implementation of the
|
||||
<interfacename>MongoWriter</interfacename> interface to have very fine
|
||||
grained control over the conversion process.</para>
|
||||
|
||||
<note>
|
||||
<para>The difference between insert and save operations is that a save
|
||||
operation will perform an insert if the object is not already
|
||||
present.</para>
|
||||
</note>
|
||||
|
||||
<para>The simple case of using the save operation is to pass in as an
|
||||
argument only the object to save. In this case the default collection
|
||||
assigned to the template will be used unless the converter overrides
|
||||
this default through the use of more specific mapping metadata. You may
|
||||
also call the save operation with a specific collection name. </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
|
||||
property/field in your class must be either a
|
||||
<classname>String</classname>, <classname>ObjectId</classname>, or
|
||||
<classname>BigInteger</classname>.</para>
|
||||
|
||||
<para>Here is a basic example of using the save operation and retrieving
|
||||
its contents.</para>
|
||||
|
||||
<example>
|
||||
<title>Inserting and retrieving documents using the
|
||||
@@ -489,10 +545,13 @@ import static org.springframework.data.document.mongodb.query.Criteria.query;
|
||||
Person p = new Person("Bob", 33);
|
||||
mongoTemplate.insert("MyCollection", p);
|
||||
|
||||
Person qp = mongoTemplate.findOne("MyCollection", query(where("id").is(p.getId())), Person.class);
|
||||
Person qp = mongoTemplate.findOne("MyCollection", query(where("age").is(33)), Person.class);
|
||||
</programlisting>
|
||||
</example>
|
||||
|
||||
<para>The four save operations available to you are listed below.
|
||||
</para>
|
||||
|
||||
<para><itemizedlist>
|
||||
<listitem>
|
||||
<para><literal>void</literal> <emphasis role="bold">save
|
||||
@@ -521,29 +580,104 @@ import static org.springframework.data.document.mongodb.query.Criteria.query;
|
||||
</listitem>
|
||||
</itemizedlist></para>
|
||||
|
||||
<para></para>
|
||||
<para>A similar set of insert operations is listed below </para>
|
||||
|
||||
<para><itemizedlist>
|
||||
<listitem>
|
||||
<para><literal>void</literal> <emphasis
|
||||
role="bold">insert</emphasis> <literal>(Object objectToSave)
|
||||
</literal> Insert the object to the default collection.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal>void</literal> <emphasis role="bold">insert
|
||||
</emphasis> <literal>(String collectionName, Object objectToSave)
|
||||
</literal> Insert the object to the specified collection.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal><T> void</literal> <emphasis
|
||||
role="bold">insert </emphasis> <literal>(T objectToSave,
|
||||
MongoWriter<T> writer) </literal> Insert the object into the
|
||||
default collection using the provided writer.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal><T> void</literal> <emphasis
|
||||
role="bold">insert </emphasis> <literal>(String collectionName, T
|
||||
objectToSave, MongoWriter<T> writer) </literal> Insert the
|
||||
object into the specified collection using the provided
|
||||
writer.</para>
|
||||
</listitem>
|
||||
</itemizedlist></para>
|
||||
|
||||
<section>
|
||||
<title>Inserting Lists of objects in batch</title>
|
||||
|
||||
<para>The MongoDB driver supports inserting a collection of documents
|
||||
in one operation. The methods in the MongoOperations interface that
|
||||
support this functionality are listed below</para>
|
||||
|
||||
<para><itemizedlist>
|
||||
<listitem>
|
||||
<para><literal>void</literal> <emphasis
|
||||
role="bold">insertList</emphasis><literal> (List<? extends
|
||||
Object> listToSave)</literal><literal> </literal> Insert a
|
||||
list of objects into the default collection in a single batch
|
||||
write to the database.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal>void</literal> <emphasis
|
||||
role="bold">insertList</emphasis> <literal>(String
|
||||
collectionName, List<? extends Object>
|
||||
listToSave)</literal><literal> </literal>Insert a list of
|
||||
objects into the specified collection in a single batch write to
|
||||
the database.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal><T> void</literal> <emphasis
|
||||
role="bold">insertList</emphasis><literal> (List<? extends
|
||||
T> listToSave, MongoWriter<T> writer)</literal>
|
||||
<literal></literal> Insert the object into the default
|
||||
collection using the provided writer.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal><T> void</literal> <emphasis
|
||||
role="bold">insertList</emphasis><literal>(String
|
||||
collectionName, List<? extends T> listToSave,
|
||||
MongoWriter<T> writer)</literal> Insert a list of objects
|
||||
into the specified collection using the provided MongoWriter
|
||||
instance</para>
|
||||
</listitem>
|
||||
</itemizedlist></para>
|
||||
</section>
|
||||
</section>
|
||||
|
||||
<section id="mongodb-template-update">
|
||||
<title>Updating documents in a collection</title>
|
||||
|
||||
<para>For updates we can elect to update the first document found using
|
||||
<interfacename>MongoOperation</interfacename>'s method
|
||||
<literal>updateFirst</literal> or we can update all documents that were
|
||||
found to match the query using<literal>updateMulti</literal>. Here is an
|
||||
example of an update of all SAVINGS accounts where we are adding a one
|
||||
time $50.00 bonus to the balance using the <literal>$inc</literal>
|
||||
operator.</para>
|
||||
found to match the query using the method
|
||||
<literal>updateMulti</literal>. Here is an example of an update of all
|
||||
SAVINGS accounts where we are adding a one time $50.00 bonus to the
|
||||
balance using the <literal>$inc</literal> operator.</para>
|
||||
|
||||
<example>
|
||||
<title>Updating documents using the MongoTemplate</title>
|
||||
|
||||
<programlisting language="java">import static org.springframework.data.document.mongodb.query.Criteria.where;
|
||||
import static org.springframework.data.document.mongodb.query.Query.query;
|
||||
import static org.springframework.data.document.mongodb.query.Update
|
||||
|
||||
...
|
||||
|
||||
WriteResult wr = mongoTemplate.updateMulti(
|
||||
new Query(where("accounts.accountType").is(Account.Type.SAVINGS)),
|
||||
new Update().inc("accounts.$.balance", 50.00));
|
||||
WriteResult wr = mongoTemplate.updateMulti(query(where("accounts.accountType").is(Account.Type.SAVINGS)),
|
||||
update.inc("accounts.$.balance", 50.00));
|
||||
</programlisting>
|
||||
</example>
|
||||
|
||||
@@ -672,81 +806,24 @@ import static org.springframework.data.document.mongodb.query.Criteria.query;
|
||||
</section>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<title>Methods for inserting documents</title>
|
||||
|
||||
<para><itemizedlist>
|
||||
<listitem>
|
||||
<para><literal>void</literal> <emphasis role="bold">insert
|
||||
</emphasis> <literal>(Object objectToSave) </literal> Insert the
|
||||
object into the default collection.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal>void</literal> <emphasis role="bold">insert
|
||||
</emphasis> <literal>(String collectionName, Object objectToSave)
|
||||
</literal> Insert the object into the specified collection.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal>void</literal> <emphasis role="bold">insertList
|
||||
</emphasis> <literal>(List<? extends Object> listToSave)
|
||||
</literal> Insert a list of objects into the default collection in
|
||||
a single batch write to the database.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal>void</literal> <emphasis role="bold">insertList
|
||||
</emphasis> <literal>(String collectionName, List<? extends
|
||||
Object> listToSave) </literal> Insert a list of objects into
|
||||
the specified collection in a single batch write to the
|
||||
database.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal><T> void</literal> <emphasis
|
||||
role="bold">insert </emphasis> <literal>(T objectToSave,
|
||||
MongoWriter<T> writer) </literal> Insert the object into the
|
||||
default collection.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal><T> void</literal> <emphasis
|
||||
role="bold">insert </emphasis> <literal>(String collectionName, T
|
||||
objectToSave, MongoWriter<T> writer) </literal> Insert the
|
||||
object into the specified collection.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal><T> void</literal> <emphasis
|
||||
role="bold">insertList </emphasis> <literal>(List<? extends
|
||||
T> listToSave, MongoWriter<T> writer) </literal> Insert a
|
||||
list of objects into the default collection using the provided
|
||||
MongoWriter instance</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal><T> void</literal> <emphasis
|
||||
role="bold">insertList </emphasis> <literal>(String
|
||||
collectionName, List<? extends T> listToSave,
|
||||
MongoWriter<T> writer) </literal> Insert a list of objects
|
||||
into the specified collection using the provided MongoWriter
|
||||
instance</para>
|
||||
</listitem>
|
||||
</itemizedlist></para>
|
||||
|
||||
<para></para>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<title>Methods for removing documents</title>
|
||||
|
||||
<para>You can use several overloaded methods to remove an object from
|
||||
the database. </para>
|
||||
|
||||
<para><itemizedlist>
|
||||
<listitem>
|
||||
<para><literal>void</literal> <emphasis role="bold">remove
|
||||
</emphasis> <literal>(Query query)</literal> Remove all documents
|
||||
from the default collection that match the provided query document
|
||||
criteria.</para>
|
||||
<para><literal>void</literal> <emphasis
|
||||
role="bold">remove</emphasis> <literal>(Object object)</literal>
|
||||
Remove the given object from the collection by Id</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal>void</literal> <emphasis
|
||||
role="bold">remove</emphasis> <literal>(Query query)</literal>
|
||||
Remove all documents from the default collection that match the
|
||||
provided query document criteria.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
@@ -755,16 +832,41 @@ import static org.springframework.data.document.mongodb.query.Criteria.query;
|
||||
</literal> Remove all documents from the specified collection that
|
||||
match the provided query document criteria.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal><T> void </literal><emphasis
|
||||
role="bold">remove</emphasis> <literal>(Query query,
|
||||
Class<T> targetClass)</literal> Same behavior as the
|
||||
remove(Query) method but the Class parameter is used to help
|
||||
convert the Id of the object if it is present in the query.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal><T> void </literal><emphasis
|
||||
role="bold">remove</emphasis> <literal>(String collectionName,
|
||||
Query query, Class<T> targetClass)</literal>Same behavior as
|
||||
remove(Query, Class) but the Class parameter is used to help
|
||||
convert the Id of the object if it is present in the uqery</para>
|
||||
</listitem>
|
||||
</itemizedlist></para>
|
||||
|
||||
<para></para>
|
||||
</section>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<section id="mongo.query">
|
||||
<title>Querying Documents</title>
|
||||
|
||||
<para>Query, Criteria</para>
|
||||
<para>You can express you queries using the Query and Criteria classes
|
||||
which have method names that mirror the native MongoDB operator names such
|
||||
as lt, lte, is, and others. The Query and Criteria classes follow a fluent
|
||||
API style so that you can easily chain together multiple method criteria
|
||||
and queries while having easy to understand code. Static imports in Java
|
||||
are used to help remove the need to see the 'new' keyword for creating
|
||||
Query and Criteria instances so as to improve readability. </para>
|
||||
|
||||
<para>GeoSpatial queries are also supported and are described more in the
|
||||
section <link linkend="mongo.geospatial">GeoSpatial Queries</link>.</para>
|
||||
|
||||
<para></para>
|
||||
|
||||
@@ -1115,10 +1217,91 @@ import static org.springframework.data.document.mongodb.query.Criteria.query;
|
||||
<para></para>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<section id="mongo.geospatial" lang="">
|
||||
<title>GeoSpatial Queries</title>
|
||||
|
||||
<para></para>
|
||||
<para>MongoDB supports GeoSpatial queries through the use of operators
|
||||
such as <literal>$near</literal>, <literal>$within</literal>, and
|
||||
<literal>$nearSphere</literal>. Methods specific to geospatial queries
|
||||
are available on the <classname>Criteria</classname> class. There are
|
||||
also a few shape classes, <classname>Box</classname>,
|
||||
<classname>Circle</classname>, and <classname>Point</classname> that are
|
||||
used in conjunction with geospatial related Criteria methods. </para>
|
||||
|
||||
<para>To understand how to perform GeoSpatial queries we will use the
|
||||
following Venue class taken from the integration tests.which relies on
|
||||
using the rich <classname>MappingMongoConverter</classname>.</para>
|
||||
|
||||
<programlisting language="java">@Document(collection="newyork")
|
||||
public class Venue {
|
||||
|
||||
@Id
|
||||
private String id;
|
||||
private String name;
|
||||
private double[] location;
|
||||
|
||||
@PersistenceConstructor
|
||||
Venue(String name, double[] location) {
|
||||
super();
|
||||
this.name = name;
|
||||
this.location = location;
|
||||
}
|
||||
|
||||
public Venue(String name, double x, double y) {
|
||||
super();
|
||||
this.name = name;
|
||||
this.location = new double[] { x, y };
|
||||
}
|
||||
|
||||
public String getName() {
|
||||
return name;
|
||||
}
|
||||
|
||||
public double[] getLocation() {
|
||||
return location;
|
||||
}
|
||||
|
||||
@Override
|
||||
public String toString() {
|
||||
return "Venue [id=" + id + ", name=" + name + ", location="
|
||||
+ Arrays.toString(location) + "]";
|
||||
}
|
||||
}</programlisting>
|
||||
|
||||
<para>To find locations within a circle, the following query can be
|
||||
used.</para>
|
||||
|
||||
<programlisting lang="java">Circle circle = new Circle(-73.99171, 40.738868, 0.01);
|
||||
List<Venue> venues = template.find(new Query(Criteria.where("location").withinCenter(circle)), Venue.class);</programlisting>
|
||||
|
||||
<para>To find venues within a circle using Spherical coordinates the
|
||||
following query can be used</para>
|
||||
|
||||
<programlisting lang="java">Circle circle = new Circle(-73.99171, 40.738868, 0.003712240453784);
|
||||
List<Venue> venues = template.find(new Query(Criteria.where("location").withinCenterSphere(circle)), Venue.class);</programlisting>
|
||||
|
||||
<para>To find venues within a Box the following query can be used</para>
|
||||
|
||||
<programlisting>Box box = new Box(new Point(-73.99756, 40.73083), new Point(-73.988135, 40.741404)); //lower-left then upper-right
|
||||
List<Venue> venues = template.find(new Query(Criteria.where("location").withinBox(box)), Venue.class);</programlisting>
|
||||
|
||||
<para>To find venues near a Point, the following query can be
|
||||
used</para>
|
||||
|
||||
<programlisting>Point point = new Point(-73.99171, 40.738868);
|
||||
List<Venue> venues = template.find(new Query(Criteria.where("location").near(point).maxDistance(0.01)), Venue.class);</programlisting>
|
||||
|
||||
<para>To find venues near a Point using Spherical coordines the
|
||||
following query can be used</para>
|
||||
|
||||
<programlisting>Point point = new Point(-73.99171, 40.738868);
|
||||
List<Venue> venues = template.find(new Query(Criteria.where("location").nearSphere(point).maxDistance(0.003712240453784)), Venue.class);
|
||||
</programlisting>
|
||||
|
||||
<note>
|
||||
<para>Support for the GeoNear command will be provided in the RC
|
||||
release.</para>
|
||||
</note>
|
||||
</section>
|
||||
</section>
|
||||
|
||||
|
||||
Reference in New Issue
Block a user