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

javadoc/doc changes.

Browse Source
This commit is contained in:
Mark Pollack
2011-04-08 17:50:38 -04:00
parent 7b673f7bc3
commit 4bb2e7a5bd
10 changed files with 465 additions and 120 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -84,7 +84,98 @@
<para>Spring MongoDB support requires MongoDB 1.4 or higher and Java SE 5
or higher. The latest production release (1.8.x as of this writing) is
recommended.</para>
recommended. An easy way to bootstrap setting up a working environment is
to create a Spring based project in <ulink
url="http://www.springsource.com/developer/sts">STS</ulink>.</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
prompted. Then enter a project and a package name such as
org.spring.mongodb.example.</para>
<para>Then add the following to pom.xml dependencies section.</para>
<programlisting lang="xml"> &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.0.0.BUILD-SNAPSHOT&lt;/version&gt;
&lt;/dependency&gt;
&lt;dependency&gt;
&lt;groupId&gt;cglib&lt;/groupId&gt;
&lt;artifactId&gt;cglib&lt;/artifactId&gt;
&lt;version&gt;2.2&lt;/version&gt;
&lt;/dependency&gt;
&lt;dependency&gt;
&lt;groupId&gt;log4j&lt;/groupId&gt;
&lt;artifactId&gt;log4j&lt;/artifactId&gt;
&lt;scope&gt;test&lt;/scope&gt;
&lt;/dependency&gt;</programlisting>
<para>The cglib dependency is there as we will use Spring's Java
configuration style. Also change the version of Spring in the pom.xml to
be </para>
<programlisting lang="xml">&lt;spring.framework.version&gt;3.0.5.RELEASE&lt;/spring.framework.version&gt;</programlisting>
<para>Next, in the org.spring.mongodb package in the sr/ctest/java
directory create a class as shown below.</para>
<programlisting lang="java">package org.spring.mongodb;
import org.springframework.context.annotation.Configuration;
import org.springframework.data.document.mongodb.MongoTemplate;
import org.springframework.data.document.mongodb.config.AbstractMongoConfiguration;
import com.mongodb.Mongo;
@Configuration
public class MongoConfig extends AbstractMongoConfiguration {
@Override
public Mongo mongo() throws Exception {
return new Mongo("localhost");
}
@Override
public MongoTemplate mongoTemplate() throws Exception {
return new MongoTemplate(mongo() , "database", "mongoexample");
}
}</programlisting>
<para>Then create a simple Person class to persist</para>
<programlisting>package org.spring.mongodb;
public class Person {
private String id;
private String name;
public Person(String id, String name) {
this.id = id;
this.name = name;
}
public String getId() {
return id;
}
public String getName() {
return name;
}
@Override
public String toString() {
return "Person [id=" + id + ", name=" + name + "]";
}
}</programlisting>
<para>And a main application to run</para>
<programlisting></programlisting>
</section>
<section id="mongodb-connectors">
@@ -419,6 +510,16 @@ public class AppConfig {
</note>
</section>
</section>
<section>
<title>Configuring the MongoConverter</title>
<para>The SimpleMongoConverter is used by default but if you want to use
the more feature rich MappingMongoConverter there are a few steps.
Please refer to the <link
linkend="mongodb.mapping-configuration">mapping section</link> for more
information.</para>
</section>
</section>
<section>
@@ -426,7 +527,7 @@ public class AppConfig {
<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. </para>
MongoDB.</para>
<para>Given a simple class such as Person</para>
@@ -490,7 +591,7 @@ Number of people = : 0</programlisting>
<para>There was implicit conversion using SimpleMongoConverter between a
String and ObjectId as stored in the database and recognizing a convention
of the property "Id" name. </para>
of the property "Id" name.</para>
<note>
<para>This example is meant to show the use of save, update and remove
@@ -521,7 +622,7 @@ Number of people = : 0</programlisting>
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>
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
@@ -549,8 +650,7 @@ import static org.springframework.data.document.mongodb.query.Criteria.query;
</programlisting>
</example>
<para>The four save operations available to you are listed below.
</para>
<para>The four save operations available to you are listed below.</para>
<para><itemizedlist>
<listitem>
@@ -580,7 +680,7 @@ import static org.springframework.data.document.mongodb.query.Criteria.query;
</listitem>
</itemizedlist></para>
<para>A similar set of insert operations is listed below </para>
<para>A similar set of insert operations is listed below</para>
<para><itemizedlist>
<listitem>
@@ -810,7 +910,7 @@ import static org.springframework.data.document.mongodb.query.Update
<title>Methods for removing documents</title>
<para>You can use several overloaded methods to remove an object from
the database. </para>
the database.</para>
<para><itemizedlist>
<listitem>
@@ -863,15 +963,11 @@ import static org.springframework.data.document.mongodb.query.Update
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>
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>
<para>GeoSpatial Queries</para>
<section id="mongodb-template-query">
<title>Querying documents in a collection</title>
@@ -886,12 +982,11 @@ import static org.springframework.data.document.mongodb.query.Update
<title>Querying for 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;
...
...
List&lt;Person&gt; result = mongoTemplate.find(
new Query(where("age").lt(50).and("accounts.balance").gt(1000.00d)),
Person.class);
List&lt;Person&gt; result = mongoTemplate.find(query(where("age").lt(50).and("accounts.balance").gt(1000.00d)),Person.class);
</programlisting>
</example>
@@ -903,7 +998,8 @@ import static org.springframework.data.document.mongodb.query.Update
<classname>Criteria</classname> object. We recommend using a static
import for
<classname>org.springframework.data.document.mongodb.query.Criteria.where</classname>
to make the query more readable.</para>
and <literal>Query.query</literal> to make the query more
readable.</para>
<para>This query should return a list of Person objects that meet the
specified criteria. The Criteria class has the following methods that
@@ -1011,15 +1107,56 @@ import static org.springframework.data.document.mongodb.query.Update
<literal>key</literal> to the current
<classname>Criteria</classname> and retuns the newly created
one</para>
<para />
</listitem>
</itemizedlist>
</para>
</section>
<para>The <classname>Query</classname> class has some additional methods
used to provide options for the query.</para>
<para>There are also methods on the Criteria class for geospatial
queries. Here is al isting but look at the section on <link
linkend="mongo.geospatial">GeoSpatial Queries</link> to see them in
action.</para>
<itemizedlist>
<listitem>
<para><literal>Criteria</literal> <emphasis role="bold">withinCenter
</emphasis> <literal>(Circle circle)</literal>Creates a geospatial
criterion using <literal>$within $center</literal> operators</para>
</listitem>
<listitem>
<para><literal>Criteria</literal> <emphasis
role="bold">withinCenterSphere </emphasis> <literal>(Circle circle)
</literal>Creates a geospatial criterion using <literal>$within
$center</literal> operators. This is only available for Mongo 1.7
and higher. </para>
</listitem>
<listitem>
<para><literal>Criteria</literal> <emphasis role="bold">withinBox
</emphasis> <literal>(Box box)</literal>Creates a geospatial
criterion using a <literal>$within $box</literal> operation
<literal /></para>
</listitem>
<listitem>
<para><literal>Criteria</literal> <emphasis role="bold">near
</emphasis> <literal>(Point point)</literal>Creates a geospatial
criterion using a <literal>$near </literal>operation</para>
</listitem>
<listitem>
<para><literal>Criteria</literal> <emphasis role="bold">nearSphere
</emphasis> <literal>(Point point) </literal>Creates a geospatial
criterion using <literal>$nearSphere$center</literal> operations.
This is only available for Mongo 1.7 and higher. </para>
</listitem>
</itemizedlist>
<para> The <classname>Query</classname> class has some additional
methods used to provide options for the query.</para>
<section>
<title>Methods for the Query class</title>
@@ -1226,7 +1363,7 @@ import static org.springframework.data.document.mongodb.query.Update
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>
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
@@ -1308,9 +1445,8 @@ List&lt;Venue&gt; venues = template.find(new Query(Criteria.where("location").ne
<section>
<title>Index and Collection managment</title>
<para>index</para>
<para>collection</para>
<para>MongoTemplate provides a few methods for managing indexes and
collections.</para>
<section>
<title>Methods for creating an Index</title>
@@ -1342,7 +1478,13 @@ List&lt;Venue&gt; venues = template.find(new Query(Criteria.where("location").ne
</listitem>
</itemizedlist></para>
<para></para>
<para>You can create both standard indexes and geospatial indexes using
the classes <classname>IndexDefinition</classname> and
<classname>GeoSpatialIndex</classname> respectfully. For example, given
the Venue class defined in a previous section, you would declare a
geospatial query as shown below</para>
<programlisting>mongoTemplate.ensureIndex(new GeospatialIndex("location"));</programlisting>
</section>
<section>
@@ -1426,7 +1568,10 @@ List&lt;Venue&gt; venues = template.find(new Query(Criteria.where("location").ne
<section>
<title>Executing Commands</title>
<para>exec plain old JS.</para>
<para>You can also get at the Mongo driver's collection.command( ) method
using the executeCommand methods on MongoTemplate. These will also perform
exception translation into Spring's Data Access Exception
hierarchy.</para>
<section>
<title>Methods for executing commands</title>
@@ -1444,50 +1589,101 @@ List&lt;Venue&gt; venues = template.find(new Query(Criteria.where("location").ne
jsonCommand) </literal> Execute the a MongoDB command expressed as
a JSON string.</para>
</listitem>
<listitem>
<para><literal>&lt;T&gt; T</literal> <emphasis role="bold">execute
</emphasis> <literal>(CollectionCallback&lt;T&gt; action)
</literal> Executes the given CollectionCallback on the default
collection.</para>
</listitem>
<listitem>
<para><literal>&lt;T&gt; T</literal> <emphasis role="bold">execute
</emphasis> <literal>(String collectionName,
CollectionCallback&lt;T&gt; action) </literal> Executes the given
CollectionCallback on the collection of the given name.update
using the $addToSet update modifier</para>
</listitem>
<listitem>
<para><literal>&lt;T&gt; T</literal> <emphasis role="bold">execute
</emphasis> <literal>(DbCallback&lt;T&gt; action) </literal>
Executes a DbCallback translating any exceptions as
necessary.</para>
</listitem>
<listitem>
<para><literal>&lt;T&gt; T</literal> <emphasis
role="bold">executeInSession </emphasis>
<literal>(DbCallback&lt;T&gt; action) </literal> Executes the
given DbCallback within the same connection to the database so as
to ensure consistency in a write heavy environment where you may
read the data that you wrote.</para>
</listitem>
</itemizedlist></para>
<para></para>
</section>
</section>
<section>
<section id="mongodb.mapping-usage.events">
<title>Lifecycle Events</title>
<para>The lifecycle events are....</para>
<para>Built into the MongoDB mapping framework are several
<classname>org.springframework.context.ApplicationEvent</classname> events
that your application can respond to by registering special beans in the
<code>ApplicationContext</code>. By being based off Spring's
ApplicationContext event infastructure this enables other products, such
as Spring Integration, to easily receive these events as they are a well
known eventing mechanism in Spring based applications.</para>
<para>To intercept an object before it goes through the conversion process
(which turns your domain object into a
<classname>com.mongodb.DBObject</classname>), you'd register a subclass of
<classname>org.springframework.data.document.mongodb.mapping.event.AbstractMappingEventListener</classname>
that overrides the <code>onBeforeConvert</code> method. When the event is
dispatched, your listener will be called and passed the domain object
before it goes into the converter.</para>
<example>
<programlisting language="java">
public class BeforeConvertListener&lt;BeforeConvertEvent, Person&gt; extends AbstractMappingEventListener {
@Override
public void onBeforeConvert(Person p) {
... does some auditing manipulation, set timestamps, whatever ...
}
}
</programlisting>
</example>
<para>To intercept an object before it goes into the database, you'd
register a subclass of
<classname>org.springframework.data.document.mongodb.mapping.event.AbstractMappingEventListener</classname>
that overrides the <code>onBeforeSave</code> method. When the event is
dispatched, your listener will be called and passed the domain object and
the converted <classname>com.mongodb.DBObject</classname>.</para>
<example>
<programlisting language="java">
public class BeforeSaveListener&lt;BeforeSaveEvent, Person&gt; extends AbstractMappingEventListener {
@Override
public void onBeforeSave(Person p, DBObject dbo) {
... change values, delete them, whatever ...
}
}
</programlisting>
</example>
<para>Simply declaring these beans in your Spring ApplicationContext will
cause them to be invoked whenever the event is dispatched.</para>
<para>The list of callback methods that are present in
AbstractMappingEventListener are</para>
<itemizedlist>
<listitem>
<para><methodname>onBeforeConvert</methodname> - called in
MongoTemplate insert, insertList and save operations before the object
is converted to a DBObject using a MongoConveter.</para>
</listitem>
<listitem>
<para><methodname>onBeforeSave</methodname> - called in MongoTemplate
insert, insertList and save operations <emphasis>before</emphasis>
inserting/saving the DBObject in the database.</para>
</listitem>
<listitem>
<para><methodname>onAfterSave</methodname> - called in MongoTemplate
insert, insertList and save operations <emphasis>after</emphasis>
inserting/saving the DBObject in the database.</para>
</listitem>
<listitem>
<para><methodname>onAfterLoad</methodname> - called in MongoTempnlate
find, findAndRemove, findOne and getCollection methods after the
DBObject is retrieved from the database.</para>
</listitem>
<listitem>
<para><methodname>onAfterConvert</methodname> - called in
MongoTempnlate find, findAndRemove, findOne and getCollection methods
after the DBObject retrieved from the database was converted to a
POJO.</para>
</listitem>
</itemizedlist>
</section>
<section label="mongo.exception">
<section id="mongo.exception" label="">
<title>Exception Translation</title>
<para>The Spring framework provides exception translation for a wide
@@ -1508,7 +1704,7 @@ List&lt;Venue&gt; venues = template.find(new Query(Criteria.where("location").ne
sure that you will be able to catch all database related exception within
a single try-catch block. Note, that not all exceptions thrown by the
MongoDB driver inherit from the MongoException class. The inner exception
and message are preserved so no information is lost. </para>
and message are preserved so no information is lost.</para>
<para>Some of the mappings performed by the MongoExceptionTranslator are:
com.mongodb.Network to DataAccessResourceFailureException and