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

added a MongoTemplate to the mapping configuration code sample

Browse Source
This commit is contained in:
Thomas Risberg
2011-04-07 10:54:07 -04:00
parent a86c3409ce
commit 4d79cdc61d
1 changed files with 104 additions and 86 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -1,63 +1,75 @@
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"> <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<chapter id="mongo.mapping"> <chapter id="mongo.mapping">
<title>Mapping support</title> <title>Mapping support</title>
<para>The object mapping support for MongoDB <para>The object mapping support for MongoDB</para>
</para>
<section id="mongodb:mapping-configuration"> <section id="mongodb:mapping-configuration">
<title>MongoDB Mapping Configuration</title> <title>MongoDB Mapping Configuration</title>
<para>Spring's Mongo namespace enables you to easily enable mapping functionality</para> <para>Spring's Mongo namespace enables you to easily enable mapping
functionality</para>
<example> <example>
<title>XML schema to configure MongoDB mapping support</title> <title>XML schema to configure MongoDB mapping support</title>
<programlisting language="xml"><![CDATA[<?xml version="1.0" encoding="UTF-8"?> <programlisting language="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
<beans xmlns="http://www.springframework.org/schema/beans" &lt;beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:context="http://www.springframework.org/schema/context" xmlns:context="http://www.springframework.org/schema/context"
xmlns:mongo="http://www.springframework.org/schema/data/mongo" xmlns:mongo="http://www.springframework.org/schema/data/mongo"
xsi:schemaLocation="http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-3.0.xsd xsi:schemaLocation="http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-3.0.xsd
http://www.springframework.org/schema/data/mongo http://www.springframework.org/schema/data/mongo/spring-mongo-1.0.xsd http://www.springframework.org/schema/data/mongo http://www.springframework.org/schema/data/mongo/spring-mongo-1.0.xsd
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd"> http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd"&gt;
<!-- Default bean name is 'mongo' --> &lt;!-- Default bean name is 'mongo' --&gt;
<mongo:mongo host="localhost" port="27017"/> &lt;mongo:mongo host="localhost" port="27017"/&gt;
<!-- by default look for a Mongo object named 'mongo' --> &lt;!-- by default look for a Mongo object named 'mongo' - default name used for the converter is 'mappingConverter' --&gt;
<mongo:mapping-converter base-package="com.mycompany.domain"/> &lt;mongo:mapping-converter base-package="com.mycompany.domain"/&gt;
</beans]]> &lt;!-- set the mapping converter to be used by the MongoTemplate --&gt;
&lt;bean id="mongoTemplate" class="org.springframework.data.document.mongodb.MongoTemplate"&gt;
&lt;constructor-arg name="mongo" ref="mongo" /&gt;
&lt;constructor-arg name="databaseName" value="test" /&gt;
&lt;constructor-arg name="defaultCollectionName" value="myCollection" /&gt;
&lt;constructor-arg name="mongoConverter" ref="mappingConverter"/&gt;
&lt;/bean&gt;
&lt;/beans
</programlisting> </programlisting>
</example> </example>
<para>This sets up the right objects in the ApplicationContext to perform the full gamut <para>This sets up the right objects in the ApplicationContext to perform
of mapping operations. The <code>base-package</code> property tells it where to scan for the full gamut of mapping operations. The <code>base-package</code>
classes annotated with the <classname>@org.springframework.data.document.mongodb.mapping.Document</classname> property tells it where to scan for classes annotated with the
annotation. <classname>@org.springframework.data.document.mongodb.mapping.Document</classname>
</para> annotation.</para>
</section> </section>
<section id="mongodb:mapping-usage"> <section id="mongodb:mapping-usage">
<title>Mapping Framework Usage</title> <title>Mapping Framework Usage</title>
<para>To take full advantage of the object mapping functionality inside the Spring Data/MongoDB support, <para>To take full advantage of the object mapping functionality inside
you should annotate your mapped objects with the <classname>@org.springframework.data.document.mongodb.mapping.Document</classname> the Spring Data/MongoDB support, you should annotate your mapped objects
annotation. Although it is not necessary for the mapping framework to have this annotation (your POJOs with the
will be mapped correctly, even without any annotations), it allows the classpath scanner to find and <classname>@org.springframework.data.document.mongodb.mapping.Document</classname>
pre-process your domain objects to extract the necessary metadata. If you don't use this annotation, annotation. Although it is not necessary for the mapping framework to have
your application will take a slight performance hit the first time you store a domain object because the this annotation (your POJOs will be mapped correctly, even without any
mapping framework needs to build up its internal metadata model so it knows about the properties of your annotations), it allows the classpath scanner to find and pre-process your
domain object and how to persist them. domain objects to extract the necessary metadata. If you don't use this
</para> annotation, your application will take a slight performance hit the first
time you store a domain object because the mapping framework needs to
build up its internal metadata model so it knows about the properties of
your domain object and how to persist them.</para>
<example> <example>
<title>Example domain object</title> <title>Example domain object</title>
<programlisting language="java"><![CDATA[package com.mycompany.domain; <programlisting language="java">package com.mycompany.domain;
@Document @Document
public class Person { public class Person {
@@ -70,27 +82,28 @@ public class Person {
@Indexed @Indexed
private String lastName; private String lastName;
}]]> }
</programlisting> </programlisting>
</example> </example>
<important> <important>
<para>The <classname>@Id</classname> annotation tells the mapper which property you want to use for the <para>The <classname>@Id</classname> annotation tells the mapper which
MongoDB <code>_id</code> property and the <classname>@Indexed</classname> annotation tells the mapping property you want to use for the MongoDB <code>_id</code> property and
framework to call <code>ensureIndex</code> on that property of your document, making searches faster. the <classname>@Indexed</classname> annotation tells the mapping
</para> framework to call <code>ensureIndex</code> on that property of your
document, making searches faster.</para>
</important> </important>
<section id="mongodb:mapping-usage:indexes"> <section id="mongodb:mapping-usage:indexes">
<title>Compound Indexes</title> <title>Compound Indexes</title>
<para>Compound indexes are also supported. They are defined at the class level, rather than on indidvidual <para>Compound indexes are also supported. They are defined at the class
properties. Here's an example that creates a compound index of <code>lastName</code> in ascending order level, rather than on indidvidual properties. Here's an example that
and <code>age</code> in descending order: creates a compound index of <code>lastName</code> in ascending order and
<code>age</code> in descending order: <example>
<example>
<title>Example Compound Index Usage</title> <title>Example Compound Index Usage</title>
<programlisting language="java"><![CDATA[package com.mycompany.domain;
<programlisting language="java">package com.mycompany.domain;
@Document @Document
@CompoundIndexes({ @CompoundIndexes({
@@ -104,27 +117,27 @@ public class Person {
private String firstName; private String firstName;
private String lastName; private String lastName;
}]]> }
</programlisting> </programlisting>
</example> </example></para>
</para>
</section> </section>
<section id="mongodb:mapping-usage:references"> <section id="mongodb:mapping-usage:references">
<title>Using DBRefs</title> <title>Using DBRefs</title>
<para>The mapping framework doesn't have to store child objects embedded within the document. You can also <para>The mapping framework doesn't have to store child objects embedded
store them separately and use a DBRef to refer to that document. When the object is loaded from MongoDB, within the document. You can also store them separately and use a DBRef
those references will be eagerly resolved and you will get back a mapped object that looks the same as if to refer to that document. When the object is loaded from MongoDB, those
it had been stored embedded within your master document. references will be eagerly resolved and you will get back a mapped
</para> object that looks the same as if it had been stored embedded within your
master document.</para>
<para>Here's an example of using a DBRef to refer to a specific document that exists independently of the <para>Here's an example of using a DBRef to refer to a specific document
object in which it is referenced (both classes are shown in-line for brevity's sake): that exists independently of the object in which it is referenced (both
</para> classes are shown in-line for brevity's sake):</para>
<example> <example>
<programlisting language="java"><![CDATA[ <programlisting language="java">
@Document @Document
public class Account { public class Account {
@@ -142,69 +155,74 @@ public class Person {
@Indexed @Indexed
private Integer ssn; private Integer ssn;
@DBRef @DBRef
private List<Account> accounts; private List&lt;Account&gt; accounts;
}]]> }
</programlisting> </programlisting>
</example> </example>
<para>There's no need to use something like <code>@OneToMany</code> because the mapping framework sees that <para>There's no need to use something like <code>@OneToMany</code>
you're wanting a one-to-many relationship because there is a List of objects. When the object is stored because the mapping framework sees that you're wanting a one-to-many
in MongoDB, there will be a list of DBRefs rather than the <code>Account</code> objects themselves. relationship because there is a List of objects. When the object is
stored in MongoDB, there will be a list of DBRefs rather than the
<important> <code>Account</code> objects themselves. <important>
<para>The mapping framework does not handle cascading saves. If you change an <code>Account</code> object that is <para>The mapping framework does not handle cascading saves. If you
referenced by a <code>Person</code> object, you must save the Account object separately. Calling <code>save</code> change an <code>Account</code> object that is referenced by a
on the <code>Person</code> object will not automatically save the <code>Account</code> objects in the <code>Person</code> object, you must save the Account object
property <code>accounts</code>.</para> separately. Calling <code>save</code> on the <code>Person</code>
</important> object will not automatically save the <code>Account</code> objects
</para> in the property <code>accounts</code>.</para>
</important></para>
</section> </section>
<section id="mongodb:mapping-usage:events"> <section id="mongodb:mapping-usage:events">
<title>Handling Mapping Framework Events</title> <title>Handling Mapping Framework Events</title>
<para>Built into the MongoDB mapping framework are several <classname>org.springframework.context.ApplicationEvent</classname> <para>Built into the MongoDB mapping framework are several
events that your application can respond to by registering special beans in the <code>ApplicationContext</code>. <classname>org.springframework.context.ApplicationEvent</classname>
</para> events that your application can respond to by registering special beans
in the <code>ApplicationContext</code>.</para>
<para>To intercept an object before it goes through the conversion process (which turns your domain object <para>To intercept an object before it goes through the conversion
into a <classname>com.mongodb.DBObject</classname>), you'd register a subclass of <classname>org.springframework.data.document.mongodb.mapping.event.AbstractMappingEventListener</classname> process (which turns your domain object into a
that overrides the <code>onBeforeConvert</code> method. When the event is dispatched, your listener will be <classname>com.mongodb.DBObject</classname>), you'd register a subclass
called and passed the domain object before it goes into the converter. of
</para> <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> <example>
<programlisting language="java"><![CDATA[ <programlisting language="java">
public class BeforeConvertListener<BeforeConvertEvent, Person> extends AbstractMappingEventListener { public class BeforeConvertListener&lt;BeforeConvertEvent, Person&gt; extends AbstractMappingEventListener {
@Override @Override
public void onBeforeConvert(Person p) { public void onBeforeConvert(Person p) {
... does some auditing manipulation, set timestamps, whatever ... ... does some auditing manipulation, set timestamps, whatever ...
} }
} }
]]></programlisting> </programlisting>
</example> </example>
<para>To intercept an object before it goes into the database, you'd register a subclass of <para>To intercept an object before it goes into the database, you'd
<classname>org.springframework.data.document.mongodb.mapping.event.AbstractMappingEventListener</classname> register a subclass of
that overrides the <code>onBeforeSave</code> method. When the event is dispatched, your listener will be <classname>org.springframework.data.document.mongodb.mapping.event.AbstractMappingEventListener</classname>
called and passed the domain object and the converted <classname>com.mongodb.DBObject</classname>. that overrides the <code>onBeforeSave</code> method. When the event is
</para> dispatched, your listener will be called and passed the domain object
and the converted <classname>com.mongodb.DBObject</classname>.</para>
<example> <example>
<programlisting language="java"><![CDATA[ <programlisting language="java">
public class BeforeSaveListener<BeforeSaveEvent, Person> extends AbstractMappingEventListener { public class BeforeSaveListener&lt;BeforeSaveEvent, Person&gt; extends AbstractMappingEventListener {
@Override @Override
public void onBeforeSave(Person p, DBObject dbo) { public void onBeforeSave(Person p, DBObject dbo) {
... change values, delete them, whatever ... ... change values, delete them, whatever ...
} }
} }
]]></programlisting> </programlisting>
</example> </example>
<para>Simply declaring these beans in your Spring ApplicationContext will cause them to be invoked whenever the <para>Simply declaring these beans in your Spring ApplicationContext
event is dispatched. will cause them to be invoked whenever the event is dispatched.</para>
</para>
</section> </section>
</section> </section>
</chapter> </chapter>