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