DATAMONGO-725 - Improve configurability and documentation of TypeMapper on MappingMongoConverter.

Added new attribute type-mapper-ref to the mapping-converter element in spring-mongo-1.3.xsd in order to support the configuration of custom-type-mappers. Removed the unsupported attributes "mongo-ref" and "mongo-template-ref" from the mapping-converter element in spring-mongo-1.3.xsd because they are not considered anymore.

Updated MappingMongoConverterParser to be aware of the new attribute. Added examples for configuring a custom MongoTypeMapper the usage of @typealias to the reference documentation.

Original pull request: spring-projects#61.

Author: Thomas Darimont

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/config/MappingMongoConverterParser.java

@@ -70,6 +70,7 @@
  * @author Jon Brisbin
  * @author Oliver Gierke
  * @author Maciej Walkowiak
+ * @author Thomas Darimont
  */
 public class MappingMongoConverterParser implements BeanDefinitionParser {
 
@@ -105,6 +106,11 @@ public BeanDefinition parse(Element element, ParserContext parserContext) {
 		converterBuilder.addConstructorArgReference(dbFactoryRef);
 		converterBuilder.addConstructorArgReference(ctxRef);
 
+		String typeMapperRef = element.getAttribute("type-mapper-ref");
+		if (StringUtils.hasText(typeMapperRef)) {
+			converterBuilder.addPropertyReference("typeMapper", typeMapperRef);
+		}
+
 		if (conversionsDefinition != null) {
 			converterBuilder.addPropertyValue("customConversions", conversionsDefinition);
 		}

spring-data-mongodb/src/main/resources/org/springframework/data/mongodb/config/spring-mongo-1.3.xsd

@@ -181,10 +181,10 @@ The base package in which to scan for entities annotated with @Document
 					</xsd:appinfo>
 				</xsd:annotation>
 			</xsd:attribute>
-			<xsd:attribute name="mongo-ref" type="mongoRef" use="optional">
+			<xsd:attribute name="type-mapper-ref" type="typeMapperRef" use="optional">
 				<xsd:annotation>
 					<xsd:documentation>
-						The reference to a Mongo. Will default to 'mongo'.
+						The reference to a MongoTypeMapper to be used by this MappingMongoConverter.
 					</xsd:documentation>
 				</xsd:annotation>
 			</xsd:attribute>
@@ -195,13 +195,6 @@ The base package in which to scan for entities annotated with @Document
 					</xsd:documentation>
 				</xsd:annotation>
 			</xsd:attribute>
-			<xsd:attribute name="mongo-template-ref" type="mongoTemplateRef" use="optional">
-				<xsd:annotation>
-					<xsd:documentation source="org.springframework.data.mongodb.core.core.MongoTemplate">
-						The reference to a MongoTemplate. Will default to 'mongoTemplate'.
-					</xsd:documentation>
-				</xsd:annotation>
-			</xsd:attribute>
 			<xsd:attribute name="disable-validation" use="optional">
 				<xsd:annotation>
 					<xsd:documentation source="org.springframework.data.mongodb.core.mapping.event.ValidatingMongoEventListener">
@@ -257,6 +250,17 @@ The name of the Mongo object that determines what server to monitor. (by default
 		</xsd:complexType>
 	</xsd:element>
 
+	<xsd:simpleType name="typeMapperRef">
+		<xsd:annotation>
+			<xsd:appinfo>
+				<tool:annotation kind="ref">
+					<tool:assignable-to type="org.springframework.data.mongodb.core.convert.MongoTypeMapper"/>
+				</tool:annotation>
+			</xsd:appinfo>
+		</xsd:annotation>
+		<xsd:union memberTypes="xsd:string"/>
+	</xsd:simpleType>
+
 	<xsd:simpleType name="mappingContextRef">
 		<xsd:annotation>
 			<xsd:appinfo>

spring-data-mongodb/src/test/java/org/springframework/data/mongodb/config/AbstractMongoConfigurationUnitTests.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2012 the original author or authors.
+ * Copyright 2012-2013 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -23,8 +23,11 @@
 import org.junit.rules.ExpectedException;
 import org.springframework.beans.factory.NoSuchBeanDefinitionException;
 import org.springframework.context.annotation.AnnotationConfigApplicationContext;
+import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 import org.springframework.data.mongodb.MongoDbFactory;
+import org.springframework.data.mongodb.core.convert.MappingMongoConverter;
+import org.springframework.data.mongodb.core.convert.MongoTypeMapper;
 import org.springframework.data.mongodb.core.mapping.BasicMongoPersistentEntity;
 import org.springframework.data.mongodb.core.mapping.Document;
 import org.springframework.data.mongodb.core.mapping.MongoMappingContext;
@@ -37,6 +40,7 @@
  * Unit tests for {@link AbstractMongoConfiguration}.
  * 
  * @author Oliver Gierke
+ * @author Thomas Darimont
  */
 public class AbstractMongoConfigurationUnitTests {
 
@@ -113,6 +117,20 @@ public void lifecycleCallbacksAreInvokedInAppropriateOrder() {
 		assertThat(spElContext.getBeanResolver(), is(notNullValue()));
 	}
 
+	/**
+	 * @see DATAMONGO-725
+	 */
+	@Test
+	public void shouldBeAbleToConfigureCustomTypeMapperViaJavaConfig() {
+
+		AnnotationConfigApplicationContext context = new AnnotationConfigApplicationContext(SampleMongoConfiguration.class);
+		MongoTypeMapper typeMapper = context.getBean(CustomMongoTypeMapper.class);
+		MappingMongoConverter mmc = context.getBean(MappingMongoConverter.class);
+
+		assertThat(mmc, is(notNullValue()));
+		assertThat(mmc.getTypeMapper(), is(typeMapper));
+	}
+
 	private static void assertScanningDisabled(final String value) throws ClassNotFoundException {
 
 		AbstractMongoConfiguration configuration = new SampleMongoConfiguration() {
@@ -138,6 +156,19 @@ protected String getDatabaseName() {
 		public Mongo mongo() throws Exception {
 			return new Mongo();
 		}
+
+		@Bean
+		@Override
+		public MappingMongoConverter mappingMongoConverter() throws Exception {
+			MappingMongoConverter mmc = super.mappingMongoConverter();
+			mmc.setTypeMapper(typeMapper());
+			return mmc;
+		}
+
+		@Bean
+		public MongoTypeMapper typeMapper() {
+			return new CustomMongoTypeMapper();
+		}
 	}
 
 	@Document

spring-data-mongodb/src/test/java/org/springframework/data/mongodb/config/CustomMongoTypeMapper.java

@@ -0,0 +1,23 @@
+/*
+ * Copyright 2013 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.data.mongodb.config;
+
+import org.springframework.data.mongodb.core.convert.DefaultMongoTypeMapper;
+
+/**
+ * @author Thomas Darimont
+ */
+class CustomMongoTypeMapper extends DefaultMongoTypeMapper {}

spring-data-mongodb/src/test/java/org/springframework/data/mongodb/config/MappingMongoConverterParserIntegrationTests.java

@@ -31,6 +31,8 @@
 import org.springframework.core.convert.converter.GenericConverter;
 import org.springframework.core.io.ClassPathResource;
 import org.springframework.data.mongodb.core.convert.CustomConversions;
+import org.springframework.data.mongodb.core.convert.MappingMongoConverter;
+import org.springframework.data.mongodb.core.convert.MongoTypeMapper;
 import org.springframework.data.mongodb.core.mapping.Account;
 import org.springframework.data.mongodb.core.mapping.CamelCaseAbbreviatingFieldNamingStrategy;
 import org.springframework.data.mongodb.repository.Person;
@@ -42,6 +44,7 @@
  * Integration tests for {@link MappingMongoConverterParser}.
  * 
  * @author Oliver Gierke
+ * @author Thomas Darimont
  */
 public class MappingMongoConverterParserIntegrationTests {
 
@@ -61,6 +64,15 @@ public void allowsDbFactoryRefAttribute() {
 		factory.getBean("converter");
 	}
 
+	@Test
+	public void hasCustomTypeMapper() {
+
+		MappingMongoConverter converter = factory.getBean("converter", MappingMongoConverter.class);
+		MongoTypeMapper customMongoTypeMapper = factory.getBean(CustomMongoTypeMapper.class);
+
+		assertThat(converter.getTypeMapper(), is(customMongoTypeMapper));
+	}
+
 	@Test
 	public void scansForConverterAndSetsUpCustomConversionsAccordingly() {
 

spring-data-mongodb/src/test/java/org/springframework/data/mongodb/config/MappingMongoConverterParserValidationIntegrationTests.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2012 the original author or authors.
+ * Copyright 2012-2013 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -33,6 +33,7 @@
  * 
  * @see DATAMONGO-36
  * @author Maciej Walkowiak
+ * @author Thomas Darimont
  */
 public class MappingMongoConverterParserValidationIntegrationTests {
 
@@ -65,4 +66,11 @@ public void validatingEventListenersIsNotCreatedWhenDisabled() {
 		reader.loadBeanDefinitions(new ClassPathResource("namespace/converter-validation-disabled.xml"));
 		factory.getBean(BeanNames.VALIDATING_EVENT_LISTENER);
 	}
+
+	@Test
+	public void validatingEventListenerCreatedWithCustomTypeMapperConfig() {
+
+		reader.loadBeanDefinitions(new ClassPathResource("namespace/converter-custom-typeMapper.xml"));
+		assertThat(factory.getBean(BeanNames.VALIDATING_EVENT_LISTENER), is(not(nullValue())));
+	}
 }

spring-data-mongodb/src/test/resources/namespace/converter-custom-typeMapper.xml

@@ -0,0 +1,11 @@
+<?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:mongo="http://www.springframework.org/schema/data/mongo"
+	xsi:schemaLocation="http://www.springframework.org/schema/data/mongo http://www.springframework.org/schema/data/mongo/spring-mongo.xsd
+			 http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd">
+
+	<mongo:mapping-converter type-mapper-ref="customMongoTypeMapper"/>
+
+	<bean name="customMongoTypeMapper" class="org.springframework.data.mongodb.config.CustomMongoTypeMapper"/>
+</beans>

spring-data-mongodb/src/test/resources/namespace/converter.xml

@@ -5,12 +5,14 @@
 	xsi:schemaLocation="http://www.springframework.org/schema/data/mongo http://www.springframework.org/schema/data/mongo/spring-mongo.xsd
 		http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd">
 
-	<mongo:mapping-converter id="converter" db-factory-ref="factory">
+	<mongo:mapping-converter id="converter" db-factory-ref="factory" type-mapper-ref="customMongoTypeMapper">
 		<mongo:custom-converters base-package="org.springframework.data.mongodb.config" />
 	</mongo:mapping-converter>
 
 	<mongo:db-factory id="factory" />
 
 	<mongo:mapping-converter id="abbreviatingConverter" abbreviate-field-names="true" />
+	
+	<bean name="customMongoTypeMapper" class="org.springframework.data.mongodb.config.CustomMongoTypeMapper"/>
 
 </beans>

spring-data-mongodb/src/test/resources/template-mapping.xml

@@ -35,8 +35,7 @@
     <constructor-arg name="mongoConverter" ref="mappingConverter1"/>
   </bean>
 
-  <mongo:mapping-converter id="mappingConverter2" base-package="org.springframework.data.mongodb.core.mapping"
-      mongo-template-ref="mongoTemplate2">
+  <mongo:mapping-converter id="mappingConverter2" base-package="org.springframework.data.mongodb.core.mapping">
       <mongo:custom-converters>
         <mongo:converter>
           <bean class="org.springframework.data.mongodb.core.PersonReadConverter"/>

src/docbkx/reference/mongodb.xml

@@ -1057,6 +1057,77 @@ mongoTemplate.save(sample);
         instance of that interface can be configured at the
         <classname>DefaultMongoTypeMapper</classname> which can be configured
         in turn on <classname>MappingMongoConverter</classname>.</para>
+
+        <example>
+          <title>Defining a TypeAlias for an Entity</title>
+
+          <programlisting language="java">@TypeAlias("pers")
+class Person {
+
+}</programlisting>
+
+          <para>Note that the resulting document will contain
+          <code>"pers"</code> as the value in the <code>_class</code>
+          Field.</para>
+        </example>
+      </simplesect>
+
+      <simplesect>
+        <title>Configuring custom type mapping</title>
+
+        <para>The following example demonstrates how to configure a custom
+        <classname>MongoTypeMapper</classname> in
+        <classname>MappingMongoConverter</classname>.</para>
+
+        <example>
+          <title>Configuring a custom MongoTypeMapper via Spring Java
+          Config</title>
+
+          <programlisting language="java">class CustomMongoTypeMapper extends DefaultMongoTypeMapper {
+  //implement custom type mapping here
+}</programlisting>
+
+          <programlisting language="java">@Configuration
+class SampleMongoConfiguration extends AbstractMongoConfiguration {
+
+    @Override
+    protected String getDatabaseName() {
+        return "database";
+    }
+
+    @Override
+    public Mongo mongo() throws Exception {
+        return new Mongo();
+    }
+
+    @Bean
+    @Override
+    public MappingMongoConverter mappingMongoConverter() throws Exception {
+        MappingMongoConverter mmc = super.mappingMongoConverter();
+        mmc.setTypeMapper(customTypeMapper());
+        return mmc;
+    }
+
+    @Bean
+    public MongoTypeMapper customTypeMapper() {
+        return new CustomMongoTypeMapper();
+    }
+}</programlisting>
+
+          <para>Note that we are extending the
+          <classname>AbstractMongoConfiguration</classname> class and override
+          the bean definition of the
+          <classname>MappingMongoConverter</classname> where we configure our
+          custom <classname>MongoTypeMapper</classname>. </para>
+        </example>
+
+        <example>
+          <title>Configuring a custom MongoTypeMapper via XML</title>
+
+          <programlisting language="xml">&lt;mongo:mapping-converter type-mapper-ref="customMongoTypeMapper"/&gt;
+
+&lt;bean name="customMongoTypeMapper" class="com.bubu.mongo.CustomMongoTypeMapper"/&gt;</programlisting>
+        </example>
       </simplesect>
     </section>